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.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)dd.1 8.2 (Berkeley) 01/13/94 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 pre-4.3BSD-reno systems. 144.It Cm block 145Treats the input as a sequence of newline or end-of-file terminated variable 146length records independent of input and output block boundaries. 147Any trailing newline character is discarded. 148Each input record is converted to a fixed length output record where the 149length is specified by the 150.Cm cbs 151operand. 152Input records shorter than the conversion record size are padded with spaces. 153Input records longer than the conversion record size are truncated. 154The number of truncated input records, if any, are reported to the standard 155error output at the completion of the copy. 156.It Cm ebcdic , ibm , oldebcdic , oldibm 157The same as the 158.Cm block 159value except that characters are translated from 160.Tn ASCII 161to 162.Tn EBCDIC 163after the 164records are converted. 165(These values imply 166.Cm block 167if the operand 168.Cm cbs 169is also specified.) 170There are four conversion maps for 171.Tn EBCDIC . 172The value 173.Cm ebcdic 174specifies the recommended one which is compatible with 175.At V . 176The value 177.Cm ibm 178is a slightly different mapping, which is compatible with the 179.At V 180.Cm ibm 181value. 182The values 183.Cm oldebcdic 184and 185.Cm oldibm 186are maps used in historic 187.Tn AT&T 188and pre-4.3BSD-reno systems. 189.It Cm lcase 190Transform uppercase characters into lowercase characters. 191.It Cm noerror 192Do not stop processing on an input error. 193When an input error occurs, a diagnostic message followed by the current 194input and output block counts will be written to the standard error output 195in the same format as the standard completion message. 196If the 197.Cm sync 198conversion is also specified, any missing input data will be replaced 199with 200.Tn NUL 201bytes (or with spaces if a block oriented conversion value was 202specified) and processed as a normal input buffer. 203If the 204.Cm sync 205conversion is not specified, the input block is omitted from the output. 206On input files which are not tapes or pipes, the file offset 207will be positioned past the block in which the error occurred using 208.Xr lseek 2 . 209.It Cm notrunc 210Do not truncate the output file. 211This will preserve any blocks in the output file not explicitly written 212by 213.Nm dd . 214The 215.Cm notrunc 216value is not supported for tapes. 217.It Cm osync 218Pad the final output block to the full output block size. 219If the input file is not a multiple of the output block size 220after conversion, this conversion forces the final output block 221to be the same size as preceding blocks for use on devices that require 222regularly sized blocks to be written. 223This option is incompatible with use of the 224.Cm bs= Ns Ar n 225block size specification. 226.It Cm swab 227Swap every pair of input bytes. 228If an input buffer has an odd number of bytes, the last byte will be 229ignored during swapping. 230.It Cm sync 231Pad every input block to the input buffer size. 232Spaces are used for pad bytes if a block oriented conversion value is 233specified, otherwise 234.Tn NUL 235bytes are used. 236.It Cm ucase 237Transform lowercase characters into uppercase characters. 238.It Cm unblock 239Treats the input as a sequence of fixed length records independent of input 240and output block boundaries. 241The length of the input records is specified by the 242.Cm cbs 243operand. 244Any trailing space characters are discarded and a newline character is 245appended. 246.El 247.El 248.Pp 249Where sizes are specified, a decimal number of bytes is expected. 250If the number ends with a ``b'', ``k'', ``m'' or ``w'', the number 251is multiplied by 512, 1024 (1K), 1048576 (1M) or the number of bytes 252in an integer, respectively. 253Two or more numbers may be separated by an ``x'' to indicate a product. 254.Pp 255When finished, 256.Nm dd 257displays the number of complete and partial input and output blocks, 258truncated input records and odd-length byte-swapping blocks to the 259standard error output. 260A partial input block is one where less than the input block size 261was read. 262A partial output block is one where less than the output block size 263was written. 264Partial output blocks to tape devices are considered fatal errors. 265Otherwise, the rest of the block will be written. 266Partial output blocks to character devices will produce a warning message. 267A truncated input block is one where a variable length record oriented 268conversion value was specified and the input line was too long to 269fit in the conversion record or was not newline terminated. 270.Pp 271Normally, data resulting from input or conversion or both are aggregated 272into output blocks of the specified size. 273After the end of input is reached, any remaining output is written as 274a block. 275This means that the final output block may be shorter than the output 276block size. 277.Pp 278If 279.Nm dd 280receives a 281.Dv SIGINFO 282(see the ``status'' argument for 283.Xr stty 1 ) 284signal, the current input and output block counts will 285be written to the standard error output 286in the same format as the standard completion message. 287If 288.Nm dd 289receives a 290.Dv SIGINT 291signal, the current input and output block counts will 292be written to the standard error output 293in the same format as the standard completion message and 294.Nm dd 295will exit. 296.Pp 297The 298.Nm dd 299utility exits 0 on success and >0 if an error occurred. 300.Sh SEE ALSO 301.Xr cp 1 , 302.Xr mt 1 , 303.Xr tr 1 304.Sh STANDARDS 305The 306.Nm dd 307utility is expected to be a superset of the 308.St -p1003.2 309standard. 310The 311.Cm files 312operand and the 313.Cm ascii , 314.Cm ebcdic , 315.Cm ibm , 316.Cm oldascii , 317.Cm oldebcdic 318and 319.Cm oldibm 320values are extensions to the 321.Tn POSIX 322standard. 323