DD(1P) POSIX Programmer's Manual DD(1P)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.
NAMEdd — convert and copy a file
SYNOPSISdd [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 omit‐
ted.
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 aggre‐
gated 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 out‐
put 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 speci‐
fied. 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, super‐
seding 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 speci‐
fied 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 implementa‐
tion shall read the blocks or seek past them; on non-seekable
files, the blocks shall be read and the data shall be dis‐
carded.
seek=n Skip n blocks (using the specified output block size) from
the beginning of the output file before copying. On non-seek‐
able 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>-termi‐
nated 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 char‐
acter. 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 char‐
acter. 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 nor‐
mally; 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 invo‐
cation of the dd utility. (See also the preceding
of=file operand.)
sync Pad every input block to the size of the ibs= buf‐
fer, appending null bytes. (If either block or
unblock is also specified, append <space> charac‐
ters, 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 sup‐
ply 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) sepa‐
rated 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 con‐
version (second table). In both tables, the ASCII values are the row
and column headers and the EBCDIC values are found at their intersec‐
tions. For example, ASCII 0012 (LF) is the second row, third column,
yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to ASCII con‐
version) 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 vari‐
ables that are unset or null. (See the Base Definitions vol‐
ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
ables 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 low‐
ercase, 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 termi‐
nated by SIGINT. It shall take the standard action for all other sig‐
nals; 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 his‐
torical 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 repeti‐
tively. 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 val‐
ues. 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 implemen‐
tations 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 histor‐
ical 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 ta‐
ble.
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 oper‐
ands 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 prac‐
tice 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 sub‐
mitted 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 Electri‐
cal 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.ker‐
nel.org/doc/man-pages/reporting_bugs.html .
IEEE/The Open Group 2013 DD(1P)
