dd - convert and copy a file
/usr/bin/dd [operand=value]...
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.
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.
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.
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.)
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 flag
set. All data and metadata writes will be synchronous. For more information on
O_SYNC see fcntl.h(3HEAD).
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.
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.
See
largefile(5) for the description of the behavior of
dd when
encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
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 standard 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
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.
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.
See
attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE |
ATTRIBUTE VALUE |
|
| Interface Stability |
Standard |
cp(1),
sed(1),
tr(1),
fcntl.h(3HEAD),
attributes(5),
environ(5),
largefile(5),
standards(5)
f+p records in(out)
numbers of full and partial blocks read(written)
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).