1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" 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.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)dd.1 6.7 (Berkeley) 08/07/91 10.\" 11.Dd 12.Dt DD 1 13.Os 14.Sh NAME 15.Nm dd 16.Nd convert and copy a file 17.Sh SYNOPSIS 18.Nm dd 19.Op operands ... 20.Sh DESCRIPTION 21The 22.Nm 23utility copies the standard input to the standard output. 24Input data is read and written in 512-byte blocks. 25If input reads are short, input from multiple reads are aggregated 26to form the output block. 27When finished, 28.Nm dd 29displays the number of complete and partial input and output blocks 30and truncated input records to the standard error output. 31.Pp 32The following operands are available: 33.Bl -tag -width of=file 34.It Cm bs= Ns Ar n 35Set both input and output block size, superseding the 36.Cm ibs 37and 38.Cm obs 39operands. 40If no conversion values other than 41.Cm noerror , 42.Cm notrunc 43or 44.Cm sync 45are specified, then each input block is copied to the output as a 46single block without any aggregation of short blocks. 47.It Cm cbs= Ns Ar n 48Set the conversion record size to 49.Va n 50bytes. 51The conversion record size is required by the record oriented conversion 52values. 53.It Cm count= Ns Ar n 54Copy only 55.Va n 56input blocks. 57.It Cm files= Ns Ar n 58Copy 59.Va n 60input files before terminating. 61This operand is only applicable when the input device is a tape. 62.It Cm ibs= Ns Ar n 63Set the input block size to 64.Va n 65bytes instead of the default 512. 66.It Cm if= Ns Ar file 67Read input from 68.Ar file 69instead of the standard input. 70.It Cm obs= Ns Ar n 71Set the output block size to 72.Va n 73bytes instead of the default 512. 74.It Cm of= Ns Ar file 75Write output to 76.Ar file 77instead of the standard output. 78Any regular output file is truncated unless the 79.Cm notrunc 80conversion value is specified. 81If an initial portion of the output file is skipped (see the 82.Cm seek 83operand) 84the output file is truncated at that point. 85.It Cm seek= Ns Ar n 86Seek 87.Va n 88blocks from the beginning of the output before copying. 89On non-tape devices, a 90.Xr lseek 2 91operation is used. 92Otherwise, existing blocks are read and the data discarded. 93If the user does not have read permission for the tape, it is positioned 94using the tape 95.Xr ioctl 2 96function calls. 97If the seek operation is past the end of file, space from the current 98end of file to the specified offset is filled with blocks of 99.Tn NUL 100bytes. 101.It Cm skip= Ns Ar n 102Skip 103.Va n 104blocks from the beginning of the input before copying. 105On input which supports seeks, a 106.Xr lseek 2 107operation is used. 108Otherwise, input data is read and discarded. 109For pipes, the correct number of bytes is read. 110For all other devices, the correct number of blocks is read without 111distinguishing between a partial or complete block being read. 112.It Xo 113.Cm conv= 114.Ns Cm value Ns Op \&, Cm value \&... 115.Xc 116Where 117.Cm value 118is one of the symbols from the following list. 119.Bl -tag -width unblock 120.It Cm ascii , oldascii 121The same as the 122.Cm unblock 123value except that characters are translated from 124.Tn ECBDIC 125to 126.Tn ASCII 127before the 128records are converted. 129(These values imply 130.Cm unblock 131if the operand 132.Cm cbs 133is also specified.) 134There are two conversion maps for 135.Tn ASCII . 136The value 137.Cm ascii 138specifies the recommended one which is compatible with System V. 139The value 140.Cm oldascii 141specifies the one used in historic 142.Tn AT&T 143and 144.Pf pre- Bx 4.3 reno 145systems. 146.It Cm block 147Treats the input as a sequence of newline or end-of-file terminated variable 148length records independent of input and output block boundaries. 149Any trailing newline character is discarded. 150Each input record is converted to a fixed length output record where the 151length is specified by the 152.Cm cbs 153operand. 154Input records shorter than the conversion record size are padded with spaces. 155Input records longer than the conversion record size are truncated. 156The number of truncated input records, if any, are reported to the standard 157error at the completion of the copy. 158.It Cm ebcdic , ibm , oldebcdic , oldibm 159The same as the 160.Cm block 161value except that characters are translated from 162.Tn ASCII 163to 164.Tn EBCDIC 165after the 166records are converted. 167(These values imply 168.Cm block 169if the operand 170.Cm cbs 171is also specified.) 172There are four conversion maps for 173.Tn EBCDIC . 174The value 175.Cm ebcdic 176specifies the recommended one which is compatible with 177.At V . 178The value 179.Cm ibm 180is a slightly different mapping, which is compatible with the 181.At V 182.Cm ibm 183value. 184The values 185.Cm oldebcdic 186and 187.Cm oldibm 188are maps used in historic 189.Tn AT&T 190and 191.Pf pre- Bx 4.3 reno 192systems. 193.It Cm lcase 194Transform uppercase characters into lowercase characters. 195.It Cm noerror 196Do not stop processing on an input error. 197When an input error occurs, a diagnostic message followed by the current 198input and output block counts will be written to standard error in the 199same format as the standard completion message. 200If the 201.Cm sync 202conversion is also specified, any missing input data will be replaced 203with 204.Tn NUL 205bytes (or with spaces if a block oriented conversion value was 206specified) and processed as a normal input buffer. 207If the 208.Cm sync 209conversion is not specified, the input block is omitted from the output. 210On input files which are not tapes or pipes, the file offset 211will be positioned past the block in which the error occurred using 212.Xr lseek 2 . 213.It Cm notrunc 214Do not truncate the output file. 215This will preserve any blocks in the output file not explicitly written 216by 217.Nm dd . 218The 219.Cm notrunc 220value is not supported for tapes. 221.It Cm swab 222Swap every pair of input bytes. 223If an input buffer has an odd number of bytes, the last byte will be 224ignored during swapping. 225.It Cm sync 226Pad every input block to the input buffer size. 227Spaces are used for pad bytes if a block oriented conversion value is 228specified, otherwise 229.Tn NUL 230bytes are used. 231.It Cm ucase 232Transform lowercase characters into uppercase characters. 233.It Cm unblock 234Treats the input as a sequence of fixed length records independent of input 235and output block boundaries. 236The length of the input records is specified by the 237.Cm cbs 238operand. 239Any trailing space characters are discarded and a newline character is 240appended. 241.El 242.El 243.Pp 244Where sizes are specified, a decimal number of bytes is expected. 245If the number ends with a ``b'', ``k'', ``m'' or ``w'', the number 246is multiplied by 512, 1024 (1K), 1048576 (1M) or the number of bytes 247in an integer, respectively. 248Two or more numbers may be separated by an ``x'' to indicate a product. 249.Pp 250When finished, 251.Nm dd 252displays the number of complete and partial input and output blocks, 253truncated input records and odd-length byte-swapping blocks to the 254standard error output. 255A partial input block is one where less than the input block size 256was read. 257A partial output block is one where less than the output block size 258was written. 259Partial output blocks to tape devices are considered fatal errors. 260Otherwise, the rest of the block will be written. 261Partial output blocks to character devices will produce a warning message. 262A truncated input block is one where a variable length record oriented 263conversion value was specified and the input line was too long to 264fit in the conversion record or was not newline terminated. 265.Pp 266Normally, data resulting from input or conversion or both are aggregated 267into output blocks of the specified size. 268After the end of input is reached, any remaining output is written as 269a block. 270This means that the final output block may be shorter than the output 271block size. 272.Pp 273If 274.Nm dd 275receives a 276.Dv SIGINFO 277(see the ``status'' argument for 278.Xr stty 1 ) 279signal, the current input and output block counts will 280be written to standard error in the same format as the standard completion 281message. 282If 283.Nm dd 284receives a 285.Dv SIGINT 286signal, the current input and output block counts will 287be written to standard error in the same format as the standard completion 288message and 289.Nm dd 290will exit. 291.Pp 292The 293.Nm dd 294utility exits 0 on success and >0 if an error occurred. 295.Sh SEE ALSO 296.Xr cp 1 , 297.Xr mt 1 , 298.Xr tr 1 299.Sh STANDARDS 300The 301.Nm dd 302utility is expected to be a superset of the 303.St -p1003.2 304standard. 305The 306.Cm files 307operand and the 308.Cm ascii , 309.Cm ebcdic , 310.Cm ibm , 311.Cm oldascii , 312.Cm oldebcdic 313and 314.Cm oldibm 315values are extensions to the 316.Tn POSIX 317standard. 318