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