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



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

NNAAMMEE
       dd -- convert and copy a file

SSYYNNOOPPSSIISS
       dd [[_o_p_e_r_a_n_d...]]

DDEESSCCRRIIPPTTIIOONN
       The _d_d 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 bbss=_e_x_p_r operand is specified and no conversions
       other than ssyynncc, nnooeerrrroorr, or nnoottrruunncc 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 ssyynncc conversion is not
       specified, the resulting output block shall be the same size as the
       input block. If the bbss=_e_x_p_r operand is not specified, or a conversion
       other than ssyynncc, nnooeerrrroorr, or nnoottrruunncc 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 ssyynncc conversion is specified, null bytes shall be appended
           to the input data up to the specified size. (If either bblloocckk or
           uunnbblloocckk 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 bbss=_e_x_p_r operand is specified and no conversion other than
           ssyynncc or nnooeerrrroorr is requested, the resulting data shall be written
           to the output as a single block, and the remaining steps are
           omitted.

        4. If the sswwaabb 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 (bblloocckk, uunnbblloocckk, llccaassee, and uuccaassee) 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 ccoonnvv=ssyynncc is not specified; thus, the
           final output block may be shorter than the output block size.

OOPPTTIIOONNSS
       None.

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

       iiff=_f_i_l_e   Specify the input pathname; the default is standard input.

       ooff=_f_i_l_e   Specify the output pathname; the default is standard output.
                 If the sseeeekk=_e_x_p_r conversion is not also specified, the output
                 file shall be truncated before the copy begins if an explicit
                 ooff=_f_i_l_e operand is specified, unless ccoonnvv=nnoottrruunncc is
                 specified. If sseeeekk=_e_x_p_r is specified, but ccoonnvv=nnoottrruunncc is
                 not, the effect of the copy shall be to preserve the blocks
                 in the output file over which _d_d 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.)

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

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

       bbss=_e_x_p_r   Set both input and output block sizes to _e_x_p_r bytes,
                 superseding iibbss= and oobbss=.  If no conversion other than ssyynncc,
                 nnooeerrrroorr, and nnoottrruunncc is specified, each input block shall be
                 copied to the output as a single block without aggregating
                 short blocks.

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

                 The application shall ensure that this operand is also
                 specified if the ccoonnvv= operand is specified with a value of
                 aasscciiii, eebbccddiicc, or iibbmm.  For a ccoonnvv= operand with an aasscciiii
                 value, the input is handled as described for the uunnbblloocckk
                 value, except that characters are converted to ASCII before
                 any trailing <space> characters are deleted. For ccoonnvv=
                 operands with eebbccddiicc or iibbmm values, the input is handled as
                 described for the bblloocckk value except that the characters are
                 converted to EBCDIC or IBM EBCDIC, respectively, after any
                 trailing <space> characters are added.

       sskkiipp=_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.

       sseeeekk=_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.

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

       ccoonnvv=_v_a_l_u_e[[,_v_a_l_u_e ...]]
                 Where _v_a_l_u_es are <comma>-separated symbols from the following
                 list:

                 aasscciiii    Convert EBCDIC to ASCII; see _T_a_b_l_e _4_-_7_, _A_S_C_I_I _t_o
                          _E_B_C_D_I_C _C_o_n_v_e_r_s_i_o_n.

                 eebbccddiicc   Convert ASCII to EBCDIC; see _T_a_b_l_e _4_-_7_, _A_S_C_I_I _t_o
                          _E_B_C_D_I_C _C_o_n_v_e_r_s_i_o_n.

                 iibbmm      Convert ASCII to a different EBCDIC set; see _T_a_b_l_e
                          _4_-_8_, _A_S_C_I_I _t_o _I_B_M _E_B_C_D_I_C _C_o_n_v_e_r_s_i_o_n.

                 The aasscciiii, eebbccddiicc, and iibbmm values are mutually-exclusive.

                 bblloocckk    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 bblloocckk and uunnbblloocckk values are mutually-exclusive.

                 uunnbblloocckk  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>.

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

                          The llccaassee and uuccaassee symbols are mutually-exclusive.

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

                 sswwaabb     Swap every pair of input bytes.

                 nnooeerrrroorr  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
                          ssyynncc 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.

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

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

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

       For the bbss=, ccbbss=, iibbss=, and oobbss= operands, the application shall
       supply an expression specifying a size in bytes. The expression, _e_x_p_r,
       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 aasscciiii and eebbccddiicc conversions (first table) and for the iibbmm
       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.

                        TTaabbllee 44--77:: AASSCCIIII ttoo EEBBCCDDIICC CCoonnvveerrssiioonn

                      TTaabbllee 44--88:: AASSCCIIII ttoo IIBBMM EEBBCCDDIICC CCoonnvveerrssiioonn

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

IINNPPUUTT FFIILLEESS
       The input file can be any file type.

EENNVVIIRROONNMMEENNTT VVAARRIIAABBLLEESS
       The following environment variables shall affect the execution of _d_d:

       _L_A_N_G      Provide a default value for the internationalization
                 variables that are unset or null. (See the Base Definitions
                 volume of POSIX.1-2017, _S_e_c_t_i_o_n _8_._2, _I_n_t_e_r_n_a_t_i_o_n_a_l_i_z_a_t_i_o_n
                 _V_a_r_i_a_b_l_e_s for the precedence of internationalization
                 variables used to determine the values of locale categories.)

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

       _L_C___C_T_Y_P_E  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.

       _L_C___M_E_S_S_A_G_E_S
                 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.

       _N_L_S_P_A_T_H   Determine the location of message catalogs for the processing
                 of _L_C___M_E_S_S_A_G_E_S.

AASSYYNNCCHHRROONNOOUUSS EEVVEENNTTSS
       For SIGINT, the _d_d 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 _S_e_c_t_i_o_n _1_._4, _U_t_i_l_i_t_y
       _D_e_s_c_r_i_p_t_i_o_n _D_e_f_a_u_l_t_s.

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

SSTTDDEERRRR
       On completion, _d_d 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", <_n_u_m_b_e_r _o_f _w_h_o_l_e _i_n_p_u_t _b_l_o_c_k_s>,
               <_n_u_m_b_e_r _o_f _p_a_r_t_i_a_l _i_n_p_u_t _b_l_o_c_k_s>

           "%u+%u records out\n", <_n_u_m_b_e_r _o_f _w_h_o_l_e _o_u_t_p_u_t _b_l_o_c_k_s>,
               <_n_u_m_b_e_r _o_f _p_a_r_t_i_a_l _o_u_t_p_u_t _b_l_o_c_k_s>

       A partial input block is one for which _r_e_a_d() 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", <_n_u_m_b_e_r _o_f _t_r_u_n_c_a_t_e_d _b_l_o_c_k_s>, "record" (if
               <_n_u_m_b_e_r _o_f _t_r_u_n_c_a_t_e_d _b_l_o_c_k_s> is one) "records" (otherwise)

       Diagnostic messages may also be written to standard error.

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

EEXXTTEENNDDEEDD DDEESSCCRRIIPPTTIIOONN
       None.

EEXXIITT SSTTAATTUUSS
       The following exit values shall be returned:

        0    The input file was copied successfully.

       >0    An error occurred.

CCOONNSSEEQQUUEENNCCEESS OOFF EERRRROORRSS
       If an input error is detected and the nnooeerrrroorr 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.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       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 _d_d utility perform conversions for
       the version specified by the tables.

EEXXAAMMPPLLEESS
       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 xx:


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

RRAATTIIOONNAALLEE
       The OPTIONS section is listed as ``None'' because there are no options
       recognized by historical _d_d 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, _d_d retains its curious JCL-like
       syntax due to the large number of applications that depend on the
       historical implementation.

       A suggested implementation technique for ccoonnvv=nnooeerrrroorr,ssyynncc is to zero
       (or <space>-fill, if bblloocckking or uunnbblloocckking) 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 _d_d 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 iibbss= and oobbss= 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 _d_d used _c_r_e_a_t() when processing ooff=_f_i_l_e.
       This makes the sseeeekk= operand unusable except on special files. The
       ccoonnvv=nnoottrruunncc feature was added because more recent BSD-based
       implementations use _o_p_e_n() (without O_TRUNC) instead of _c_r_e_a_t(), but
       they fail to delete output file contents after the data copied.

       The _w multiplier (historically meaning _w_o_r_d), is used in System V to
       mean 2 and in 4.2 BSD to mean 4. Since _w_o_r_d 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 (''//cc'') 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 (''//cc'') 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 (''//cc'').

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

       The ccbbss operand is required if any of the aasscciiii, eebbccddiicc, or iibbmm
       operands are specified. For the aasscciiii operand, the input is handled as
       described for the uunnbblloocckk operand except that characters are converted
       to ASCII before the trailing <space> characters are deleted. For the
       eebbccddiicc and iibbmm operands, the input is handled as described for the
       bblloocckk operand except that the characters are converted to EBCDIC or IBM
       EBCDIC after the trailing <space> characters are added.

       The bblloocckk and uunnbblloocckk keywords are from historical BSD practice.

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

       Early proposals only allowed two numbers separated by xx to be used in a
       product when specifying bbss=, ccbbss=, iibbss=, and oobbss= 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 sswwaabb 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.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _1_._4, _U_t_i_l_i_t_y _D_e_s_c_r_i_p_t_i_o_n _D_e_f_a_u_l_t_s, _s_e_d, _t_r

       The Base Definitions volume of POSIX.1-2017, _C_h_a_p_t_e_r _8, _E_n_v_i_r_o_n_m_e_n_t
       _V_a_r_i_a_b_l_e_s

CCOOPPYYRRIIGGHHTT
       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(1)
