bin/dd/dd.1

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