dd(1M)




NAME

     dd - convert and copy a file


SYNOPSIS

     /usr/bin/dd [operand=value...]


DESCRIPTION

     The dd utility copies the specified input file to the speci-
     fied  output  with  possible conversions. The standard input
     and output are used by default. The input and  output  block
     sizes  may  be  specified  to take advantage of raw physical
     I/O. Sizes are specified in bytes; a number may end with  k,
     b,  or  w  to  specify  multiplication  by  1024, 512, or 2,
     respectively. Numbers may also be separated by x to indicate
     multiplication.

     The dd utility reads the input one block at  a  time,  using
     the  specified input block size. dd then processes the block
     of data actually returned, which could be smaller  than  the
     requested  block  size. dd applies any conversions that have
     been specified and writes the resulting data to  the  output
     in blocks of the specified output block size.

     cbs is used only if ascii, asciib, unblock, ebcdic, ebcdicb,
     ibm,  ibmb,  or  block conversion is specified. In the first
     two cases, cbs characters are  copied  into  the  conversion
     buffer,  any  specified  character mapping is done, trailing
     blanks are trimmed, and a NEWLINE is  added  before  sending
     the  line  to output. In the last three cases, characters up
     to NEWLINE are read into the conversion  buffer  and  blanks
     are  added  to  make  up an output record of size cbs. ASCII
     files are presumed to contain NEWLINE characters. If cbs  is
     unspecified  or  0, the ascii, asciib, ebcdic, ebcdicb, ibm,
     and ibmb options convert the character set without  changing
     the  input  file's  block  structure.  The unblock and block
     options become a simple file copy.

     After completion, dd reports the number of whole and partial
     input and output blocks.


OPERANDS

     The following operands are supported:

     if=file
           Specifies  the  input  path.  Standard  input  is  the
           default.

     of=file
           Specifies the output  path.  Standard  output  is  the
           default.  If  the  seek=expr  conversion  is  not also
           specified, the output file will  be  truncated  before
           the  copy begins, unless conv=notrunc is specified. If
           seek=expr is specified, but conv=notrunc is  not,  the
           effect  of  the copy will be to preserve the blocks in
           the output file over which dd seeks, but no other por-
           tion  of  the  output  file will 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 is shortened by the copy.)

     ibs=n Specifies the input block size in n bytes (default  is
           512).

     obs=n Specifies the output block size in n bytes (default is
           512).

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

     cbs=n Specifies the conversion  block  size  for  block  and
           unblock in bytes by n (default is 0). If cbs= is omit-
           ted or given a value of 0, using block or unblock pro-
           duces unspecified results.

           This option is used only if ASCII or EBCDIC conversion
           is  specified.  For the ascii and asciib operands, 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,  ebcdicb, ibm, and ibmb 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.

     files=n
           Copies and concatenates n input files before terminat-
           ing  (makes  sense only where input is a magnetic tape
           or similar device).

     skip=n
           Skips n input blocks (using the specified input  block
           size)  before starting to copy. On seekable files, the
           implementation reads the blocks or seeks past them. On
           non-seekable  files,  the blocks are read and the data
           is discarded.

     iseek=n
           Seeks n blocks from beginning  of  input  file  before
           copying (appropriate for disk files, where skip can be
           incredibly slow).

     oseek=n
           Seeks n blocks from beginning of  output  file  before
           copying.

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

     count=n
           Copies only n input blocks.

     conv=value[,value...]
           Where values are comma-separated symbols from the fol-
           lowing list:

     ascii Converts EBCDIC to ASCII.

     asciib
           Converts EBCDIC to ASCII using BSD-compatible  charac-
           ter translations.

     ebcdic
           Converts ASCII to EBCDIC. If  converting  fixed-length
           ASCII  records  without  NEWLINEs,  sets up a pipeline
           with dd conv=unblock beforehand.

     ebcdicb
           Converts ASCII to EBCDIC using BSD-compatible  charac-
           ter  translations.  If  converting  fixed-length ASCII
           records without NEWLINEs, sets up a pipeline  with  dd
           conv=unblock beforehand.

     ibm   Slightly different map of ASCII to EBCDIC. If convert-
           ing  fixed-length ASCII records without NEWLINEs, sets
           up a pipeline with dd conv=unblock beforehand.

     ibmb  Slightly different map of ASCII to EBCDIC  using  BSD-
           compatible   character   translations.  If  converting
           fixed-length ASCII records without NEWLINEs, sets up a
           pipeline with dd conv=unblock beforehand.

     The ascii (or asciib), ebcdic  (or  ebcdicb),  and  ibm  (or
     ibmb) values are mutually exclusive.

     block Treats the input as a sequence  of  NEWLINE-terminated
           or  EOF-terminated variable-length records independent
           of the input block boundaries.  Each  record  is  con-
           verted  to  a  record with a fixed length specified by
           the conversion block size. Any  NEWLINE  character  is
           removed  from  the  input  line.  SPACE characters are
           appended to lines that are shorter than their  conver-
           sion  block  size  to  fill  the block. Lines that are
           longer than the conversion block size are truncated to
           the  largest  number  of characters that will fit into
           that size. The number of truncated lines is reported.

     unblock
           Converts  fixed-length  records  to  variable  length.
           Reads  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  char-
           acter.

     The  block and unblock values are mutually exclusive.

     lcase Maps upper-case characters specified by  the  LC_CTYPE
           keyword  tolower to the corresponding lower-case char-
           acter. Characters for which no  mapping  is  specified
           are not modified by this conversion.

     ucase Maps lower-case characters specified by  the  LC_CTYPE
           keyword  toupper to the corresponding upper-case char-
           acter. Characters for which no  mapping  is  specified
           are not modified by this conversion.

     The lcase and ucase symbols are mutually exclusive.

     swab  Swaps every pair of input bytes. If the current  input
           record is an odd number of bytes, the last byte in the
           input record is ignored.

     noerror
           Does not stop processing on an input  error.  When  an
           input error occurs, a diagnostic message is written on
           standard error, followed by the current input and out-
           put block counts in the same format as used at comple-
           tion. If the sync conversion is specified, the missing
           input  is  replaced with null bytes and processed nor-
           mally. Otherwise, the input block will be omitted from
           the output.

     notrunc
           Does not truncate the output file. Preserves blocks in
           the output file not explicitly written by this invoca-
           tion of dd. (See also the preceding of=file operand.)

     sync  Pads every input block to the size of the ibs= buffer,
           appending  null  bytes. (If either block or unblock is
           also specified, appends SPACE characters, rather  than
           null bytes.)

     If operands other than conv= are specified more  than  once,
     the last specified operand=value is used.

     For the bs=, cbs=, ibs=, and obs= operands, the  application
     must  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  mul-
        tiplication by 1024

     3. a positive decimal number followed by b, specifying  mul-
        tiplication by 512

     4. two or more positive decimal numbers (with or  without  k
        or b) separated by x, specifying the product of the indi-
        cated values.

     All of the operands will be processed before  any  input  is
     read.


USAGE

     See largefile(5) for the description of the behavior  of  dd
     when encountering files greater than or equal to 2 Gbyte ( 2
    **31 bytes).


EXAMPLES

     Example 1: Copying from one tape drive to another

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

     example% dd if=/dev/rmt/0h  of=/dev/rmt/1h

     Example 2: Stripping the first 10 bytes from standard input

     The following example strips the first 10 bytes  from  stan-
     dard input:

     example% dd ibs=10  skip=1

     Example 3: Reading a tape into an ASCII file

     This example reads an EBCDIC tape blocked ten 80-byte EBCDIC
     card images per block into the ASCII file x:
     example% dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase

     Example 4: Using conv=sync to write to tape

     The following example uses conv=sync when writing to a tape:

     example% tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync


ENVIRONMENT VARIABLES

     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution of dd: LANG, LC_ALL,
     LC_CTYPE, LC_MESSAGES, and NLSPATH.


EXIT STATUS

     The following exit values are returned:

     0     The input file was copied successfully.

     >0    An error occurred.

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


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|
    | Interface Stability         | Standard                    |
    |_____________________________|_____________________________|


SEE ALSO

     cp(1),  sed(1),  tr(1),  attributes(5),  environ(5),  large-
     file(5), standards(5)


DIAGNOSTICS

     f+p records in(out)
           numbers of full and partial blocks read(written)


NOTES

     Do not use dd to copy files between file systems having dif-
     ferent block sizes.

     Using a  blocked device to copy a file will result in  extra
     nulls  being added to the file to pad the final block to the
     block boundary.

     When  dd reads from a pipe,  using  the   ibs=X  and   obs=Y
     operands,  the  output  will  always be blocked in chunks of
     size Y. When  bs=Z is used, the output blocks will be  what-
     ever was available to be read from the pipe at the time.

     When using dd to copy files to a tape device, the file  size
     must  be  a multiple of the device sector size (for example,
     512 Kbyte).  To  copy files of arbitrary size to a tape dev-
     ice, use  tar(1) or  cpio(1).

     For SIGINT, dd writes status information to  standard  error
     before  exiting.  It takes the standard action for all other
     signals.


Man(1) output converted with man2html