dd(1p) — Linux manual page

PROLOG | NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OPERANDS | STDIN | INPUT FILES | ENVIRONMENT VARIABLES | ASYNCHRONOUS EVENTS | STDOUT | STDERR | OUTPUT FILES | EXTENDED DESCRIPTION | EXIT STATUS | CONSEQUENCES OF ERRORS | APPLICATION USAGE | EXAMPLES | RATIONALE | FUTURE DIRECTIONS | SEE ALSO | COPYRIGHT

DD(1P)                  POSIX Programmer's Manual                 DD(1P)

PROLOG         top

       This manual page is part of the POSIX Programmer's Manual.  The
       Linux implementation of this interface may differ (consult the
       corresponding Linux manual page for details of Linux behavior),
       or the interface may not be implemented on Linux.

NAME         top

       dd — convert and copy a file

SYNOPSIS         top

       dd [operand...]

DESCRIPTION         top

       The dd utility shall copy the specified input file to the
       specified output file with possible conversions using specific
       input and output block sizes. It shall read the input one block
       at a time, using the specified input block size; it shall then
       process the block of data actually returned, which could be
       smaller than the requested block size. It shall apply any
       conversions that have been specified and write the resulting data
       to the output in blocks of the specified output block size. If
       the bs=expr operand is specified and no conversions other than
       sync, noerror, or notrunc are requested, the data returned from
       each input block shall be written as a separate output block; if
       the read returns less than a full block and the sync conversion
       is not specified, the resulting output block shall be the same
       size as the input block. If the bs=expr operand is not specified,
       or a conversion other than sync, noerror, or notrunc is
       requested, the input shall be processed and collected into full-
       sized output blocks until the end of the input is reached.

       The processing order shall be as follows:

        1. An input block is read.

        2. If the input block is shorter than the specified input block
           size and the sync conversion is specified, null bytes shall
           be appended to the input data up to the specified size. (If
           either block or unblock is also specified, <space> characters
           shall be appended instead of null bytes.) The remaining
           conversions and output shall include the pad characters as if
           they had been read from the input.

        3. If the bs=expr operand is specified and no conversion other
           than sync or noerror is requested, the resulting data shall
           be written to the output as a single block, and the remaining
           steps are omitted.

        4. If the swab conversion is specified, each pair of input data
           bytes shall be swapped. If there is an odd number of bytes in
           the input block, the last byte in the input record shall not
           be swapped.

        5. Any remaining conversions (block, unblock, lcase, and ucase)
           shall be performed. These conversions shall operate on the
           input data independently of the input blocking; an input or
           output fixed-length record may span block boundaries.

        6. The data resulting from input or conversion or both shall be
           aggregated into output blocks of the specified size. After
           the end of input is reached, any remaining output shall be
           written as a block without padding if conv=sync is not
           specified; thus, the final output block may be shorter than
           the output block size.

OPTIONS         top

       None.

OPERANDS         top

       All of the operands shall be processed before any input is read.
       The following operands shall be supported:

       if=file   Specify the input pathname; the default is standard
                 input.

       of=file   Specify the output pathname; the default is standard
                 output. If the seek=expr conversion is not also
                 specified, the output file shall be truncated before
                 the copy begins if an explicit of=file operand is
                 specified, unless conv=notrunc is specified. If
                 seek=expr is specified, but conv=notrunc is not, the
                 effect of the copy shall be to preserve the blocks in
                 the output file over which dd seeks, but no other
                 portion of the output file shall be preserved. (If the
                 size of the seek plus the size of the input file is
                 less than the previous size of the output file, the
                 output file shall be shortened by the copy. If the
                 input file is empty and either the size of the seek is
                 greater than the previous size of the output file or
                 the output file did not previously exist, the size of
                 the output file shall be set to the file offset after
                 the seek.)

       ibs=expr  Specify the input block size, in bytes, by expr
                 (default is 512).

       obs=expr  Specify the output block size, in bytes, by expr
                 (default is 512).

       bs=expr   Set both input and output block sizes to expr bytes,
                 superseding ibs= and obs=.  If no conversion other than
                 sync, noerror, and notrunc is specified, each input
                 block shall be copied to the output as a single block
                 without aggregating short blocks.

       cbs=expr  Specify the conversion block size for block and unblock
                 in bytes by expr (default is zero). If cbs= is omitted
                 or given a value of zero, using block or unblock
                 produces unspecified results.

                 The application shall ensure that this operand is also
                 specified if the conv= operand is specified with a
                 value of ascii, ebcdic, or ibm.  For a conv= operand
                 with an ascii value, the input is handled as described
                 for the unblock value, except that characters are
                 converted to ASCII before any trailing <space>
                 characters are deleted. For conv= operands with ebcdic
                 or ibm values, the input is handled as described for
                 the block value except that the characters are
                 converted to EBCDIC or IBM EBCDIC, respectively, after
                 any trailing <space> characters are added.

       skip=n    Skip n input blocks (using the specified input block
                 size) before starting to copy. On seekable files, the
                 implementation shall read the blocks or seek past them;
                 on non-seekable files, the blocks shall be read and the
                 data shall be discarded.

       seek=n    Skip n blocks (using the specified output block size)
                 from the beginning of the output file before copying.
                 On non-seekable files, existing blocks shall be read
                 and space from the current end-of-file to the specified
                 offset, if any, filled with null bytes; on seekable
                 files, the implementation shall seek to the specified
                 offset or read the blocks as described for non-seekable
                 files.

       count=n   Copy only n input blocks. If n is zero, it is
                 unspecified whether no blocks or all blocks are copied.

       conv=value[,value ...]
                 Where values are <comma>-separated symbols from the
                 following list:

                 ascii    Convert EBCDIC to ASCII; see Table 4-7, ASCII
                          to EBCDIC Conversion.

                 ebcdic   Convert ASCII to EBCDIC; see Table 4-7, ASCII
                          to EBCDIC Conversion.

                 ibm      Convert ASCII to a different EBCDIC set; see
                          Table 4-8, ASCII to IBM EBCDIC Conversion.

                 The ascii, ebcdic, and ibm values are mutually-
                 exclusive.

                 block    Treat the input as a sequence of
                          <newline>-terminated or end-of-file-terminated
                          variable-length records independent of the
                          input block boundaries. Each record shall be
                          converted to a record with a fixed length
                          specified by the conversion block size. Any
                          <newline> shall be removed from the input
                          line; <space> characters shall be appended to
                          lines that are shorter than their conversion
                          block size to fill the block. Lines that are
                          longer than the conversion block size shall be
                          truncated to the largest number of characters
                          that fit into that size; the number of
                          truncated lines shall be reported (see the
                          STDERR section).

                          The block and unblock values are mutually-
                          exclusive.

                 unblock  Convert fixed-length records to variable
                          length. Read a number of bytes equal to the
                          conversion block size (or the number of bytes
                          remaining in the input, if less than the
                          conversion block size), delete all trailing
                          <space> characters, and append a <newline>.

                 lcase    Map uppercase characters specified by the
                          LC_CTYPE keyword tolower to the corresponding
                          lowercase character. Characters for which no
                          mapping is specified shall not be modified by
                          this conversion.

                          The lcase and ucase symbols are mutually-
                          exclusive.

                 ucase    Map lowercase characters specified by the
                          LC_CTYPE keyword toupper to the corresponding
                          uppercase character. Characters for which no
                          mapping is specified shall not be modified by
                          this conversion.

                 swab     Swap every pair of input bytes.

                 noerror  Do not stop processing on an input error. When
                          an input error occurs, a diagnostic message
                          shall be written on standard error, followed
                          by the current input and output block counts
                          in the same format as used at completion (see
                          the STDERR section). If the sync conversion is
                          specified, the missing input shall be replaced
                          with null bytes and processed normally;
                          otherwise, the input block shall be omitted
                          from the output.

                 notrunc  Do not truncate the output file. Preserve
                          blocks in the output file not explicitly
                          written by this invocation of the dd utility.
                          (See also the preceding of=file operand.)

                 sync     Pad every input block to the size of the ibs=
                          buffer, appending null bytes. (If either block
                          or unblock is also specified, append <space>
                          characters, rather than null bytes.)

       The behavior is unspecified if operands other than conv= are
       specified more than once.

       For the bs=, cbs=, ibs=, and obs= operands, the application shall
       supply an expression specifying a size in bytes. The expression,
       expr, can be:

        1. A positive decimal number

        2. A positive decimal number followed by k, specifying
           multiplication by 1024

        3. A positive decimal number followed by b, specifying
           multiplication by 512

        4. Two or more positive decimal numbers (with or without k or b)
           separated by x, specifying the product of the indicated
           values

       All of the operands are processed before any input is read.

       The following two tables display the octal number character
       values used for the ascii and ebcdic conversions (first table)
       and for the ibm conversion (second table). In both tables, the
       ASCII values are the row and column headers and the EBCDIC values
       are found at their intersections. For example, ASCII 0012 (LF) is
       the second row, third column, yielding 0045 in EBCDIC. The
       inverted tables (for EBCDIC to ASCII conversion) are not shown,
       but are in one-to-one correspondence with these tables. The
       differences between the two tables are highlighted by small boxes
       drawn around five entries.

                     Table 4-7: ASCII to EBCDIC Conversion
                   Table 4-8: ASCII to IBM EBCDIC Conversion

STDIN         top

       If no if= operand is specified, the standard input shall be used.
       See the INPUT FILES section.

INPUT FILES         top

       The input file can be any file type.

ENVIRONMENT VARIABLES         top

       The following environment variables shall affect the execution of
       dd:

       LANG      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base
                 Definitions volume of POSIX.1‐2017, Section 8.2,
                 Internationalization Variables for the precedence of
                 internationalization variables used to determine the
                 values of locale categories.)

       LC_ALL    If set to a non-empty string value, override the values
                 of all the other internationalization variables.

       LC_CTYPE  Determine the locale for the interpretation of
                 sequences of bytes of text data as characters (for
                 example, single-byte as opposed to multi-byte
                 characters in arguments and input files), the
                 classification of characters as uppercase or lowercase,
                 and the mapping of characters from one case to the
                 other.

       LC_MESSAGES
                 Determine the locale that should be used to affect the
                 format and contents of diagnostic messages written to
                 standard error and informative messages written to
                 standard output.

       NLSPATH   Determine the location of message catalogs for the
                 processing of LC_MESSAGES.

ASYNCHRONOUS EVENTS         top

       For SIGINT, the dd utility shall interrupt its current
       processing, write status information to standard error, and exit
       as though terminated by SIGINT. It shall take the standard action
       for all other signals; see the ASYNCHRONOUS EVENTS section in
       Section 1.4, Utility Description Defaults.

STDOUT         top

       If no of= operand is specified, the standard output shall be
       used. The nature of the output depends on the operands selected.

STDERR         top

       On completion, dd shall write the number of input and output
       blocks to standard error. In the POSIX locale the following
       formats shall be used:

           "%u+%u records in\n", <number of whole input blocks>,
               <number of partial input blocks>

           "%u+%u records out\n", <number of whole output blocks>,
               <number of partial output blocks>

       A partial input block is one for which read() returned less than
       the input block size. A partial output block is one that was
       written with fewer bytes than specified by the output block size.

       In addition, when there is at least one truncated block, the
       number of truncated blocks shall be written to standard error. In
       the POSIX locale, the format shall be:

           "%u truncated %s\n", <number of truncated blocks>, "record" (if
               <number of truncated blocks> is one) "records" (otherwise)

       Diagnostic messages may also be written to standard error.

OUTPUT FILES         top

       If the of= operand is used, the output shall be the same as
       described in the STDOUT section.

EXTENDED DESCRIPTION         top

       None.

EXIT STATUS         top

       The following exit values shall be returned:

        0    The input file was copied successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS         top

       If an input error is detected and the noerror conversion has not
       been specified, any partial output block shall be written to the
       output file, a diagnostic message shall be written, and the copy
       operation shall be discontinued. If some other error is detected,
       a diagnostic message shall be written and the copy operation
       shall be discontinued.

       The following sections are informative.

APPLICATION USAGE         top

       The input and output block size can be specified to take
       advantage of raw physical I/O.

       There are many different versions of the EBCDIC codesets. The
       ASCII and EBCDIC conversions specified for the dd utility perform
       conversions for the version specified by the tables.

EXAMPLES         top

       The following command:

           dd if=/dev/rmt0h  of=/dev/rmt1h

       copies from tape drive 0 to tape drive 1, using a common
       historical device naming convention.

       The following command:

           dd ibs=10  skip=1

       strips the first 10 bytes from standard input.

       This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card
       images per block into the ASCII file x:

           dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase

RATIONALE         top

       The OPTIONS section is listed as ``None'' because there are no
       options recognized by historical dd utilities. Certainly, many of
       the operands could have been designed to use the Utility Syntax
       Guidelines, which would have resulted in the classic hyphenated
       option letters. In this version of this volume of POSIX.1‐2017,
       dd retains its curious JCL-like syntax due to the large number of
       applications that depend on the historical implementation.

       A suggested implementation technique for conv=noerror,sync is to
       zero (or <space>-fill, if blocking or unblocking) the input
       buffer before each read and to write the contents of the input
       buffer to the output even after an error. In this manner, any
       data transferred to the input buffer before the error was
       detected is preserved. Another point is that a failed read on a
       regular file or a disk generally does not increment the file
       offset, and dd must then seek past the block on which the error
       occurred; otherwise, the input error occurs repetitively. When
       the input is a magnetic tape, however, the tape normally has
       passed the block containing the error when the error is reported,
       and thus no seek is necessary.

       The default ibs= and obs= sizes are specified as 512 bytes
       because there are historical (largely portable) scripts that
       assume these values. If they were left unspecified, unusual
       results could occur if an implementation chose an odd block size.

       Historical implementations of dd used creat() when processing
       of=file.  This makes the seek= operand unusable except on special
       files. The conv=notrunc feature was added because more recent
       BSD-based implementations use open() (without O_TRUNC) instead of
       creat(), but they fail to delete output file contents after the
       data copied.

       The w multiplier (historically meaning word), is used in System V
       to mean 2 and in 4.2 BSD to mean 4. Since word is inherently non-
       portable, its use is not supported by this volume of
       POSIX.1‐2017.

       Standard EBCDIC does not have the characters '[' and ']'.  The
       values used in the table are taken from a common print train that
       does contain them. Other than those characters, the print train
       values are not filled in, but appear to provide some of the
       motivation for the historical choice of translations reflected
       here.

       The Standard EBCDIC table provides a 1:1 translation for all 256
       bytes.

       The IBM EBCDIC table does not provide such a translation. The
       marked cells in the tables differ in such a way that:

        1. EBCDIC 0112 ('¢') and 0152 (broken pipe) do not appear in the
           table.

        2. EBCDIC 0137 ('¬') translates to/from ASCII 0236 ('^').  In
           the standard table, EBCDIC 0232 (no graphic) is used.

        3. EBCDIC 0241 ('~') translates to/from ASCII 0176 ('~').  In
           the standard table, EBCDIC 0137 ('¬') is used.

        4. 0255 ('[') and 0275 (']') appear twice, once in the same
           place as for the standard table and once in place of 0112
           ('¢') and 0241 ('~').

       In net result:

              EBCDIC 0275 (']') displaced EBCDIC 0241 ('~') in cell
              0345.

                  That displaced EBCDIC 0137 ('¬') in cell 0176.

                  That displaced EBCDIC 0232 (no graphic) in cell 0136.

                  That replaced EBCDIC 0152 (broken pipe) in cell 0313.

              EBCDIC 0255 ('[') replaced EBCDIC 0112 ('¢').

       This translation, however, reflects historical practice that
       (ASCII) '~' and '¬' were often mapped to each other, as were '['
       and '¢'; and ']' and (EBCDIC) '~'.

       The cbs operand is required if any of the ascii, ebcdic, or ibm
       operands are specified. For the ascii operand, the input is
       handled as described for the unblock operand except that
       characters are converted to ASCII before the trailing <space>
       characters are deleted. For the ebcdic and ibm operands, the
       input is handled as described for the block operand except that
       the characters are converted to EBCDIC or IBM EBCDIC after the
       trailing <space> characters are added.

       The block and unblock keywords are from historical BSD practice.

       The consistent use of the word record in standard error messages
       matches most historical practice. An earlier version of System V
       used block, but this has been updated in more recent releases.

       Early proposals only allowed two numbers separated by x to be
       used in a product when specifying bs=, cbs=, ibs=, and obs=
       sizes. This was changed to reflect the historical practice of
       allowing multiple numbers in the product as provided by Version 7
       and all releases of System V and BSD.

       A change to the swab conversion is required to match historical
       practice and is the result of IEEE PASC Interpretations 1003.2
       #03 and #04, submitted for the ISO POSIX‐2:1993 standard.

       A change to the handling of SIGINT is required to match
       historical practice and is the result of IEEE PASC Interpretation
       1003.2 #06 submitted for the ISO POSIX‐2:1993 standard.

FUTURE DIRECTIONS         top

       None.

SEE ALSO         top

       Section 1.4, Utility Description Defaults, sed(1p), tr(1p)

       The Base Definitions volume of POSIX.1‐2017, Chapter 8,
       Environment Variables

COPYRIGHT         top

       Portions of this text are reprinted and reproduced in electronic
       form from IEEE Std 1003.1-2017, Standard for Information
       Technology -- Portable Operating System Interface (POSIX), The
       Open Group Base Specifications Issue 7, 2018 Edition, Copyright
       (C) 2018 by the Institute of Electrical and Electronics
       Engineers, Inc and The Open Group.  In the event of any
       discrepancy between this version and the original IEEE and The
       Open Group Standard, the original IEEE and The Open Group
       Standard is the referee document. The original Standard can be
       obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page
       are most likely to have been introduced during the conversion of
       the source files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group               2017                            DD(1P)

Pages that refer to this page: iconv(1p)