Provided by: manpages-posix_2013a-1_all bug

PROLOG

       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

       dd — convert and copy a file

SYNOPSIS

       dd [operand...]

DESCRIPTION

       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

       None.

OPERANDS

       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.

       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

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

INPUT FILES

       The input file can be any file type.

ENVIRONMENT VARIABLES

       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‐2008,  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

       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

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

STDERR

       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

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

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       The following exit values shall be returned:

        0    The input file was copied successfully.

       >0    An error occurred.

CONSEQUENCES OF ERRORS

       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

       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

       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

       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‐2008, 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‐2008.

       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

       None.

SEE ALSO

       Section 1.4, Utility Description Defaults, sed, tr

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

COPYRIGHT

       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  7,  Copyright  (C)  2013  by  the  Institute  of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) 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.unix.org/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 .