1.\" $NetBSD: dd.1,v 1.36 2019/01/30 10:28:50 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" Keith Muller of the University of California, San Diego. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" @(#)dd.1 8.2 (Berkeley) 1/13/94 34.\" 35.Dd January 29, 2019 36.Dt DD 1 37.Os 38.Sh NAME 39.Nm dd 40.Nd convert and copy a file 41.Sh SYNOPSIS 42.Nm 43.Op operand ... 44.Sh DESCRIPTION 45The 46.Nm 47utility copies the standard input to the standard output. 48Input data is read and written in 512-byte blocks. 49If input reads are short, input from multiple reads are aggregated 50to form the output block. 51When finished, 52.Nm 53displays the number of complete and partial input and output blocks 54and truncated input records to the standard error output. 55.Pp 56The following operands are available: 57.Bl -tag -width of=file 58.It Cm bs= Ns Ar n 59Set both input and output block size, superseding the 60.Cm ibs 61and 62.Cm obs 63operands. 64If no conversion values other than 65.Cm noerror , 66.Cm notrunc 67or 68.Cm sync 69are specified, then each input block is copied to the output as a 70single block without any aggregation of short blocks. 71.It Cm cbs= Ns Ar n 72Set the conversion record size to 73.Va n 74bytes. 75The conversion record size is required by the record oriented conversion 76values. 77.It Cm count= Ns Ar n 78Copy only 79.Va n 80input blocks. 81.It Cm files= Ns Ar n 82Copy 83.Va n 84input files before terminating. 85This operand is only applicable when the input device is a tape. 86.It Cm ibs= Ns Ar n 87Set the input block size to 88.Va n 89bytes instead of the default 512. 90.It Cm if= Ns Ar file 91Read input from 92.Ar file 93instead of the standard input. 94.It Cm iflag= Ns Ar flags 95Use comma-separated 96.Ar flags 97when calling 98.Xr open 2 99for the input file. 100See the 101.Sx INPUT AND OUTPUT FLAGS 102section for details. 103Default value is 104.Va rdonly . 105.It Cm iseek= Ns Ar n 106Seek on the input file 107.Ar n 108blocks. 109This is synonymous with 110.Cm skip= Ns Ar n . 111.It Cm msgfmt= Ns Ar fmt 112Specify the message format 113.Ar fmt 114to be used when writing information to standard output. 115Possible values are: 116.Bl -tag -width xxxxx -offset indent -compact 117.It quiet 118turns off information summary report except for errors and 119.Cm progress . 120.It posix 121default information summary report as specified by POSIX. 122.It human 123default information summary report extended with human-readable 124values. 125.El 126.Pp 127When 128.Ar fmt 129does not correspond to any value given above, 130it contains a string that will be used as format specifier 131for the information summary output. 132Each conversion specification is introduced by the character 133.Cm % . 134The following ones are available: 135.Bl -tag -width xx -offset indent -compact 136.It b 137total number of bytes transferred 138.It B 139total number of bytes transferred in 140.Xr humanize_number 3 141format 142.It e 143speed transfer 144.It E 145speed transfer in 146.Xr humanize_number 3 147format 148.It i 149number of partial input block(s) 150.It I 151number of full input block(s) 152.It o 153number of partial output block(s) 154.It O 155number of full output block(s) 156.It s 157time elapsed since the beginning in 158.Do seconds.ms Dc 159format 160.It p 161number of sparse output blocks 162.It t 163number of truncated blocks 164.It w 165number of odd-length swab blocks 166.It P 167singular/plural of 168.Do block Dc 169depending on number of sparse blocks 170.It T 171singular/plural of 172.Do block Dc 173depending on number of truncated blocks 174.It W 175singular/plural of 176.Do block Dc 177depending on number of swab blocks 178.El 179.It Cm obs= Ns Ar n 180Set the output block size to 181.Va n 182bytes instead of the default 512. 183.It Cm of= Ns Ar file 184Write output to 185.Ar file 186instead of the standard output. 187Any regular output file is truncated unless the 188.Cm notrunc 189conversion value is specified. 190If an initial portion of the output file is skipped (see the 191.Cm seek 192operand) 193the output file is truncated at that point. 194.It Cm oflag= Ns Ar flags 195Same as 196.Cm iflag 197but for the call to 198.Xr open 2 199on the output file. 200The default value is 201.Va creat , 202which must be explicitly added in 203.Cm oflag 204if this option is used in order to output to a nonexistent file. 205The default or specified value is or'ed with 206.Va rdwr 207for a first 208.Xr open 2 209attempt, then on failure with 210.Va wronly 211on a second attempt. 212In both cases, 213.Va trunc 214is automatically added if none of 215.Cm oseek , 216.Cm seek , 217or 218.Cm conv=notrunc 219operands are used. 220See the 221.Sx INPUT AND OUTPUT FLAGS 222section for details. 223.It Cm oseek= Ns Ar n 224Seek on the output file 225.Ar n 226blocks. 227This is synonymous with 228.Cm seek= Ns Ar n . 229.It Cm seek= Ns Ar n 230Seek 231.Va n 232blocks from the beginning of the output before copying. 233On non-tape devices, an 234.Xr lseek 2 235operation is used. 236Otherwise, existing blocks are read and the data discarded. 237If the user does not have read permission for the tape, it is positioned 238using the tape 239.Xr ioctl 2 240function calls. 241If the seek operation is past the end of file, space from the current 242end of file to the specified offset is filled with blocks of 243.Tn NUL 244bytes. 245.It Cm skip= Ns Ar n 246Skip 247.Va n 248blocks from the beginning of the input before copying. 249On input which supports seeks, an 250.Xr lseek 2 251operation is used. 252Otherwise, input data is read and discarded. 253For pipes, the correct number of bytes is read. 254For all other devices, the correct number of blocks is read without 255distinguishing between a partial or complete block being read. 256.It Cm progress= Ns Ar n 257Switch on display of progress if 258.Va n 259is set to any non-zero value. 260This will cause a 261.Dq \&. 262to be printed (to the standard error output) for every 263.Va n 264full or partial blocks written to the output file. 265.Sm off 266.It Cm conv= Cm value Op \&, Cm value \&... 267.Sm on 268Where 269.Cm value 270is one of the symbols from the following list. 271.Bl -tag -width unblock 272.It Cm ascii , oldascii 273The same as the 274.Cm unblock 275value except that characters are translated from 276.Tn EBCDIC 277to 278.Tn ASCII 279before the 280records are converted. 281(These values imply 282.Cm unblock 283if the operand 284.Cm cbs 285is also specified.) 286There are two conversion maps for 287.Tn ASCII . 288The value 289.Cm ascii 290specifies the recommended one which is compatible with 291.At V . 292The value 293.Cm oldascii 294specifies the one used in historic 295.Tn AT&T 296and pre- 297.Bx 4.3 Reno 298systems. 299.It Cm block 300Treats the input as a sequence of newline or end-of-file terminated variable 301length records independent of input and output block boundaries. 302Any trailing newline character is discarded. 303Each input record is converted to a fixed length output record where the 304length is specified by the 305.Cm cbs 306operand. 307Input records shorter than the conversion record size are padded with spaces. 308Input records longer than the conversion record size are truncated. 309The number of truncated input records, if any, are reported to the standard 310error output at the completion of the copy. 311.It Cm ebcdic , ibm , oldebcdic , oldibm 312The same as the 313.Cm block 314value except that characters are translated from 315.Tn ASCII 316to 317.Tn EBCDIC 318after the 319records are converted. 320(These values imply 321.Cm block 322if the operand 323.Cm cbs 324is also specified.) 325There are four conversion maps for 326.Tn EBCDIC . 327The value 328.Cm ebcdic 329specifies the recommended one which is compatible with 330.At V . 331The value 332.Cm ibm 333is a slightly different mapping, which is compatible with the 334.At V 335.Cm ibm 336value. 337The values 338.Cm oldebcdic 339and 340.Cm oldibm 341are maps used in historic 342.Tn AT&T 343and pre 344.Bx 4.3 Reno 345systems. 346.It Cm lcase 347Transform uppercase characters into lowercase characters. 348.It Cm noerror 349Do not stop processing on an input error. 350When an input error occurs, a diagnostic message followed by the current 351input and output block counts will be written to the standard error output 352in the same format as the standard completion message. 353If the 354.Cm sync 355conversion is also specified, any missing input data will be replaced 356with 357.Tn NUL 358bytes (or with spaces if a block oriented conversion value was 359specified) and processed as a normal input buffer. 360If the 361.Cm sync 362conversion is not specified, the input block is omitted from the output. 363On input files which are not tapes or pipes, the file offset 364will be positioned past the block in which the error occurred using 365.Xr lseek 2 . 366.It Cm notrunc 367Do not truncate the output file. 368This will preserve any blocks in the output file not explicitly written 369by 370.Nm . 371The 372.Cm notrunc 373value is not supported for tapes. 374.It Cm osync 375Pad the final output block to the full output block size. 376If the input file is not a multiple of the output block size 377after conversion, this conversion forces the final output block 378to be the same size as preceding blocks for use on devices that require 379regularly sized blocks to be written. 380This option is incompatible with use of the 381.Cm bs= Ns Ar n 382block size specification. 383.It Cm sparse 384If one or more non-final output blocks would consist solely of 385.Dv NUL 386bytes, try to seek the output file by the required space instead of 387filling them with 388.Dv NUL Ns s . 389This results in a sparse file on some file systems. 390.It Cm swab 391Swap every pair of input bytes. 392If an input buffer has an odd number of bytes, the last byte will be 393ignored during swapping. 394.It Cm sync 395Pad every input block to the input buffer size. 396Spaces are used for pad bytes if a block oriented conversion value is 397specified, otherwise 398.Tn NUL 399bytes are used. 400.It Cm ucase 401Transform lowercase characters into uppercase characters. 402.It Cm unblock 403Treats the input as a sequence of fixed length records independent of input 404and output block boundaries. 405The length of the input records is specified by the 406.Cm cbs 407operand. 408Any trailing space characters are discarded and a newline character is 409appended. 410.El 411.El 412.Pp 413Where sizes are specified, a decimal number of bytes is expected. 414Two or more numbers may be separated by an 415.Dq x 416to indicate a product. 417Each number may have one of the following optional suffixes: 418.Bl -tag -width 3n -offset indent -compact 419.It b 420Block; multiply by 512 421.It k 422Kibi; multiply by 1024 (1 KiB) 423.It m 424Mebi; multiply by 1048576 (1 MiB) 425.It g 426Gibi; multiply by 1073741824 (1 GiB) 427.It t 428Tebi; multiply by 1099511627776 (1 TiB) 429.It w 430Word; multiply by the number of bytes in an integer 431.El 432.Pp 433When finished, 434.Nm 435displays the number of complete and partial input and output blocks, 436truncated input records and odd-length byte-swapping blocks to the 437standard error output. 438A partial input block is one where less than the input block size 439was read. 440A partial output block is one where less than the output block size 441was written. 442Partial output blocks to tape devices are considered fatal errors. 443Otherwise, the rest of the block will be written. 444Partial output blocks to character devices will produce a warning message. 445A truncated input block is one where a variable length record oriented 446conversion value was specified and the input line was too long to 447fit in the conversion record or was not newline terminated. 448.Pp 449Normally, data resulting from input or conversion or both are aggregated 450into output blocks of the specified size. 451After the end of input is reached, any remaining output is written as 452a block. 453This means that the final output block may be shorter than the output 454block size. 455.Pp 456If 457.Nm 458receives a 459.Dv SIGINFO 460signal 461(see the 462.Ic status 463argument for 464.Xr stty 1 ) , 465the current input and output block counts will 466be written to the standard error output 467in the same format as the standard completion message. 468If 469.Nm 470receives a 471.Dv SIGINT 472signal, the current input and output block counts will 473be written to the standard error output 474in the same format as the standard completion message and 475.Nm 476will exit. 477.Sh INPUT AND OUTPUT FLAGS 478There are flags valid for input only, for output only, or for either. 479.Pp 480The flags that apply to both input and output are: 481.Bl -tag -width directory 482.It Cm alt_io 483Use Alternative I/O. 484.It Cm async 485Use 486.Dv SIGIO 487signaling for I/O. 488.It Cm cloexec 489Set the close-on-exec flag. 490.It Cm direct 491Directly access the data, skipping any caches. 492.It Cm directory 493Not available for 494.Nm . 495.It Cm exlock 496Atomically obtain an exclusive lock. 497.It Cm noctty 498Do not consider the file as a potential controlling tty. 499.It Cm nofollow 500Do not follow symbolic links. 501.It Cm nonblock 502Do not block on open or I/O requests. 503.It Cm nosigpipe 504Return 505.Er EPIPE 506instead of raising 507.Dv SIGPIPE . 508.It Cm shlock 509Atomically obtain a shared lock. 510.It Cm sync 511All I/O will be performed with full synchronization. 512.El 513.Pp 514The flags that apply to only input are: 515.Bl -tag -width directory 516.It Cm rdonly 517Set the read-only flag. 518.It Cm rdwr 519Set the read and write flags. 520.It Cm rsync 521Enable read synchronization, if the 522.Cm sync 523option is also set. 524.El 525.Pp 526The flags that apply to only output are: 527.Bl -tag -width directory 528.It Cm append 529Append to the output by default. 530.It Cm creat 531Create the output file. 532.It Cm dsync 533Wait for all data to be synchronously written. 534.It Cm excl 535Ensure that output is to a new file. 536.It Cm trunc 537Truncate the output file before writing. 538.It Cm wronly 539Set the write-only flag. 540.El 541See 542.Xr open 2 543and 544.Xr ioctl 2 545for more details. 546.Sh EXIT STATUS 547.Ex -std dd 548.Sh EXAMPLES 549To print summary information in human-readable form: 550.Pp 551.Dl dd if=/dev/zero of=/dev/null count=1 msgfmt=human 552.Pp 553To customize the information summary output and print it through 554.Xr unvis 3 : 555.Bd -literal -offset indent 556dd if=/dev/zero of=/dev/null count=1 \e 557 msgfmt='speed:%E, in %s seconds\en' 2>&1 | unvis 558.Ed 559.Sh SEE ALSO 560.Xr cp 1 , 561.Xr mt 1 , 562.Xr tr 1 563.Sh STANDARDS 564The 565.Nm 566utility is expected to be a superset of the 567.St -p1003.2 568standard. 569The 570.Cm files 571and 572.Cm msgfmt 573operands and the 574.Cm ascii , 575.Cm ebcdic , 576.Cm ibm , 577.Cm oldascii , 578.Cm oldebcdic 579and 580.Cm oldibm 581values are extensions to the 582.Tn POSIX 583standard. 584.Sh HISTORY 585A 586.Nm 587utility appeared in 588.At v5 . 589