1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Copyright 1989 AT&T 44.\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved 45.\" Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved 46.\" Copyright (c) 2014, Joyent, Inc. All rights Reserved. 47.\" Copyright (c) 2014 by Delphix. All rights reserved. 48.\" Copyright 2021 Oxide Computer Company 49.\" 50.Dd October 24, 2021 51.Dt DD 8 52.Os 53.Sh NAME 54.Nm dd 55.Nd convert and copy a file 56.Sh SYNOPSIS 57.Nm 58.Op Ar operand Ns = Ns Ar value 59.Ar ... 60.Sh DESCRIPTION 61The 62.Nm 63utility copies the specified input file to the specified output 64with possible conversions. 65The standard input and output are used by default. 66The input and output block sizes may be specified to take advantage of raw 67physical I/O. 68Sizes are specified in bytes; a number may end with 69.Sy k , 70.Sy b , 71or 72.Sy w 73to specify multiplication by 1024, 512, or 2, respectively. 74Numbers may also be separated by 75.Sy x 76to indicate multiplication. 77.Pp 78The 79.Nm 80utility reads the input one block at a time, using the specified 81input block size. 82.Nm 83then processes the block of data actually returned, 84which could be smaller than the requested block size unless the input flag 85.Ar fullblock 86is used. 87.Nm 88applies any conversions that have been specified and writes the resulting data 89to the output in blocks of the specified output block size. 90.Pp 91.Cm cbs 92is used only if 93.Cm ascii , 94.Cm asciib , 95.Cm unblock , 96.Cm ebcdic , 97.Cm ebcdicb , 98.Cm ibm , 99.Cm ibmb , 100or 101.Cm block 102conversion is specified. 103In the first two cases, 104.Cm cbs 105characters are copied into the conversion buffer, any specified character 106mapping is done, trailing blanks are trimmed, and a 107.Cm NEWLINE 108is added before sending the line to output. 109In the last three cases, characters up to 110.Cm NEWLINE 111are read into the conversion buffer and blanks are added to make up an output 112record of size 113.Cm cbs . 114.Cm ASCII 115files are presumed to contain 116.Cm NEWLINE 117characters. 118If 119.Cm cbs 120is unspecified or 121.Cm 0 , 122the 123.Cm ascii , 124.Cm asciib , 125.Cm ebcdic , 126.Cm ebcdicb , 127.Cm ibm , 128and 129.Cm ibmb 130options convert the character set without changing the input file's block 131structure. 132The 133.Cm unblock 134and 135.Cm block 136options become a simple file copy. 137.Pp 138After completion, 139.Nm 140reports the number of whole and partial input and output blocks. 141.Sh OPERANDS 142The following operands are supported: 143.Bl -tag -width "if=file" 144.It Cm if= Ns Ar file 145.Pp 146Specifies the input path. 147Standard input is the default. 148.It Cm of= Ns Ar file 149.Pp 150Specifies the output path. 151Standard output is the default. 152If the 153.Cm seek Ns = Ns Ar expr 154conversion is not also specified, the output file will be truncated before 155the copy begins, unless 156.Cm conv Ns = Ns Ar notrunc 157is specified. 158If 159.Cm seek Ns = Ns Ar expr 160is specified, but 161.Cm conv Ns = Ns Ar notrunc 162is not, the effect of the copy will be to preserve the blocks in the output 163file over which 164.Nm 165seeks, but no other portion of the output file will be preserved. 166(If the size of the seek plus the size of the input file is less than the 167previous size of the output file, the output file is shortened by the copy.) 168.It Cm ibs Ns = Ns Ar n 169.Pp 170Specifies the input block size in 171.Ar n 172bytes (default is 512). 173.It Cm obs Ns = Ns Ar n 174.Pp 175Specifies the output block size in 176.Ar n 177bytes (default is 512). 178.It Cm bs Ns = Ns Ar n 179.Pp 180Sets both input and output block sizes to 181.Ar n 182bytes, superseding 183.Cm ibs Ns = 184and 185.Cm obs Ns = . 186If no conversion other than 187.Cm sync , 188.Cm noerror , 189and 190.Cm notrunc 191is specified, each input block is copied to the output as a 192single block without aggregating short blocks. 193.It Cm cbs Ns = Ns Ar n 194.Pp 195Specifies the conversion block size for 196.Cm block 197and 198.Cm unblock 199in bytes by 200.Ar n 201(default is 202.Cm 0 Ns ). 203If 204.Cm cbs Ns = 205is omitted or given a value of 206.Cm 0 , 207using 208.Cm block 209or 210.Cm unblock 211produces unspecified results. 212.Pp 213This option is used only if 214.Cm ASCII 215or 216.Cm EBCDIC 217conversion is specified. 218For the 219.Cm ascii 220and 221.Cm asciib 222operands, the input is handled as described for the 223.Cm unblock 224operand except that characters are converted to 225.Cm ASCII 226before the trailing 227.Cm SPACE 228characters are deleted. 229For the 230.Cm ebcdic , 231.Cm ebcdicb , 232.Cm ibm , 233and 234.Cm ibmb 235operands, the input is handled as described for the 236.Cm block 237operand except that the characters are converted to 238.Cm EBCDIC 239or IBM 240.Cm EBCDIC 241after the trailing 242.Cm SPACE 243characters are added. 244.It Cm files Ns = Ns Ar n 245.Pp 246Copies and concatenates 247.Ar n 248input files before terminating (makes sense 249only where input is a magnetic tape or similar device). 250.It Cm skip Ns = Ns Ar n 251.Pp 252Skips 253.Ar n 254input blocks (using the specified input block size) before starting to copy. 255On seekable files, the implementation reads the blocks or seeks past them. 256On non-seekable files, the blocks are read and the data is discarded. 257.It Cm iseek Ns = Ns Ar n 258.Pp 259Seeks 260.Ar n 261blocks from beginning of input file before copying (appropriate 262for disk files, where 263.Cm skip 264can be incredibly slow). 265.It Cm oseek Ns = Ns Ar n 266.Pp 267Seeks 268.Ar n 269blocks from beginning of output file before copying. 270.It Cm seek Ns = Ns Ar n 271.Pp 272Skips 273.Ar n 274blocks (using the specified output block size) from beginning of 275output file before copying. 276On non-seekable files, existing blocks are read and space from the current 277end-of-file to the specified offset, if any, is filled with null bytes. 278On seekable files, the implementation seeks to the specified 279offset or reads the blocks as described for non-seekable files. 280.It Cm ostride Ns = Ns Ar n 281.Pp 282Writes every 283.Ar n Ns 284th block (using the specified output block size) when writing output. 285Skips 286.Ar n 287- 1 blocks after writing each record. 288.It Cm istride Ns = Ns Ar n 289.Pp 290Reads every 291.Ar n Ns 292th block (using the specified input block size) when reading input. 293Skips 294.Ar n 295- 1 blocks after reading each record. 296.It Cm stride Ns = Ns Ar n 297.Pp 298Reads every 299.Ar n Ns 300th block (using the specified input block size) when reading input. 301Skips 302.Ar n 303- 1 blocks after reading each record. 304Also writes every 305.Ar n Ns 306th block (using the specified output block size) when writing output. 307Skips 308.Ar n 309- 1 blocks after writing each record. 310.It Cm count Ns = Ns Ar n 311.Pp 312Copies only 313.Ar n 314input blocks. 315.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value Ns ... 316.Pp 317Where 318.Ar value Ns 319s are comma-separated symbols from the following list: 320.Bl -hang 321.It Cm ascii 322Converts 323.Cm EBCDIC 324to 325.Cm ASCII . 326.sp 327.It Cm asciib 328Converts 329.Cm EBCDIC 330to 331.Cm ASCII 332using 333.Cm BSD Ns 334-compatible character translations. 335.It Cm ebcdic 336Converts 337.Cm ASCII 338to 339.Cm EBCDIC . 340If converting fixed-length 341.Cm ASCII 342records without 343.Cm NEWLINE Ns 344s, sets up a pipeline with 345.Nm 346.Cm conv Ns = Ns Ar unblock 347beforehand. 348.It Cm ebcdicb 349Converts 350.Cm ASCII 351to 352.Cm EBCDIC 353using 354.Cm BSD Ns 355-compatible character translations. 356If converting fixed-length 357.Cm ASCII 358records without 359.Cm NEWLINE Ns 360s, sets up a pipeline with 361.Nm 362.Cm conv Ns = Ns Ar unblock 363beforehand. 364.It Cm ibm 365Slightly different map of 366.Cm ASCII 367to 368.Cm EBCDIC . 369If converting fixed-length 370.Cm ASCII 371records without 372.Cm NEWLINE Ns 373s, sets up a pipeline with 374.Nm 375.Cm conv Ns = Ns Ar unblock 376beforehand. 377.It Cm ibmb 378Slightly different map of 379.Cm ASCII 380to 381.Cm EBCDIC 382using 383.Cm BSD Ns 384-compatible character translations. 385If converting fixed-length 386.Cm ASCII 387records without 388.Cm NEWLINE Ns 389s, sets up a pipeline with 390.Nm 391.Cm conv Ns = Ns Ar unblock 392beforehand. 393.El 394.Pp 395The 396.Cm ascii 397(or 398.Cm asciib Ns ), 399.Cm ebcdic 400(or 401.Cm ebcdicb Ns ), 402and 403.Cm ibm 404(or 405.Cm ibmb ) 406values are mutually exclusive. 407.Bl -hang 408.It Cm block 409Treats the input as a sequence of 410.Cm NEWLINE Ns 411-terminated or 412.Cm EOF Ns 413-terminated variable-length records independent of the input block boundaries. 414Each record is converted to a record with a fixed length specified 415by the conversion block size. 416Any 417.Cm NEWLINE 418character is removed from the input line. 419.Cm SPACE 420characters are appended to lines that are shorter than their conversion block 421size to fill the block. 422Lines that are longer than the conversion block size are truncated to the 423largest number of characters that will fit into that size. 424The number of truncated lines is reported. 425.It Cm unblock 426Converts fixed-length records to variable length. 427Reads a number of bytes equal to the conversion block size (or the number of 428bytes remaining in the input, if less than the conversion block size), 429delete all trailing 430.Cm SPACE 431characters, and append a 432.Cm NEWLINE 433character. 434.El 435.Pp 436The 437.Cm block 438and 439.Cm unblock 440values are mutually exclusive. 441.Bl -hang 442.It Cm lcase 443Maps upper-case characters specified by the 444.Cm LC_CTYPE 445keyword 446.Cm tolower 447to the corresponding lower-case character. 448Characters for which no mapping is specified are not modified by this 449conversion. 450.It Cm ucase 451Maps lower-case characters specified by the 452.Cm LC_CTYPE 453keyword 454.Cm toupper 455to the corresponding upper-case character. 456Characters for which no mapping is specified are not modified by this 457conversion. 458.El 459.Pp 460The 461.Cm lcase 462and 463.Cm ucase 464symbols are mutually exclusive. 465.Bl -hang 466.It Cm swab 467Swaps every pair of input bytes. 468If the current input record is an odd number of bytes, the last byte in the 469input record is ignored. 470.It Cm noerror 471Does not stop processing on an input error. 472When an input error occurs, a diagnostic message is written on standard error, 473followed by the current input and output block counts in the same format as 474used at completion. 475If the 476.Cm sync 477conversion is specified, the missing input is replaced with null 478bytes and processed normally. 479Otherwise, the input block will be omitted from the output. 480.It Cm notrunc 481Does not truncate the output file. 482Preserves blocks in the output file not explicitly written by this invocation 483of 484.Nm . 485(See also the preceding 486.Cm of Ns = Ns Ar file 487operand.) 488.It Cm sync 489Pads every input block to the size of the 490.Cm ibs Ns = 491buffer, appending null bytes. 492(If either 493.Cm block 494or 495.Cm unblock 496is also specified, appends 497.Cm SPACE 498characters, rather than null bytes.) 499.El 500.It Cm iflag Ns = Ns Ar value Ns Op , Ns Ar value ... 501.Pp 502Where 503.Ar value Ns 504s are comma-separated symbols from the following list which 505affect the behavior of reading from the input file: 506.Bl -hang 507.It Cm fullblock 508Accumulate full blocks of input. 509.El 510.It Cm oflag Ns = Ns Ar value Ns Op , Ns Ar value ... 511.ad 512.sp .6 513Where 514.Ar value Ns 515s are comma-separated symbols from the following list which 516affect the behavior of writing the output file: 517.Bl -hang 518.It Cm dsync 519The output file is opened with the 520.Cm O_DSYNC 521flag set. 522All data writes will be synchronous. 523For more information on 524.Cm O_DSYNC 525see 526.Xr fcntl.h 3HEAD . 527.It Cm sync 528The output file is opened with the 529.Cm O_SYNC . 530All data and metadata writes will be synchronous. 531For more information on 532.Cm O_SYNC 533see 534.Xr fcntl.h 3HEAD . 535.El 536.It Cm status Ns = Ns Ar type 537Changes the way that 538.Nm 539outputs information about transfers. 540Only one 541.Ar type may be specified. 542The following are valid values for 543.Ar type : 544.Bl -hang 545.It Cm none 546The program will not output any information and statistics about the transfer. 547This includes when 548.Nm 549receives a signal such as 550.Dv SIGINFO 551and 552.Dv SIGUSR1 . 553Only errors will be emitted. 554.It Cm noxfer 555When printing statistical information such as when the program terminates or in 556response to a signal, only print information about the number of records and 557none of the statistics about the transfer 558.Pq total bytes, total time, and throughput . 559.It Cm progress 560Once a second, output the normal 561.Nm 562transfer statistics that include the total number of bytes transferred, time 563elapsed, and average throughput. 564.El 565.El 566.Pp 567If operands other than 568.Cm conv Ns = 569and 570.Cm oflag Ns = 571are specified more than once, the last specified 572.Cm operand Ns = Ns Ar value 573is used. 574.Pp 575For the 576.Cm bs Ns = , 577.Cm cbs Ns = , 578.Cm ibs Ns = , 579and 580.Cm obs Ns = 581operands, the application must supply an expression specifying a size in bytes. 582The expression, 583.Cm expr , 584can be: 585.Bl -enum -offset indent -compact 586.It 587a positive decimal number 588.Pp 589.It 590a positive decimal number followed by 591.Sy k , 592specifying multiplication by 1024 593.Pp 594.It 595a positive decimal number followed by 596.Sy M , 597specifying multiplication by 1024*1024 598.Pp 599.It 600a positive decimal number followed by 601.Sy G , 602specifying multiplication by 1024*1024*1024 603.Pp 604.It 605a positive decimal number followed by 606.Sy T , 607specifying multiplication by 1024*1024*1024*1024 608.Pp 609.It 610a positive decimal number followed by 611.Sy P , 612specifying multiplication by 1024*1024*1024*1024*1024 613.Pp 614.It 615a positive decimal number followed by 616.Sy E , 617specifying multiplication by 1024*1024*1024*1024*1024*1024 618.Pp 619.It 620a positive decimal number followed by 621.Sy Z , 622specifying multiplication by 1024*1024*1024*1024*1024*1024*1024 623.Pp 624.It 625a positive decimal number followed by 626.Sy b , 627specifying multiplication by 512 628.Pp 629.It 630two or more positive decimal numbers (with or without 631.Sy k 632or 633.Sy b ) 634separated by 635.Sy x , 636specifying the product of the indicated values. 637.El 638.Pp 639All of the operands will be processed before any input is read. 640.Sh SIGNALS 641When 642.Nm 643receives either SIGINFO or SIGUSR1, 644.Nm 645will emit the current input and output block counts, total bytes written, 646total time elapsed, and the number of bytes per second to standard error. 647This is the same information format that 648.Nm 649emits when it successfully completes. 650Users may send SIGINFO via their terminal. 651The default character is ^T, see 652.Xr stty 1 653for more information. 654.Pp 655For 656.Sy SIGINT , 657.Nm 658writes status information to standard error before exiting. 659.Nm 660takes the standard action for all other signals. 661.Sh USAGE 662See 663.Xr largefile 7 664for the description of the behavior of 665.Nm 666when encountering files greater than or equal to 2 Gbyte (2^31 bytes). 667.Sh EXIT STATUS 668The following exit values are returned: 669.Bl -tag -width ".It Cm >0" 670.It Cm 0 671The input file was copied successfully. 672.It Cm >0 673An error occurred. 674.El 675.Pp 676If an input error is detected and the 677.Cm noerror 678conversion has not been specified, any partial output block will be written 679to the output file, a diagnostic message will be written, and the copy 680operation will be discontinued. 681If some other error is detected, a diagnostic message will be 682written and the copy operation will be discontinued. 683.Sh EXAMPLES 684.Bl -ohang 685.It Sy Example 1 No Copying from one tape drive to another 686.Pp 687The following example copies from tape drive 688.Sy 0 689to tape drive 690.Sy 1 , 691using a common historical device naming convention. 692.Pp 693.Dl % dd if=/dev/rmt/0h of=/dev/rmt/1h 694.It Sy Example 2 No Stripping the first 10 bytes from standard input 695.Pp 696The following example strips the first 10 bytes from standard input: 697.Pp 698.Dl % dd ibs=10 skip=1 699.It Sy Example 3 No Reading a tape into an ASCII file 700.Pp 701This example reads an 702.Cm EBCDIC 703tape blocked ten 80-byte 704.Cm EBCDIC 705card images per block into the 706.Cm ASCII 707file 708.Sy x : 709.Pp 710.Dl % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase 711.It Sy Example 4 No Using conv=sync to write to tape 712.Pp 713The following example uses 714.Cm conv Ns = Ns Ar sync 715when writing to a tape: 716.Pp 717.Dl % tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync 718.El 719.Sh DIAGNOSTICS 720.Bl -hang 721.It Sy f+p records in(out) 722numbers of full and partial blocks read(written) 723.El 724.Sh ENVIRONMENT VARIABLES 725See 726.Xr environ 7 727for descriptions of the following environment variables 728that affect the execution of 729.Nm : 730.Ev LANG , 731.Ev LC_ALL , 732.Ev LC_CTYPE , 733.Ev LC_MESSAGES , 734and 735.Ev NLSPATH . 736.Sh INTERFACE STABILITY 737Standard 738.Sh SEE ALSO 739.Xr cp 1 , 740.Xr sed 1 , 741.Xr tr 1 , 742.Xr fcntl.h 3HEAD , 743.Xr attributes 7 , 744.Xr environ 7 , 745.Xr largefile 7 , 746.Xr standards 7 747.Sh NOTES 748Do not use 749.Nm 750to copy files between file systems having different block sizes. 751.Pp 752Using a blocked device to copy a file will result in extra nulls being added 753to the file to pad the final block to the block boundary. 754.Pp 755When 756.Nm 757reads from a pipe, using the 758.Cm ibs Ns = Ns Ar X 759and 760.Cm obs Ns = Ns Ar Y 761operands, the output will always be blocked in chunks of size Y. 762When 763.Cm bs Ns = Ns Ar Z 764is used, the output blocks will be whatever was available to be read 765from the pipe at the time. 766.Pp 767When using 768.Nm 769to copy files to a tape device, the file size must be a multiple of the 770device sector size (for example, 512 Kbyte). 771To copy files of arbitrary size to a tape device, use 772.Xr tar 1 773or 774.Xr cpio 1 . 775