xref: /illumos-gate/usr/src/man/man8/dd.8 (revision bbf21555)

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
.\" Copyright (c) 2014, Joyent, Inc.  All rights Reserved.
.\" Copyright (c) 2014 by Delphix. All rights reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd October 24, 2021
.Dt DD 8
.Os
.Sh NAME
.Nm dd
.Nd convert and copy a file
.Sh SYNOPSIS
.Nm
.Op Ar operand Ns = Ns Ar value
.Ar ...
.Sh DESCRIPTION
The
.Nm
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
.Sy k ,
.Sy b ,
or
.Sy w
to specify multiplication by 1024, 512, or 2, respectively.
Numbers may also be separated by
.Sy x
to indicate multiplication.
.Pp
The
.Nm
utility reads the input one block at a time, using the specified
input block size.
.Nm
then processes the block of data actually returned,
which could be smaller than the requested block size unless the input flag
.Ar fullblock
is used.
.Nm
applies any conversions that have been specified and writes the resulting data
to the output in blocks of the specified output block size.
.Pp
.Cm cbs
is used only if
.Cm ascii ,
.Cm asciib ,
.Cm unblock ,
.Cm ebcdic ,
.Cm ebcdicb ,
.Cm ibm ,
.Cm ibmb ,
or
.Cm block
conversion is specified.
In the first two cases,
.Cm cbs
characters are copied into the conversion buffer, any specified character
mapping is done, trailing blanks are trimmed, and a
.Cm NEWLINE
is added before sending the line to output.
In the last three cases, characters up to
.Cm NEWLINE
are read into the conversion buffer and blanks are added to make up an output
record of size
.Cm cbs .
.Cm ASCII
files are presumed to contain
.Cm NEWLINE
characters.
If
.Cm cbs
is unspecified or
.Cm 0 ,
the
.Cm ascii ,
.Cm asciib ,
.Cm ebcdic ,
.Cm ebcdicb ,
.Cm ibm ,
and
.Cm ibmb
options convert the character set without changing the input file's block
structure.
The
.Cm unblock
and
.Cm block
options become a simple file copy.
.Pp
After completion,
.Nm
reports the number of whole and partial input and output blocks.
.Sh OPERANDS
The following operands are supported:
.Bl -tag -width "if=file"
.It Cm if= Ns Ar file
.Pp
Specifies the input path.
Standard input is the default.
.It Cm of= Ns Ar file
.Pp
Specifies the output path.
Standard output is the default.
If the
.Cm seek Ns = Ns Ar expr
conversion is not also specified, the output file will be truncated before
the copy begins, unless
.Cm conv Ns = Ns Ar notrunc
is specified.
If
.Cm seek Ns = Ns Ar expr
is specified, but
.Cm conv Ns = Ns Ar notrunc
is not, the effect of the copy will be to preserve the blocks in the output
file over which
.Nm
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.)
.It Cm ibs Ns = Ns Ar n
.Pp
Specifies the input block size in
.Ar n
bytes (default is 512).
.It Cm obs Ns = Ns Ar n
.Pp
Specifies the output block size in
.Ar n
bytes (default is 512).
.It Cm bs Ns = Ns Ar n
.Pp
Sets both input and output block sizes to
.Ar n
bytes, superseding
.Cm ibs Ns =
and
.Cm obs Ns = .
If no conversion other than
.Cm sync ,
.Cm noerror ,
and
.Cm notrunc
is specified, each input block is copied to the output as a
single block without aggregating short blocks.
.It Cm cbs Ns = Ns Ar n
.Pp
Specifies the conversion block size for
.Cm block
and
.Cm unblock
in bytes by
.Ar n
(default is
.Cm 0 Ns ).
If
.Cm cbs Ns =
is omitted or given a value of
.Cm 0 ,
using
.Cm block
or
.Cm unblock
produces unspecified results.
.Pp
This option is used only if
.Cm ASCII
or
.Cm EBCDIC
conversion is specified.
For the
.Cm ascii
and
.Cm asciib
operands, the input is handled as described for the
.Cm unblock
operand except that characters are converted to
.Cm ASCII
before the trailing
.Cm SPACE
characters are deleted.
For the
.Cm ebcdic ,
.Cm ebcdicb ,
.Cm ibm ,
and
.Cm ibmb
operands, the input is handled as described for the
.Cm block
operand except that the characters are converted to
.Cm EBCDIC
or IBM
.Cm EBCDIC
after the trailing
.Cm SPACE
characters are added.
.It Cm files Ns = Ns Ar n
.Pp
Copies and concatenates
.Ar n
input files before terminating (makes sense
only where input is a magnetic tape or similar device).
.It Cm skip Ns = Ns Ar n
.Pp
Skips
.Ar 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.
.It Cm iseek Ns = Ns Ar n
.Pp
Seeks
.Ar n
blocks from beginning of input file before copying (appropriate
for disk files, where
.Cm skip
can be incredibly slow).
.It Cm oseek Ns = Ns Ar n
.Pp
Seeks
.Ar n
blocks from beginning of output file before copying.
.It Cm seek Ns = Ns Ar n
.Pp
Skips
.Ar 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.
.It Cm ostride Ns = Ns Ar n
.Pp
Writes every
.Ar n Ns
th block (using the specified output block size) when writing output.
Skips
.Ar n
- 1 blocks after writing each record.
.It Cm istride Ns = Ns Ar n
.Pp
Reads every
.Ar n Ns
th block (using the specified input block size) when reading input.
Skips
.Ar n
- 1 blocks after reading each record.
.It Cm stride Ns = Ns Ar n
.Pp
Reads every
.Ar n Ns
th block (using the specified input block size) when reading input.
Skips
.Ar n
- 1 blocks after reading each record.
Also writes every
.Ar n Ns
th block (using the specified output block size) when writing output.
Skips
.Ar n
- 1 blocks after writing each record.
.It Cm count Ns = Ns Ar n
.Pp
Copies only
.Ar n
input blocks.
.It Cm conv Ns = Ns Ar value Ns Op , Ns  Ar value Ns ...
.Pp
Where
.Ar value Ns
s are comma-separated symbols from the following list:
.Bl -hang
.It Cm ascii
Converts
.Cm EBCDIC
to
.Cm ASCII .
.sp
.It Cm asciib
Converts
.Cm EBCDIC
to
.Cm ASCII
using
.Cm BSD Ns
-compatible character translations.
.It Cm ebcdic
Converts
.Cm ASCII
to
.Cm EBCDIC .
If converting fixed-length
.Cm ASCII
records without
.Cm NEWLINE Ns
s, sets up a pipeline with
.Nm
.Cm conv Ns = Ns Ar unblock
beforehand.
.It Cm ebcdicb
Converts
.Cm ASCII
to
.Cm EBCDIC
using
.Cm BSD Ns
-compatible character translations.
If converting fixed-length
.Cm ASCII
records without
.Cm NEWLINE Ns
s, sets up a pipeline with
.Nm
.Cm conv Ns = Ns Ar unblock
beforehand.
.It Cm ibm
Slightly different map of
.Cm ASCII
to
.Cm EBCDIC .
If converting fixed-length
.Cm ASCII
records without
.Cm NEWLINE Ns
s, sets up a pipeline with
.Nm
.Cm conv Ns = Ns Ar unblock
beforehand.
.It Cm ibmb
Slightly different map of
.Cm ASCII
to
.Cm EBCDIC
using
.Cm BSD Ns
-compatible character translations.
If converting fixed-length
.Cm ASCII
records without
.Cm NEWLINE Ns
s, sets up a pipeline with
.Nm
.Cm conv Ns = Ns Ar unblock
beforehand.
.El
.Pp
The
.Cm ascii
(or
.Cm asciib Ns ),
.Cm ebcdic
(or
.Cm ebcdicb Ns ),
and
.Cm ibm
(or
.Cm ibmb )
values are mutually exclusive.
.Bl -hang
.It Cm block
Treats the input as a sequence of
.Cm NEWLINE Ns
-terminated or
.Cm EOF Ns
-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
.Cm NEWLINE
character is removed from the input line.
.Cm 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.
.It Cm 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
.Cm SPACE
characters, and append a
.Cm NEWLINE
character.
.El
.Pp
The
.Cm block
and
.Cm unblock
values are mutually exclusive.
.Bl -hang
.It Cm lcase
Maps upper-case characters specified by the
.Cm LC_CTYPE
keyword
.Cm tolower
to the corresponding lower-case character.
Characters for which no mapping is specified are not modified by this
conversion.
.It Cm ucase
Maps lower-case characters specified by the
.Cm LC_CTYPE
keyword
.Cm toupper
to the corresponding upper-case character.
Characters for which no mapping is specified are not modified by this
conversion.
.El
.Pp
The
.Cm lcase
and
.Cm ucase
symbols are mutually exclusive.
.Bl -hang
.It Cm 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.
.It Cm 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
.Cm 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.
.It Cm notrunc
Does not truncate the output file.
Preserves blocks in the output file not explicitly written by this invocation
of
.Nm .
(See also the preceding
.Cm of Ns = Ns Ar file
operand.)
.It Cm sync
Pads every input block to the size of the
.Cm ibs Ns =
buffer, appending null bytes.
(If either
.Cm block
or
.Cm unblock
is also specified, appends
.Cm SPACE
characters, rather than null bytes.)
.El
.It Cm iflag Ns = Ns Ar value Ns Op , Ns Ar value ...
.Pp
Where
.Ar value Ns
s are comma-separated symbols from the following list which
affect the behavior of reading from the input file:
.Bl -hang
.It Cm fullblock
Accumulate full blocks of input.
.El
.It Cm oflag Ns = Ns Ar value Ns Op , Ns Ar value ...
.ad
.sp .6
Where
.Ar value Ns
s are comma-separated symbols from the following list which
affect the behavior of writing the output file:
.Bl -hang
.It Cm dsync
The output file is opened with the
.Cm O_DSYNC
flag set.
All data writes will be synchronous.
For more information on
.Cm O_DSYNC
see
.Xr fcntl.h 3HEAD .
.It Cm sync
The output file is opened with the
.Cm O_SYNC .
All data and metadata writes will be synchronous.
For more information on
.Cm O_SYNC
see
.Xr fcntl.h 3HEAD .
.El
.It Cm status Ns = Ns Ar type
Changes the way that
.Nm
outputs information about transfers.
Only one
.Ar type may be specified.
The following are valid values for
.Ar type :
.Bl -hang
.It Cm none
The program will not output any information and statistics about the transfer.
This includes when
.Nm
receives a signal such as
.Dv SIGINFO
and
.Dv SIGUSR1 .
Only errors will be emitted.
.It Cm 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
.Pq total bytes, total time, and throughput .
.It Cm progress
Once a second, output the normal
.Nm
transfer statistics that include the total number of bytes transferred, time
elapsed, and average throughput.
.El
.El
.Pp
If operands other than
.Cm conv Ns =
and
.Cm oflag Ns =
are specified more than once, the last specified
.Cm operand Ns = Ns Ar value
is used.
.Pp
For the
.Cm bs Ns = ,
.Cm cbs Ns = ,
.Cm ibs Ns = ,
and
.Cm obs Ns =
operands, the application must supply an expression specifying a size in bytes.
The expression,
.Cm expr ,
can be:
.Bl -enum -offset indent -compact
.It
a positive decimal number
.Pp
.It
a positive decimal number followed by
.Sy k ,
specifying multiplication by 1024
.Pp
.It
a positive decimal number followed by
.Sy M ,
specifying multiplication by 1024*1024
.Pp
.It
a positive decimal number followed by
.Sy G ,
specifying multiplication by 1024*1024*1024
.Pp
.It
a positive decimal number followed by
.Sy T ,
specifying multiplication by 1024*1024*1024*1024
.Pp
.It
a positive decimal number followed by
.Sy P ,
specifying multiplication by 1024*1024*1024*1024*1024
.Pp
.It
a positive decimal number followed by
.Sy E ,
specifying multiplication by 1024*1024*1024*1024*1024*1024
.Pp
.It
a positive decimal number followed by
.Sy Z ,
specifying multiplication by 1024*1024*1024*1024*1024*1024*1024
.Pp
.It
a positive decimal number followed by
.Sy b ,
specifying multiplication by 512
.Pp
.It
two or more positive decimal numbers (with or without
.Sy k
or
.Sy b )
separated by
.Sy x ,
specifying the product of the indicated values.
.El
.Pp
All of the operands will be processed before any input is read.
.Sh SIGNALS
When
.Nm
receives either SIGINFO or SIGUSR1,
.Nm
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
.Nm
emits when it successfully completes.
Users may send SIGINFO via their terminal.
The default character is ^T, see
.Xr stty 1
for more information.
.Pp
For
.Sy SIGINT ,
.Nm
writes status information to standard error before exiting.
.Nm
takes the standard action for all other signals.
.Sh USAGE
See
.Xr largefile 7
for the description of the behavior of
.Nm
when encountering files greater than or equal to 2 Gbyte (2^31 bytes).
.Sh EXIT STATUS
The following exit values are returned:
.Bl -tag -width ".It Cm >0"
.It Cm 0
The input file was copied successfully.
.It Cm >0
An error occurred.
.El
.Pp
If an input error is detected and the
.Cm 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.
.Sh EXAMPLES
.Bl -ohang
.It Sy Example 1 No Copying from one tape drive to another
.Pp
The following example copies from tape drive
.Sy 0
to tape drive
.Sy 1 ,
using a common historical device naming convention.
.Pp
.Dl % dd if=/dev/rmt/0h of=/dev/rmt/1h
.It Sy Example 2 No Stripping the first 10 bytes from standard input
.Pp
The following example strips the first 10 bytes from standard input:
.Pp
.Dl % dd ibs=10  skip=1
.It Sy Example 3 No Reading a tape into an ASCII file
.Pp
This example reads an
.Cm EBCDIC
tape blocked ten 80-byte
.Cm EBCDIC
card images per block into the
.Cm ASCII
file
.Sy x :
.Pp
.Dl % dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
.It Sy Example 4 No Using conv=sync to write to tape
.Pp
The following example uses
.Cm conv Ns = Ns Ar sync
when writing to a tape:
.Pp
.Dl % tar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync
.El
.Sh DIAGNOSTICS
.Bl -hang
.It Sy f+p records in(out)
numbers of full and partial blocks read(written)
.El
.Sh ENVIRONMENT VARIABLES
See
.Xr environ 7
for descriptions of the following environment variables
that affect the execution of
.Nm :
.Ev LANG ,
.Ev LC_ALL ,
.Ev LC_CTYPE ,
.Ev LC_MESSAGES ,
and
.Ev NLSPATH .
.Sh INTERFACE STABILITY
Standard
.Sh SEE ALSO
.Xr cp 1 ,
.Xr sed 1 ,
.Xr tr 1 ,
.Xr fcntl.h 3HEAD ,
.Xr attributes 7 ,
.Xr environ 7 ,
.Xr largefile 7 ,
.Xr standards 7
.Sh NOTES
Do not use
.Nm
to copy files between file systems having different block sizes.
.Pp
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.
.Pp
When
.Nm
reads from a pipe, using the
.Cm ibs Ns = Ns Ar X
and
.Cm obs Ns = Ns Ar Y
operands, the output will always be blocked in chunks of size Y.
When
.Cm bs Ns = Ns Ar Z
is used, the output blocks will be whatever was available to be read
from the pipe at the time.
.Pp
When using
.Nm
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
.Xr tar 1
or
.Xr cpio 1 .