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