bin/dd/dd.1

   1 .\"     $NetBSD: dd.1,v 1.21 2007/04/13 00:38:45 lukem 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 April 13, 2007
  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 operands ...
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility copies the standard input to the standard output.
  48 Input data is read and written in 512-byte blocks.
  49 If input reads are short, input from multiple reads are aggregated
  50 to form the output block.
  51 When finished,
  52 .Nm
  53 displays the number of complete and partial input and output blocks
  54 and truncated input records to the standard error output.
  55 .Pp
  56 The following operands are available:
  57 .Bl -tag -width of=file
  58 .It Cm bs= Ns Ar n
  59 Set both input and output block size, superseding the
  60 .Cm ibs
  61 and
  62 .Cm obs
  63 operands.
  64 If no conversion values other than
  65 .Cm noerror ,
  66 .Cm notrunc
  67 or
  68 .Cm sync
  69 are specified, then each input block is copied to the output as a
  70 single block without any aggregation of short blocks.
  71 .It Cm cbs= Ns Ar n
  72 Set the conversion record size to
  73 .Va n
  74 bytes.
  75 The conversion record size is required by the record oriented conversion
  76 values.
  77 .It Cm count= Ns Ar n
  78 Copy only
  79 .Va n
  80 input blocks.
  81 .It Cm files= Ns Ar n
  82 Copy
  83 .Va n
  84 input files before terminating.
  85 This operand is only applicable when the input device is a tape.
  86 .It Cm ibs= Ns Ar n
  87 Set the input block size to
  88 .Va n
  89 bytes instead of the default 512.
  90 .It Cm if= Ns Ar file
  91 Read input from
  92 .Ar file
  93 instead of the standard input.
  94 .It Cm obs= Ns Ar n
  95 Set the output block size to
  96 .Va n
  97 bytes instead of the default 512.
  98 .It Cm of= Ns Ar file
  99 Write output to
 100 .Ar file
 101 instead of the standard output.
 102 Any regular output file is truncated unless the
 103 .Cm notrunc
 104 conversion value is specified.
 105 If an initial portion of the output file is skipped (see the
 106 .Cm seek
 107 operand)
 108 the output file is truncated at that point.
 109 .It Cm seek= Ns Ar n
 110 Seek
 111 .Va n
 112 blocks from the beginning of the output before copying.
 113 On non-tape devices, a
 114 .Xr lseek 2
 115 operation is used.
 116 Otherwise, existing blocks are read and the data discarded.
 117 If the user does not have read permission for the tape, it is positioned
 118 using the tape
 119 .Xr ioctl 2
 120 function calls.
 121 If the seek operation is past the end of file, space from the current
 122 end of file to the specified offset is filled with blocks of
 123 .Tn NUL
 124 bytes.
 125 .It Cm skip= Ns Ar n
 126 Skip
 127 .Va n
 128 blocks from the beginning of the input before copying.
 129 On input which supports seeks, a
 130 .Xr lseek 2
 131 operation is used.
 132 Otherwise, input data is read and discarded.
 133 For pipes, the correct number of bytes is read.
 134 For all other devices, the correct number of blocks is read without
 135 distinguishing between a partial or complete block being read.
 136 .It Cm progress= Ns Ar n
 137 Switch on display of progress if
 138 .Va n
 139 is set to any non-zero value.
 140 This will cause a
 141 .Dq \&.
 142 to be printed (to the standard error output) for every
 143 .Va n
 144 full or partial blocks written to the output file.
 145 .Sm off
 146 .It Cm conv= Cm value Op \&, Cm value \&...
 147 .Sm on
 148 Where
 149 .Cm value
 150 is one of the symbols from the following list.
 151 .Bl -tag -width unblock
 152 .It Cm ascii , oldascii
 153 The same as the
 154 .Cm unblock
 155 value except that characters are translated from
 156 .Tn EBCDIC
 157 to
 158 .Tn ASCII
 159 before the
 160 records are converted.
 161 (These values imply
 162 .Cm unblock
 163 if the operand
 164 .Cm cbs
 165 is also specified.)
 166 There are two conversion maps for
 167 .Tn ASCII .
 168 The value
 169 .Cm ascii
 170 specifies the recommended one which is compatible with
 171 .At V .
 172 The value
 173 .Cm oldascii
 174 specifies the one used in historic
 175 .Tn AT\*[Am]T
 176 and pre-
 177 .Bx 4.3 Reno
 178 systems.
 179 .It Cm block
 180 Treats the input as a sequence of newline or end-of-file terminated variable
 181 length records independent of input and output block boundaries.
 182 Any trailing newline character is discarded.
 183 Each input record is converted to a fixed length output record where the
 184 length is specified by the
 185 .Cm cbs
 186 operand.
 187 Input records shorter than the conversion record size are padded with spaces.
 188 Input records longer than the conversion record size are truncated.
 189 The number of truncated input records, if any, are reported to the standard
 190 error output at the completion of the copy.
 191 .It Cm ebcdic , ibm , oldebcdic , oldibm
 192 The same as the
 193 .Cm block
 194 value except that characters are translated from
 195 .Tn ASCII
 196 to
 197 .Tn EBCDIC
 198 after the
 199 records are converted.
 200 (These values imply
 201 .Cm block
 202 if the operand
 203 .Cm cbs
 204 is also specified.)
 205 There are four conversion maps for
 206 .Tn EBCDIC .
 207 The value
 208 .Cm ebcdic
 209 specifies the recommended one which is compatible with
 210 .At V .
 211 The value
 212 .Cm ibm
 213 is a slightly different mapping, which is compatible with the
 214 .At V
 215 .Cm ibm
 216 value.
 217 The values
 218 .Cm oldebcdic
 219 and
 220 .Cm oldibm
 221 are maps used in historic
 222 .Tn AT\*[Am]T
 223 and pre
 224 .Bx 4.3 Reno
 225 systems.
 226 .It Cm lcase
 227 Transform uppercase characters into lowercase characters.
 228 .It Cm noerror
 229 Do not stop processing on an input error.
 230 When an input error occurs, a diagnostic message followed by the current
 231 input and output block counts will be written to the standard error output
 232 in the same format as the standard completion message.
 233 If the
 234 .Cm sync
 235 conversion is also specified, any missing input data will be replaced
 236 with
 237 .Tn NUL
 238 bytes (or with spaces if a block oriented conversion value was
 239 specified) and processed as a normal input buffer.
 240 If the
 241 .Cm sync
 242 conversion is not specified, the input block is omitted from the output.
 243 On input files which are not tapes or pipes, the file offset
 244 will be positioned past the block in which the error occurred using
 245 .Xr lseek 2 .
 246 .It Cm notrunc
 247 Do not truncate the output file.
 248 This will preserve any blocks in the output file not explicitly written
 249 by
 250 .Nm .
 251 The
 252 .Cm notrunc
 253 value is not supported for tapes.
 254 .It Cm osync
 255 Pad the final output block to the full output block size.
 256 If the input file is not a multiple of the output block size
 257 after conversion, this conversion forces the final output block
 258 to be the same size as preceding blocks for use on devices that require
 259 regularly sized blocks to be written.
 260 This option is incompatible with use of the
 261 .Cm bs= Ns Ar n
 262 block size specification.
 263 .It Cm sparse
 264 If one or more non-final output blocks would consist solely of
 265 .Dv NUL
 266 bytes, try to seek the output file by the required space instead of
 267 filling them with
 268 .Dv NUL Ns s .
 269 This results in a sparse file on some file systems.
 270 .It Cm swab
 271 Swap every pair of input bytes.
 272 If an input buffer has an odd number of bytes, the last byte will be
 273 ignored during swapping.
 274 .It Cm sync
 275 Pad every input block to the input buffer size.
 276 Spaces are used for pad bytes if a block oriented conversion value is
 277 specified, otherwise
 278 .Tn NUL
 279 bytes are used.
 280 .It Cm ucase
 281 Transform lowercase characters into uppercase characters.
 282 .It Cm unblock
 283 Treats the input as a sequence of fixed length records independent of input
 284 and output block boundaries.
 285 The length of the input records is specified by the
 286 .Cm cbs
 287 operand.
 288 Any trailing space characters are discarded and a newline character is
 289 appended.
 290 .El
 291 .El
 292 .Pp
 293 Where sizes are specified, a decimal number of bytes is expected.
 294 Two or more numbers may be separated by an
 295 .Dq x
 296 to indicate a product.
 297 Each number may have one of the following optional suffixes:
 298 .Bl -tag -width 3n -offset indent -compact
 299 .It b
 300 Block; multiply by 512
 301 .It k
 302 Kibi; multiply by 1024 (1 KiB)
 303 .It m
 304 Mebi; multiply by 1048576 (1 MiB)
 305 .It g
 306 Gibi; multiply by 1073741824 (1 GiB)
 307 .It t
 308 Tebi; multiply by 1099511627776 (1 TiB)
 309 .It w
 310 Word; multiply by the number of bytes in an integer
 311 .El
 312 .Pp
 313 When finished,
 314 .Nm
 315 displays the number of complete and partial input and output blocks,
 316 truncated input records and odd-length byte-swapping blocks to the
 317 standard error output.
 318 A partial input block is one where less than the input block size
 319 was read.
 320 A partial output block is one where less than the output block size
 321 was written.
 322 Partial output blocks to tape devices are considered fatal errors.
 323 Otherwise, the rest of the block will be written.
 324 Partial output blocks to character devices will produce a warning message.
 325 A truncated input block is one where a variable length record oriented
 326 conversion value was specified and the input line was too long to
 327 fit in the conversion record or was not newline terminated.
 328 .Pp
 329 Normally, data resulting from input or conversion or both are aggregated
 330 into output blocks of the specified size.
 331 After the end of input is reached, any remaining output is written as
 332 a block.
 333 This means that the final output block may be shorter than the output
 334 block size.
 335 .Pp
 336 If
 337 .Nm
 338 receives a
 339 .Dv SIGINFO
 340 signal
 341 (see the
 342 .Ic status
 343 argument for
 344 .Xr stty 1 ) ,
 345 the current input and output block counts will
 346 be written to the standard error output
 347 in the same format as the standard completion message.
 348 If
 349 .Nm
 350 receives a
 351 .Dv SIGINT
 352 signal, the current input and output block counts will
 353 be written to the standard error output
 354 in the same format as the standard completion message and
 355 .Nm
 356 will exit.
 357 .Sh EXIT STATUS
 358 The
 359 .Nm
 360 utility exits 0 on success and \*[Gt]0 if an error occurred.
 361 .Sh SEE ALSO
 362 .Xr cp 1 ,
 363 .Xr mt 1 ,
 364 .Xr tr 1
 365 .Sh STANDARDS
 366 The
 367 .Nm
 368 utility is expected to be a superset of the
 369 .St -p1003.2
 370 standard.
 371 The
 372 .Cm files
 373 operand and the
 374 .Cm ascii ,
 375 .Cm ebcdic ,
 376 .Cm ibm ,
 377 .Cm oldascii ,
 378 .Cm oldebcdic
 379 and
 380 .Cm oldibm
 381 values are extensions to the
 382 .Tn POSIX
 383 standard.