1 DD(1M)                       Maintenance Commands                       DD(1M)
   2 
   3 NAME
   4      dd - convert and copy a file
   5 
   6 SYNOPSIS
   7      /usr/bin/dd [operand=value] ...
   8 
   9 DESCRIPTION
  10      The dd utility copies the specified input file to the specified output
  11      with possible conversions.  The standard input and output are used by
  12      default.  The input and output block sizes may be specified to take
  13      advantage of raw physical I/O.  Sizes are specified in bytes; a number
  14      may end with k, b, or w to specify multiplication by 1024, 512, or 2,
  15      respectively.  Numbers may also be separated by x to indicate
  16      multiplication.
  17 
  18      The dd utility reads the input one block at a time, using the specified
  19      input block size.  dd then processes the block of data actually returned,
  20      which could be smaller than the requested block size unless the input
  21      flag fullblock is used.  dd applies any conversions that have been
  22      specified and writes the resulting data to the output in blocks of the
  23      specified output block size.
  24 
  25      cbs is used only if ascii, asciib, unblock, ebcdic, ebcdicb, ibm, ibmb,
  26      or block conversion is specified.  In the first two cases, cbs characters
  27      are copied into the conversion buffer, any specified character mapping is
  28      done, trailing blanks are trimmed, and a NEWLINE is added before sending
  29      the line to output.  In the last three cases, characters up to NEWLINE
  30      are read into the conversion buffer and blanks are added to make up an
  31      output record of size cbs.  ASCII files are presumed to contain NEWLINE
  32      characters.  If cbs is unspecified or 0, the ascii, asciib, ebcdic,
  33      ebcdicb, ibm, and ibmb options convert the character set without changing
  34      the input file's block structure.  The unblock and block options become a
  35      simple file copy.
  36 
  37      After completion, dd reports the number of whole and partial input and
  38      output blocks.
  39 
  40 OPERANDS
  41      The following operands are supported:
  42 
  43      if=file
  44 
  45              Specifies the input path.  Standard input is the default.
  46 
  47      of=file
  48 
  49              Specifies the output path.  Standard output is the default.  If
  50              the seek=expr conversion is not also specified, the output file
  51              will be truncated before the copy begins, unless conv=notrunc is
  52              specified.  If seek=expr is specified, but conv=notrunc is not,
  53              the effect of the copy will be to preserve the blocks in the
  54              output file over which dd seeks, but no other portion of the
  55              output file will be preserved.  (If the size of the seek plus the
  56              size of the input file is less than the previous size of the
  57              output file, the output file is shortened by the copy.)
  58 
  59      ibs=n
  60 
  61              Specifies the input block size in n bytes (default is 512).
  62 
  63      obs=n
  64 
  65              Specifies the output block size in n bytes (default is 512).
  66 
  67      bs=n
  68 
  69              Sets both input and output block sizes to n bytes, superseding
  70              ibs= and obs=.  If no conversion other than sync, noerror, and
  71              notrunc is specified, each input block is copied to the output as
  72              a single block without aggregating short blocks.
  73 
  74      cbs=n
  75 
  76              Specifies the conversion block size for block and unblock in
  77              bytes by n (default is 0). If cbs= is omitted or given a value of
  78              0, using block or unblock produces unspecified results.
  79 
  80              This option is used only if ASCII or EBCDIC conversion is
  81              specified.  For the ascii and asciib operands, the input is
  82              handled as described for the unblock operand except that
  83              characters are converted to ASCII before the trailing SPACE
  84              characters are deleted.  For the ebcdic, ebcdicb, ibm, and ibmb
  85              operands, the input is handled as described for the block operand
  86              except that the characters are converted to EBCDIC or IBM EBCDIC
  87              after the trailing SPACE characters are added.
  88 
  89      files=n
  90 
  91              Copies and concatenates n input files before terminating (makes
  92              sense only where input is a magnetic tape or similar device).
  93 
  94      skip=n
  95 
  96              Skips n input blocks (using the specified input block size)
  97              before starting to copy.  On seekable files, the implementation
  98              reads the blocks or seeks past them.  On non-seekable files, the
  99              blocks are read and the data is discarded.
 100 
 101      iseek=n
 102 
 103              Seeks n blocks from beginning of input file before copying
 104              (appropriate for disk files, where skip can be incredibly slow).
 105 
 106      oseek=n
 107 
 108              Seeks n blocks from beginning of output file before copying.
 109 
 110      seek=n
 111 
 112              Skips n blocks (using the specified output block size) from
 113              beginning of output file before copying.  On non-seekable files,
 114              existing blocks are read and space from the current end-of-file
 115              to the specified offset, if any, is filled with null bytes.  On
 116              seekable files, the implementation seeks to the specified offset
 117              or reads the blocks as described for non-seekable files.
 118 
 119      ostride=n
 120 
 121              Writes every nth block (using the specified output block size)
 122              when writing output.  Skips n - 1 blocks after writing each
 123              record.
 124 
 125      istride=n
 126 
 127              Reads every nth block (using the specified input block size) when
 128              reading input.  Skips n - 1 blocks after reading each record.
 129 
 130      stride=n
 131 
 132              Reads every nth block (using the specified input block size) when
 133              reading input.  Skips n - 1 blocks after reading each record.
 134              Also writes every nth block (using the specified output block
 135              size) when writing output.  Skips n - 1 blocks after writing each
 136              record.
 137 
 138      count=n
 139 
 140              Copies only n input blocks.
 141 
 142      conv=value[,value...]
 143 
 144              Where values are comma-separated symbols from the following list:
 145 
 146              ascii   Converts EBCDIC to ASCII.
 147 
 148 
 149              asciib  Converts EBCDIC to ASCII using BSD-compatible character
 150                      translations.
 151 
 152              ebcdic  Converts ASCII to EBCDIC.  If converting fixed-length
 153                      ASCII records without NEWLINEs, sets up a pipeline with
 154                      dd conv=unblock beforehand.
 155 
 156              ebcdicb Converts ASCII to EBCDIC using BSD-compatible character
 157                      translations.  If converting fixed-length ASCII records
 158                      without NEWLINEs, sets up a pipeline with dd conv=unblock
 159                      beforehand.
 160 
 161              ibm     Slightly different map of ASCII to EBCDIC.  If converting
 162                      fixed-length ASCII records without NEWLINEs, sets up a
 163                      pipeline with dd conv=unblock beforehand.
 164 
 165              ibmb    Slightly different map of ASCII to EBCDIC using
 166                      BSD-compatible character translations.  If converting
 167                      fixed-length ASCII records without NEWLINEs, sets up a
 168                      pipeline with dd conv=unblock beforehand.
 169 
 170              The ascii (or asciib ), ebcdic (or ebcdicb ), and ibm (or ibmb)
 171              values are mutually exclusive.
 172 
 173              block   Treats the input as a sequence of NEWLINE-terminated or
 174                      EOF-terminated variable-length records independent of the
 175                      input block boundaries.  Each record is converted to a
 176                      record with a fixed length specified by the conversion
 177                      block size.  Any NEWLINE character is removed from the
 178                      input line.  SPACE characters are appended to lines that
 179                      are shorter than their conversion block size to fill the
 180                      block.  Lines that are longer than the conversion block
 181                      size are truncated to the largest number of characters
 182                      that will fit into that size.  The number of truncated
 183                      lines is reported.
 184 
 185              unblock Converts fixed-length records to variable length.  Reads
 186                      a number of bytes equal to the conversion block size (or
 187                      the number of bytes remaining in the input, if less than
 188                      the conversion block size), delete all trailing SPACE
 189                      characters, and append a NEWLINE character.
 190 
 191              The block and unblock values are mutually exclusive.
 192 
 193              lcase   Maps upper-case characters specified by the LC_CTYPE
 194                      keyword tolower to the corresponding lower-case
 195                      character.  Characters for which no mapping is specified
 196                      are not modified by this conversion.
 197 
 198              ucase   Maps lower-case characters specified by the LC_CTYPE
 199                      keyword toupper to the corresponding upper-case
 200                      character.  Characters for which no mapping is specified
 201                      are not modified by this conversion.
 202 
 203              The lcase and ucase symbols are mutually exclusive.
 204 
 205              swab    Swaps every pair of input bytes.  If the current input
 206                      record is an odd number of bytes, the last byte in the
 207                      input record is ignored.
 208 
 209              noerror Does not stop processing on an input error.  When an
 210                      input error occurs, a diagnostic message is written on
 211                      standard error, followed by the current input and output
 212                      block counts in the same format as used at completion.
 213                      If the sync conversion is specified, the missing input is
 214                      replaced with null bytes and processed normally.
 215                      Otherwise, the input block will be omitted from the
 216                      output.
 217 
 218              notrunc Does not truncate the output file.  Preserves blocks in
 219                      the output file not explicitly written by this invocation
 220                      of dd.  (See also the preceding of=file operand.)
 221 
 222              sync    Pads every input block to the size of the ibs= buffer,
 223                      appending null bytes.  (If either block or unblock is
 224                      also specified, appends SPACE characters, rather than
 225                      null bytes.)
 226 
 227      iflag=value[,value ...]
 228 
 229              Where values are comma-separated symbols from the following list
 230              which affect the behavior of reading from the input file:
 231 
 232              fullblock Accumulate full blocks of input.
 233 
 234      oflag=value[,value ...]
 235 
 236              Where values are comma-separated symbols from the following list
 237              which affect the behavior of writing the output file:
 238 
 239              dsync   The output file is opened with the O_DSYNC flag set.  All
 240                      data writes will be synchronous.  For more information on
 241                      O_DSYNC see fcntl.h(3HEAD).
 242 
 243              sync    The output file is opened with the O_SYNC.  All data and
 244                      metadata writes will be synchronous.  For more
 245                      information on O_SYNC see fcntl.h(3HEAD).
 246 
 247      If operands other than conv= and oflag= are specified more than once, the
 248      last specified operand=value is used.
 249 
 250      For the bs=, cbs=, ibs=, and obs= operands, the application must supply
 251      an expression specifying a size in bytes.  The expression, expr, can be:
 252            1.   a positive decimal number
 253 
 254            2.   a positive decimal number followed by k, specifying
 255                 multiplication by 1024
 256 
 257            3.   a positive decimal number followed by M, specifying
 258                 multiplication by 1024*1024
 259 
 260            4.   a positive decimal number followed by G, specifying
 261                 multiplication by 1024*1024*1024
 262 
 263            5.   a positive decimal number followed by T, specifying
 264                 multiplication by 1024*1024*1024*1024
 265 
 266            6.   a positive decimal number followed by P, specifying
 267                 multiplication by 1024*1024*1024*1024*1024
 268 
 269            7.   a positive decimal number followed by E, specifying
 270                 multiplication by 1024*1024*1024*1024*1024*1024
 271 
 272            8.   a positive decimal number followed by Z, specifying
 273                 multiplication by 1024*1024*1024*1024*1024*1024*1024
 274 
 275            9.   a positive decimal number followed by b, specifying
 276                 multiplication by 512
 277 
 278            10.  two or more positive decimal numbers (with or without k or b)
 279                 separated by x, specifying the product of the indicated
 280                 values.
 281 
 282      All of the operands will be processed before any input is read.
 283 
 284 SIGNALS
 285      When dd receives either SIGINFO or SIGUSR1, dd will emit the current
 286      input and output block counts, total bytes written, total time elapsed,
 287      and the number of bytes per second to standard error.  This is the same
 288      information format that dd emits when it successfully completes.  Users
 289      may send SIGINFO via their terminal.  The default character is ^T, see
 290      stty(1) for more information.
 291 
 292      For SIGINT, dd writes status information to standard error before
 293      exiting.  dd takes the standard action for all other signals.
 294 
 295 USAGE
 296      See largefile(5) for the description of the behavior of dd when
 297      encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 298 
 299 EXIT STATUS
 300      The following exit values are returned:
 301 
 302      0       The input file was copied successfully.
 303 
 304      >0           An error occurred.
 305 
 306      If an input error is detected and the noerror conversion has not been
 307      specified, any partial output block will be written to the output file, a
 308      diagnostic message will be written, and the copy operation will be
 309      discontinued.  If some other error is detected, a diagnostic message will
 310      be written and the copy operation will be discontinued.
 311 
 312 EXAMPLES
 313      Example 1 Copying from one tape drive to another
 314 
 315      The following example copies from tape drive 0 to tape drive 1, using a
 316      common historical device naming convention.
 317 
 318            % dd if=/dev/rmt/0h of=/dev/rmt/1h
 319 
 320      Example 2 Stripping the first 10 bytes from standard input
 321 
 322      The following example strips the first 10 bytes from standard input:
 323 
 324            % dd ibs=10 skip=1
 325 
 326      Example 3 Reading a tape into an ASCII file
 327 
 328      This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card images
 329      per block into the ASCII file x:
 330 
 331            % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
 332 
 333      Example 4 Using conv=sync to write to tape
 334 
 335      The following example uses conv=sync when writing to a tape:
 336 
 337            % tar cvf -. | compress | dd obs=1024k of=/dev/rmt/0 conv=sync
 338 
 339 DIAGNOSTICS
 340      f+p records in(out) numbers of full and partial blocks read(written)
 341 
 342 ENVIRONMENT VARIABLES
 343      See environ(5) for descriptions of the following environment variables
 344      that affect the execution of dd: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and
 345      NLSPATH.
 346 
 347 INTERFACE STABILITY
 348      Standard
 349 
 350 SEE ALSO
 351      cp(1), sed(1), tr(1), fcntl.h(3HEAD), attributes(5), environ(5),
 352      largefile(5), standards(5)
 353 
 354 NOTES
 355      Do not use dd to copy files between file systems having different block
 356      sizes.
 357 
 358      Using a  blocked device to copy a file will result in extra nulls being
 359      added to the file to pad the final block to the block boundary.
 360 
 361      When dd reads from a pipe, using the ibs=X and obs=Y operands, the output
 362      will always be blocked in chunks of size Y.  When bs=Z is used, the
 363      output blocks will be whatever was available to be read from the pipe at
 364      the time.
 365 
 366      When using dd to copy files to a tape device, the file size must be a
 367      multiple of the device sector size (for example, 512 Kbyte).  To copy
 368      files of arbitrary size to a tape device, use tar(1) or cpio(1).
 369 
 370 illumos                           May 4, 2019                          illumos