1.\"- 2.\" Copyright (c) 1990, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" This code is derived from software contributed to Berkeley by 6.\" Keith Muller of the University of California, San Diego. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.Dd June 4, 2020 33.Dt DD 1 34.Os 35.Sh NAME 36.Nm dd 37.Nd convert and copy a file 38.Sh SYNOPSIS 39.Nm 40.Op Ar operands ... 41.Sh DESCRIPTION 42The 43.Nm 44utility copies the standard input to the standard output. 45Input data is read and written in 512-byte blocks. 46If input reads are short, input from multiple reads are aggregated 47to form the output block. 48When finished, 49.Nm 50displays the number of complete and partial input and output blocks 51and truncated input records to the standard error output. 52.Pp 53The following operands are available: 54.Bl -tag -width "of=file" 55.It Cm bs Ns = Ns Ar n 56Set both input and output block size to 57.Ar n 58bytes, superseding the 59.Cm ibs 60and 61.Cm obs 62operands. 63If no conversion values other than 64.Cm noerror , 65.Cm notrunc 66or 67.Cm sync 68are specified, then each input block is copied to the output as a 69single block without any aggregation of short blocks. 70.It Cm cbs Ns = Ns Ar n 71Set the conversion record size to 72.Ar n 73bytes. 74The conversion record size is required by the record oriented conversion 75values. 76.It Cm count Ns = Ns Ar n 77Copy only 78.Ar n 79input blocks. 80.It Cm files Ns = Ns Ar n 81Copy 82.Ar n 83input files before terminating. 84This operand is only applicable when the input device is a tape. 85.It Cm fillchar Ns = Ns Ar c 86When padding a block in conversion mode or due to use of 87.Cm noerror 88and 89.Cm sync 90modes, fill with the specified 91.Tn ASCII 92character, rather than using a space or 93.Dv NUL . 94.It Cm ibs Ns = Ns Ar n 95Set the input block size to 96.Ar n 97bytes instead of the default 512. 98.It Cm if Ns = Ns Ar file 99Read input from 100.Ar file 101instead of the standard input. 102.It Cm iflag Ns = Ns Ar value Ns Op , Ns Ar value ... 103Where 104.Cm value 105is one of the symbols from the following list. 106.Bl -tag -width "fullblock" 107.It Cm fullblock 108Reading from the input file may not obtain a full block. 109When a read returns short, continue reading to fill the block. 110Without this flag, 111.Cm count 112limits the number of times 113.Xr read 2 114is called on the input rather than the number of blocks copied in full. 115May not be combined with 116.Cm conv=sync . 117.It Cm direct 118Set the O_DIRECT flag on the input file to make reads bypass any local caching. 119.El 120.It Cm iseek Ns = Ns Ar n 121Seek on the input file 122.Ar n 123blocks. 124This is synonymous with 125.Cm skip Ns = Ns Ar n . 126.It Cm obs Ns = Ns Ar n 127Set the output block size to 128.Ar n 129bytes instead of the default 512. 130.It Cm of Ns = Ns Ar file 131Write output to 132.Ar file 133instead of the standard output. 134Any regular output file is truncated unless the 135.Cm notrunc 136conversion value is specified. 137If an initial portion of the output file is seeked past (see the 138.Cm oseek 139operand), 140the output file is truncated at that point. 141.It Cm oflag Ns = Ns Ar value Ns Op , Ns Ar value ... 142Where 143.Cm value 144is one of the symbols from the following list. 145.Bl -tag -width "direct" 146.It Cm fsync 147Set the O_FSYNC flag on the output file to make writes synchronous. 148.It Cm sync 149Set the O_SYNC flag on the output file to make writes synchronous. 150This is synonymous with the 151.Cm fsync 152value. 153.It Cm direct 154Set the O_DIRECT flag on the output file to make writes bypass any local caching. 155.El 156.It Cm oseek Ns = Ns Ar n 157Seek on the output file 158.Ar n 159blocks. 160This is synonymous with 161.Cm seek Ns = Ns Ar n . 162.It Cm seek Ns = Ns Ar n 163Seek 164.Ar n 165blocks from the beginning of the output before copying. 166On non-tape devices, an 167.Xr lseek 2 168operation is used. 169Otherwise, existing blocks are read and the data discarded. 170If the user does not have read permission for the tape, it is positioned 171using the tape 172.Xr ioctl 2 173function calls. 174If the seek operation is past the end of file, space from the current 175end of file to the specified offset is filled with blocks of 176.Dv NUL 177bytes. 178.It Cm skip Ns = Ns Ar n 179Skip 180.Ar n 181blocks from the beginning of the input before copying. 182On input which supports seeks, an 183.Xr lseek 2 184operation is used. 185Otherwise, input data is read and discarded. 186For pipes, the correct number of bytes is read. 187For all other devices, the correct number of blocks is read without 188distinguishing between a partial or complete block being read. 189.It Cm speed Ns = Ns Ar n 190Limit the copying speed to 191.Ar n 192bytes per second. 193.It Cm status Ns = Ns Ar value 194Where 195.Cm value 196is one of the symbols from the following list. 197.Bl -tag -width "progress" 198.It Cm noxfer 199Do not print the transfer statistics as the last line of status output. 200.It Cm none 201Do not print the status output. 202Error messages are shown; informational messages are not. 203.It Cm progress 204Print basic transfer statistics once per second. 205.El 206.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ... 207Where 208.Cm value 209is one of the symbols from the following list. 210.Bl -tag -width "unblock" 211.It Cm ascii , oldascii 212The same as the 213.Cm unblock 214value except that characters are translated from 215.Tn EBCDIC 216to 217.Tn ASCII 218before the 219records are converted. 220(These values imply 221.Cm unblock 222if the operand 223.Cm cbs 224is also specified.) 225There are two conversion maps for 226.Tn ASCII . 227The value 228.Cm ascii 229specifies the recommended one which is compatible with 230.At V . 231The value 232.Cm oldascii 233specifies the one used in historic 234.At 235and 236.No pre- Ns Bx 4.3 reno 237systems. 238.It Cm block 239Treats the input as a sequence of newline or end-of-file terminated variable 240length records independent of input and output block boundaries. 241Any trailing newline character is discarded. 242Each input record is converted to a fixed length output record where the 243length is specified by the 244.Cm cbs 245operand. 246Input records shorter than the conversion record size are padded with spaces. 247Input records longer than the conversion record size are truncated. 248The number of truncated input records, if any, are reported to the standard 249error output at the completion of the copy. 250.It Cm ebcdic , ibm , oldebcdic , oldibm 251The same as the 252.Cm block 253value except that characters are translated from 254.Tn ASCII 255to 256.Tn EBCDIC 257after the 258records are converted. 259(These values imply 260.Cm block 261if the operand 262.Cm cbs 263is also specified.) 264There are four conversion maps for 265.Tn EBCDIC . 266The value 267.Cm ebcdic 268specifies the recommended one which is compatible with 269.At V . 270The value 271.Cm ibm 272is a slightly different mapping, which is compatible with the 273.At V 274.Cm ibm 275value. 276The values 277.Cm oldebcdic 278and 279.Cm oldibm 280are maps used in historic 281.At 282and 283.No pre- Ns Bx 4.3 reno 284systems. 285.It Cm fdatasync 286Perform an 287.Xr fdatasync 2 288on the output file before closing it. 289.It Cm fsync 290Perform an 291.Xr fsync 2 292on the output file before closing it. 293.It Cm lcase 294Transform uppercase characters into lowercase characters. 295.It Cm pareven , parnone , parodd , parset 296Output data with the specified parity. 297The parity bit on input is stripped unless 298.Tn EBCDIC 299to 300.Tn ASCII 301conversions is also specified. 302.It Cm noerror 303Do not stop processing on an input error. 304When an input error occurs, a diagnostic message followed by the current 305input and output block counts will be written to the standard error output 306in the same format as the standard completion message. 307If the 308.Cm sync 309conversion is also specified, any missing input data will be replaced 310with 311.Dv NUL 312bytes (or with spaces if a block oriented conversion value was 313specified) and processed as a normal input buffer. 314If the 315.Cm fillchar 316option is specified, the fill character provided on the command line 317will override 318the automatic selection of the fill character. 319If the 320.Cm sync 321conversion is not specified, the input block is omitted from the output. 322On input files which are not tapes or pipes, the file offset 323will be positioned past the block in which the error occurred using 324.Xr lseek 2 . 325.It Cm notrunc 326Do not truncate the output file. 327This will preserve any blocks in the output file not explicitly written 328by 329.Nm . 330The 331.Cm notrunc 332value is not supported for tapes. 333.It Cm osync 334Pad the final output block to the full output block size. 335If the input file is not a multiple of the output block size 336after conversion, this conversion forces the final output block 337to be the same size as preceding blocks for use on devices that require 338regularly sized blocks to be written. 339This option is incompatible with use of the 340.Cm bs Ns = Ns Ar n 341block size specification. 342.It Cm sparse 343If one or more output blocks would consist solely of 344.Dv NUL 345bytes, try to seek the output file by the required space instead of 346filling them with 347.Dv NUL Ns s , 348resulting in a sparse file. 349.It Cm swab 350Swap every pair of input bytes. 351If an input buffer has an odd number of bytes, the last byte will be 352ignored during swapping. 353.It Cm sync 354Pad every input block to the input buffer size. 355Spaces are used for pad bytes if a block oriented conversion value is 356specified, otherwise 357.Dv NUL 358bytes are used. 359.It Cm ucase 360Transform lowercase characters into uppercase characters. 361.It Cm unblock 362Treats the input as a sequence of fixed length records independent of input 363and output block boundaries. 364The length of the input records is specified by the 365.Cm cbs 366operand. 367Any trailing space characters are discarded and a newline character is 368appended. 369.El 370.El 371.Pp 372Where sizes or speed are specified, a decimal, octal, or hexadecimal number of 373bytes is expected. 374If the number ends with a 375.Dq Li b , 376.Dq Li k , 377.Dq Li m , 378.Dq Li g , 379.Dq Li t , 380.Dq Li p , 381or 382.Dq Li w , 383the 384number is multiplied by 512, 1024 (1K), 1048576 (1M), 1073741824 (1G), 3851099511627776 (1T), 1125899906842624 (1P) 386or the number of bytes in an integer, respectively. 387Two or more numbers may be separated by an 388.Dq Li x 389to indicate a product. 390.Pp 391When finished, 392.Nm 393displays the number of complete and partial input and output blocks, 394truncated input records and odd-length byte-swapping blocks to the 395standard error output. 396A partial input block is one where less than the input block size 397was read. 398A partial output block is one where less than the output block size 399was written. 400Partial output blocks to tape devices are considered fatal errors. 401Otherwise, the rest of the block will be written. 402Partial output blocks to character devices will produce a warning message. 403A truncated input block is one where a variable length record oriented 404conversion value was specified and the input line was too long to 405fit in the conversion record or was not newline terminated. 406.Pp 407Normally, data resulting from input or conversion or both are aggregated 408into output blocks of the specified size. 409After the end of input is reached, any remaining output is written as 410a block. 411This means that the final output block may be shorter than the output 412block size. 413.Pp 414If 415.Nm 416receives a 417.Dv SIGINFO 418(see the 419.Cm status 420argument for 421.Xr stty 1 ) 422signal, the current input and output block counts will 423be written to the standard error output 424in the same format as the standard completion message. 425If 426.Nm 427receives a 428.Dv SIGINT 429signal, the current input and output block counts will 430be written to the standard error output 431in the same format as the standard completion message and 432.Nm 433will exit. 434.Sh EXIT STATUS 435.Ex -std 436.Sh EXAMPLES 437Check that a disk drive contains no bad blocks: 438.Pp 439.Dl "dd if=/dev/ada0 of=/dev/null bs=1m" 440.Pp 441Do a refresh of a disk drive, in order to prevent presently 442recoverable read errors from progressing into unrecoverable read errors: 443.Pp 444.Dl "dd if=/dev/ada0 of=/dev/ada0 bs=1m" 445.Pp 446Remove parity bit from a file: 447.Pp 448.Dl "dd if=file conv=parnone of=file.txt" 449.Pp 450Check for (even) parity errors on a file: 451.Pp 452.Dl "dd if=file conv=pareven | cmp -x - file" 453.Pp 454To create an image of a Mode-1 CD-ROM, which is a commonly used format 455for data CD-ROM disks, use a block size of 2048 bytes: 456.Pp 457.Dl "dd if=/dev/cd0 of=filename.iso bs=2048" 458.Pp 459Write a filesystem image to a memory stick, padding the end with zeros, 460if necessary, to a 1MiB boundary: 461.Pp 462.Dl "dd if=memstick.img of=/dev/da0 bs=1m conv=noerror,sync" 463.Sh SEE ALSO 464.Xr cp 1 , 465.Xr mt 1 , 466.Xr recoverdisk 1 , 467.Xr tr 1 , 468.Xr geom 4 , 469.Xr trim 8 470.Sh STANDARDS 471The 472.Nm 473utility is expected to be a superset of the 474.St -p1003.2 475standard. 476The 477.Cm files 478and 479.Cm status 480operands and the 481.Cm ascii , 482.Cm ebcdic , 483.Cm ibm , 484.Cm oldascii , 485.Cm oldebcdic 486and 487.Cm oldibm 488values are extensions to the 489.Tn POSIX 490standard. 491.Sh HISTORY 492A 493.Nm 494command appeared in 495.At v5 . 496.Sh BUGS 497Protection mechanisms in the 498.Xr geom 4 499subsystem might prevent the super-user from writing blocks to a disk. 500Instructions for temporarily disabling these protection mechanisms can be 501found in the 502.Xr geom 4 503man page. 504