DD(8) Maintenance Commands and Procedures DD(8)
NAME
dd - convert and copy a file
SYNOPSIS
dd [
operand=
value]
...DESCRIPTION
The
dd utility copies the specified input file to the specified 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 unless the input flag
fullblock is used.
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 portion 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 omitted or given a value of
0,
using
block or
unblock produces 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 terminating (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.
ostride=
n Writes every
nth block (using the specified output block size)
when writing output. Skips
n - 1 blocks after writing each
record.
istride=
n Reads every
nth block (using the specified input block size) when
reading input. Skips
n - 1 blocks after reading each record.
stride=
n Reads every
nth block (using the specified input block size) when
reading input. Skips
n - 1 blocks after reading each record.
Also writes every
nth block (using the specified output block
size) when writing output. Skips
n - 1 blocks after writing each
record.
count=
n Copies only
n input blocks.
conv=
value[,
value...]
Where
values are comma-separated symbols from the following list:
ascii Converts
EBCDIC to
ASCII.
asciib Converts
EBCDIC to
ASCII using
BSD-compatible character
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 character
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 converting
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 converted 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 conversion 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 character.
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 character.
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 character.
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 output block
counts in the same format as used at completion. If the
sync conversion is specified, the missing input is
replaced with null bytes and processed normally.
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 invocation
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.)
iflag=
value[,
value ...]
Where
values are comma-separated symbols from the following list
which affect the behavior of reading from the input file:
fullblock Accumulate full blocks of input.
oflag=
value[,
value ...]
Where
values are comma-separated symbols from the following list
which affect the behavior of writing the output file:
dsync The output file is opened with the
O_DSYNC flag set. All
data writes will be synchronous. For more information on
O_DSYNC see
fcntl.h(3HEAD).
sync The output file is opened with the
O_SYNC. All data and
metadata writes will be synchronous. For more information
on
O_SYNC see
fcntl.h(3HEAD).
status=
type Changes the way that
dd outputs information about transfers. Only
one
type may be specified. The following are valid values for
type:
none The program will not output any information and statistics
about the transfer. This includes when
dd receives a
signal such as SIGINFO and SIGUSR1. Only errors will be
emitted.
noxfer When printing statistical information such as when the
program terminates or in response to a signal, only print
information about the number of records and none of the
statistics about the transfer (total bytes, total time,
and throughput).
progress Once a second, output the normal
dd transfer statistics
that include the total number of bytes transferred, time
elapsed, and average throughput.
If operands other than
conv= and
oflag= 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
multiplication by 1024
3. a positive decimal number followed by
M, specifying
multiplication by 1024*1024
4. a positive decimal number followed by
G, specifying
multiplication by 1024*1024*1024
5. a positive decimal number followed by
T, specifying
multiplication by 1024*1024*1024*1024
6. a positive decimal number followed by
P, specifying
multiplication by 1024*1024*1024*1024*1024
7. a positive decimal number followed by
E, specifying
multiplication by 1024*1024*1024*1024*1024*1024
8. a positive decimal number followed by
Z, specifying
multiplication by 1024*1024*1024*1024*1024*1024*1024
9. a positive decimal number followed by
b, specifying
multiplication by 512
10. 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 will be processed before any input is read.
SIGNALS
When
dd receives either SIGINFO or SIGUSR1,
dd will emit the current input
and output block counts, total bytes written, total time elapsed, and the
number of bytes per second to standard error. This is the same information
format that
dd emits when it successfully completes. Users may send
SIGINFO via their terminal. The default character is ^T, see
stty(1) for
more information.
For
SIGINT,
dd writes status information to standard error before exiting.
dd takes the standard action for all other signals.
USAGE
See
largefile(7) for the description of the behavior of
dd when
encountering files greater than or equal to 2 Gbyte (2^31 bytes).
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.
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.
% 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 standard input:
% 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:
% 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:
% tar cvf -. | compress | dd obs=1024k of=/dev/rmt/0 conv=sync
DIAGNOSTICS
f+p records in(out) numbers of full and partial blocks read(written)
ENVIRONMENT VARIABLES
See
environ(7) for descriptions of the following environment variables that
affect the execution of
dd: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES, and
NLSPATH.
INTERFACE STABILITY
Standard
SEE ALSO
cp(1),
sed(1),
tr(1),
fcntl.h(3HEAD),
attributes(7),
environ(7),
largefile(7),
standards(7)NOTES
Do not use
dd to copy files between file systems having different 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 whatever 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 device, use
tar(1) or
cpio(1).
illumos October 24, 2021 illumos