601 lines
15 KiB
Groff
601 lines
15 KiB
Groff
.\" $NetBSD: dd.1,v 1.37 2021/05/18 07:17:09 nia Exp $
|
|
.\"
|
|
.\" Copyright (c) 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to Berkeley by
|
|
.\" Keith Muller of the University of California, San Diego.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)dd.1 8.2 (Berkeley) 1/13/94
|
|
.\"
|
|
.Dd May 18, 2021
|
|
.Dt DD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dd
|
|
.Nd convert and copy a file
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op operand ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility copies the standard input to the standard output.
|
|
Input data is read and written in 512-byte blocks.
|
|
If input reads are short, input from multiple reads are aggregated
|
|
to form the output block.
|
|
When finished,
|
|
.Nm
|
|
displays the number of complete and partial input and output blocks
|
|
and truncated input records to the standard error output.
|
|
.Pp
|
|
The following operands are available:
|
|
.Bl -tag -width of=file
|
|
.It Cm bs= Ns Ar n
|
|
Set both input and output block size, superseding the
|
|
.Cm ibs
|
|
and
|
|
.Cm obs
|
|
operands.
|
|
If no conversion values other than
|
|
.Cm noerror ,
|
|
.Cm notrunc
|
|
or
|
|
.Cm sync
|
|
are specified, then each input block is copied to the output as a
|
|
single block without any aggregation of short blocks.
|
|
.It Cm cbs= Ns Ar n
|
|
Set the conversion record size to
|
|
.Va n
|
|
bytes.
|
|
The conversion record size is required by the record oriented conversion
|
|
values.
|
|
.It Cm count= Ns Ar n
|
|
Copy only
|
|
.Va n
|
|
input blocks.
|
|
.It Cm files= Ns Ar n
|
|
Copy
|
|
.Va n
|
|
input files before terminating.
|
|
This operand is only applicable when the input device is a tape.
|
|
.It Cm ibs= Ns Ar n
|
|
Set the input block size to
|
|
.Va n
|
|
bytes instead of the default 512.
|
|
.It Cm if= Ns Ar file
|
|
Read input from
|
|
.Ar file
|
|
instead of the standard input.
|
|
.It Cm iflag= Ns Ar flags
|
|
Use comma-separated
|
|
.Ar flags
|
|
when calling
|
|
.Xr open 2
|
|
for the input file.
|
|
See the
|
|
.Sx INPUT AND OUTPUT FLAGS
|
|
section for details.
|
|
Default value is
|
|
.Va rdonly .
|
|
.It Cm iseek= Ns Ar n
|
|
Seek on the input file
|
|
.Ar n
|
|
blocks.
|
|
This is synonymous with
|
|
.Cm skip= Ns Ar n .
|
|
.It Cm msgfmt= Ns Ar fmt
|
|
Specify the message format
|
|
.Ar fmt
|
|
to be used when writing information to standard output.
|
|
Possible values are:
|
|
.Bl -tag -width xxxxx -offset indent -compact
|
|
.It quiet
|
|
turns off information summary report except for errors and
|
|
.Cm progress .
|
|
.It posix
|
|
default information summary report as specified by POSIX.
|
|
.It human
|
|
default information summary report extended with human-readable
|
|
values.
|
|
.El
|
|
.Pp
|
|
When
|
|
.Ar fmt
|
|
does not correspond to any value given above,
|
|
it contains a string that will be used as format specifier
|
|
for the information summary output.
|
|
Each conversion specification is introduced by the character
|
|
.Cm % .
|
|
The following ones are available:
|
|
.Bl -tag -width xx -offset indent -compact
|
|
.It b
|
|
total number of bytes transferred
|
|
.It B
|
|
total number of bytes transferred in
|
|
.Xr humanize_number 3
|
|
format
|
|
.It e
|
|
speed transfer
|
|
.It E
|
|
speed transfer in
|
|
.Xr humanize_number 3
|
|
format
|
|
.It i
|
|
number of partial input block(s)
|
|
.It I
|
|
number of full input block(s)
|
|
.It o
|
|
number of partial output block(s)
|
|
.It O
|
|
number of full output block(s)
|
|
.It s
|
|
time elapsed since the beginning in
|
|
.Do seconds.ms Dc
|
|
format
|
|
.It p
|
|
number of sparse output blocks
|
|
.It t
|
|
number of truncated blocks
|
|
.It w
|
|
number of odd-length swab blocks
|
|
.It P
|
|
singular/plural of
|
|
.Do block Dc
|
|
depending on number of sparse blocks
|
|
.It T
|
|
singular/plural of
|
|
.Do block Dc
|
|
depending on number of truncated blocks
|
|
.It W
|
|
singular/plural of
|
|
.Do block Dc
|
|
depending on number of swab blocks
|
|
.El
|
|
.It Cm obs= Ns Ar n
|
|
Set the output block size to
|
|
.Va n
|
|
bytes instead of the default 512.
|
|
.It Cm of= Ns Ar file
|
|
Write output to
|
|
.Ar file
|
|
instead of the standard output.
|
|
Any regular output file is truncated unless the
|
|
.Cm notrunc
|
|
conversion value is specified.
|
|
If an initial portion of the output file is skipped (see the
|
|
.Cm seek
|
|
operand)
|
|
the output file is truncated at that point.
|
|
.It Cm oflag= Ns Ar flags
|
|
Same as
|
|
.Cm iflag
|
|
but for the call to
|
|
.Xr open 2
|
|
on the output file.
|
|
The default value is
|
|
.Va creat ,
|
|
which must be explicitly added in
|
|
.Cm oflag
|
|
if this option is used in order to output to a nonexistent file.
|
|
The default or specified value is or'ed with
|
|
.Va rdwr
|
|
for a first
|
|
.Xr open 2
|
|
attempt, then on failure with
|
|
.Va wronly
|
|
on a second attempt.
|
|
In both cases,
|
|
.Va trunc
|
|
is automatically added if none of
|
|
.Cm oseek ,
|
|
.Cm seek ,
|
|
or
|
|
.Cm conv=notrunc
|
|
operands are used.
|
|
See the
|
|
.Sx INPUT AND OUTPUT FLAGS
|
|
section for details.
|
|
.It Cm oseek= Ns Ar n
|
|
Seek on the output file
|
|
.Ar n
|
|
blocks.
|
|
This is synonymous with
|
|
.Cm seek= Ns Ar n .
|
|
.It Cm seek= Ns Ar n
|
|
Seek
|
|
.Va n
|
|
blocks from the beginning of the output before copying.
|
|
On non-tape devices, an
|
|
.Xr lseek 2
|
|
operation is used.
|
|
Otherwise, existing blocks are read and the data discarded.
|
|
If the user does not have read permission for the tape, it is positioned
|
|
using the tape
|
|
.Xr ioctl 2
|
|
function calls.
|
|
If the seek operation is past the end of file, space from the current
|
|
end of file to the specified offset is filled with blocks of
|
|
.Tn NUL
|
|
bytes.
|
|
.It Cm skip= Ns Ar n
|
|
Skip
|
|
.Va n
|
|
blocks from the beginning of the input before copying.
|
|
On input which supports seeks, an
|
|
.Xr lseek 2
|
|
operation is used.
|
|
Otherwise, input data is read and discarded.
|
|
For pipes, the correct number of bytes is read.
|
|
For all other devices, the correct number of blocks is read without
|
|
distinguishing between a partial or complete block being read.
|
|
.It Cm progress= Ns Ar n
|
|
Switch on display of progress if
|
|
.Va n
|
|
is set to any non-zero value.
|
|
This will cause a
|
|
.Dq \&.
|
|
to be printed (to the standard error output) for every
|
|
.Va n
|
|
full or partial blocks written to the output file.
|
|
.Sm off
|
|
.It Cm conv= Cm value Op \&, Cm value \&...
|
|
.Sm on
|
|
Where
|
|
.Cm value
|
|
is one of the symbols from the following list.
|
|
.Bl -tag -width unblock
|
|
.It Cm ascii , oldascii
|
|
The same as the
|
|
.Cm unblock
|
|
value except that characters are translated from
|
|
.Tn EBCDIC
|
|
to
|
|
.Tn ASCII
|
|
before the
|
|
records are converted.
|
|
(These values imply
|
|
.Cm unblock
|
|
if the operand
|
|
.Cm cbs
|
|
is also specified.)
|
|
There are two conversion maps for
|
|
.Tn ASCII .
|
|
The value
|
|
.Cm ascii
|
|
specifies the recommended one which is compatible with
|
|
.At V .
|
|
The value
|
|
.Cm oldascii
|
|
specifies the one used in historic
|
|
.Tn AT&T
|
|
and pre-
|
|
.Bx 4.3 Reno
|
|
systems.
|
|
.It Cm block
|
|
Treats the input as a sequence of newline or end-of-file terminated variable
|
|
length records independent of input and output block boundaries.
|
|
Any trailing newline character is discarded.
|
|
Each input record is converted to a fixed length output record where the
|
|
length is specified by the
|
|
.Cm cbs
|
|
operand.
|
|
Input records shorter than the conversion record size are padded with spaces.
|
|
Input records longer than the conversion record size are truncated.
|
|
The number of truncated input records, if any, are reported to the standard
|
|
error output at the completion of the copy.
|
|
.It Cm ebcdic , ibm , oldebcdic , oldibm
|
|
The same as the
|
|
.Cm block
|
|
value except that characters are translated from
|
|
.Tn ASCII
|
|
to
|
|
.Tn EBCDIC
|
|
after the
|
|
records are converted.
|
|
(These values imply
|
|
.Cm block
|
|
if the operand
|
|
.Cm cbs
|
|
is also specified.)
|
|
There are four conversion maps for
|
|
.Tn EBCDIC .
|
|
The value
|
|
.Cm ebcdic
|
|
specifies the recommended one which is compatible with
|
|
.At V .
|
|
The value
|
|
.Cm ibm
|
|
is a slightly different mapping, which is compatible with the
|
|
.At V
|
|
.Cm ibm
|
|
value.
|
|
The values
|
|
.Cm oldebcdic
|
|
and
|
|
.Cm oldibm
|
|
are maps used in historic
|
|
.Tn AT&T
|
|
and pre
|
|
.Bx 4.3 Reno
|
|
systems.
|
|
.It Cm lcase
|
|
Transform uppercase characters into lowercase characters.
|
|
.It Cm noerror
|
|
Do not stop processing on an input error.
|
|
When an input error occurs, a diagnostic message followed by the current
|
|
input and output block counts will be written to the standard error output
|
|
in the same format as the standard completion message.
|
|
If the
|
|
.Cm sync
|
|
conversion is also specified, any missing input data will be replaced
|
|
with
|
|
.Tn NUL
|
|
bytes (or with spaces if a block oriented conversion value was
|
|
specified) and processed as a normal input buffer.
|
|
If the
|
|
.Cm sync
|
|
conversion is not specified, the input block is omitted from the output.
|
|
On input files which are not tapes or pipes, the file offset
|
|
will be positioned past the block in which the error occurred using
|
|
.Xr lseek 2 .
|
|
.It Cm notrunc
|
|
Do not truncate the output file.
|
|
This will preserve any blocks in the output file not explicitly written
|
|
by
|
|
.Nm .
|
|
The
|
|
.Cm notrunc
|
|
value is not supported for tapes.
|
|
.It Cm osync
|
|
Pad the final output block to the full output block size.
|
|
If the input file is not a multiple of the output block size
|
|
after conversion, this conversion forces the final output block
|
|
to be the same size as preceding blocks for use on devices that require
|
|
regularly sized blocks to be written.
|
|
This option is incompatible with use of the
|
|
.Cm bs= Ns Ar n
|
|
block size specification.
|
|
.It Cm sparse
|
|
If one or more non-final output blocks would consist solely of
|
|
.Dv NUL
|
|
bytes, try to seek the output file by the required space instead of
|
|
filling them with
|
|
.Dv NUL Ns s .
|
|
This results in a sparse file on some file systems.
|
|
.It Cm swab
|
|
Swap every pair of input bytes.
|
|
If an input buffer has an odd number of bytes, the last byte will be
|
|
ignored during swapping.
|
|
.It Cm sync
|
|
Pad every input block to the input buffer size.
|
|
Spaces are used for pad bytes if a block oriented conversion value is
|
|
specified, otherwise
|
|
.Tn NUL
|
|
bytes are used.
|
|
.It Cm ucase
|
|
Transform lowercase characters into uppercase characters.
|
|
.It Cm unblock
|
|
Treats the input as a sequence of fixed length records independent of input
|
|
and output block boundaries.
|
|
The length of the input records is specified by the
|
|
.Cm cbs
|
|
operand.
|
|
Any trailing space characters are discarded and a newline character is
|
|
appended.
|
|
.El
|
|
.El
|
|
.Pp
|
|
Where sizes are specified, a decimal number of bytes is expected.
|
|
Two or more numbers may be separated by an
|
|
.Dq x
|
|
to indicate a product.
|
|
Each number may have one of the following optional suffixes:
|
|
.Bl -tag -width 3n -offset indent -compact
|
|
.It b
|
|
Block; multiply by 512
|
|
.It k
|
|
Kibi; multiply by 1024 (1 KiB)
|
|
.It m
|
|
Mebi; multiply by 1048576 (1 MiB)
|
|
.It g
|
|
Gibi; multiply by 1073741824 (1 GiB)
|
|
.It t
|
|
Tebi; multiply by 1099511627776 (1 TiB)
|
|
.It w
|
|
Word; multiply by the number of bytes in an integer
|
|
.El
|
|
.Pp
|
|
When finished,
|
|
.Nm
|
|
displays the number of complete and partial input and output blocks,
|
|
truncated input records and odd-length byte-swapping blocks to the
|
|
standard error output.
|
|
A partial input block is one where less than the input block size
|
|
was read.
|
|
A partial output block is one where less than the output block size
|
|
was written.
|
|
Partial output blocks to tape devices are considered fatal errors.
|
|
Otherwise, the rest of the block will be written.
|
|
Partial output blocks to character devices will produce a warning message.
|
|
A truncated input block is one where a variable length record oriented
|
|
conversion value was specified and the input line was too long to
|
|
fit in the conversion record or was not newline terminated.
|
|
.Pp
|
|
Normally, data resulting from input or conversion or both are aggregated
|
|
into output blocks of the specified size.
|
|
After the end of input is reached, any remaining output is written as
|
|
a block.
|
|
This means that the final output block may be shorter than the output
|
|
block size.
|
|
.Pp
|
|
If
|
|
.Nm
|
|
receives a
|
|
.Dv SIGINFO
|
|
signal
|
|
(see the
|
|
.Ic status
|
|
argument for
|
|
.Xr stty 1 ) ,
|
|
the current input and output block counts will
|
|
be written to the standard error output
|
|
in the same format as the standard completion message.
|
|
If
|
|
.Nm
|
|
receives a
|
|
.Dv SIGINT
|
|
signal, the current input and output block counts will
|
|
be written to the standard error output
|
|
in the same format as the standard completion message and
|
|
.Nm
|
|
will exit.
|
|
.Sh INPUT AND OUTPUT FLAGS
|
|
There are flags valid for input only, for output only, or for either.
|
|
.Pp
|
|
The flags that apply to both input and output are:
|
|
.Bl -tag -width directory
|
|
.It Cm alt_io
|
|
Use Alternative I/O.
|
|
.It Cm async
|
|
Use
|
|
.Dv SIGIO
|
|
signaling for I/O.
|
|
.It Cm cloexec
|
|
Set the close-on-exec flag.
|
|
.It Cm direct
|
|
Directly access the data, skipping any caches.
|
|
.It Cm directory
|
|
Not available for
|
|
.Nm .
|
|
.It Cm exlock
|
|
Atomically obtain an exclusive lock.
|
|
.It Cm noctty
|
|
Do not consider the file as a potential controlling tty.
|
|
.It Cm nofollow
|
|
Do not follow symbolic links.
|
|
.It Cm nonblock
|
|
Do not block on open or I/O requests.
|
|
.It Cm nosigpipe
|
|
Return
|
|
.Er EPIPE
|
|
instead of raising
|
|
.Dv SIGPIPE .
|
|
.It Cm shlock
|
|
Atomically obtain a shared lock.
|
|
.It Cm sync
|
|
All I/O will be performed with full synchronization.
|
|
.El
|
|
.Pp
|
|
The flags that apply to only input are:
|
|
.Bl -tag -width directory
|
|
.It Cm rdonly
|
|
Set the read-only flag.
|
|
.It Cm rdwr
|
|
Set the read and write flags.
|
|
.It Cm rsync
|
|
Enable read synchronization, if the
|
|
.Cm sync
|
|
option is also set.
|
|
.El
|
|
.Pp
|
|
The flags that apply to only output are:
|
|
.Bl -tag -width directory
|
|
.It Cm append
|
|
Append to the output by default.
|
|
.It Cm creat
|
|
Create the output file.
|
|
.It Cm dsync
|
|
Wait for all data to be synchronously written.
|
|
.It Cm excl
|
|
Ensure that output is to a new file.
|
|
.It Cm trunc
|
|
Truncate the output file before writing.
|
|
.It Cm wronly
|
|
Set the write-only flag.
|
|
.El
|
|
See
|
|
.Xr open 2
|
|
and
|
|
.Xr ioctl 2
|
|
for more details.
|
|
.Sh EXIT STATUS
|
|
.Ex -std dd
|
|
.Sh EXAMPLES
|
|
To write a
|
|
.Xr gzip 1
|
|
compressed
|
|
.Nx
|
|
image to a removable drive, with
|
|
.Xr progress 1
|
|
output:
|
|
.Bd -literal -unfilled -offset indent
|
|
zcat NetBSD-9.2-amd64-install.img.gz | \\
|
|
progress dd of=/dev/rsd0 bs=1m
|
|
.Ed
|
|
.Pp
|
|
To print summary information in human-readable form:
|
|
.Pp
|
|
.Dl dd if=/dev/zero of=/dev/null count=1 msgfmt=human
|
|
.Pp
|
|
To customize the information summary output and print it through
|
|
.Xr unvis 3 :
|
|
.Bd -literal -offset indent
|
|
dd if=/dev/zero of=/dev/null count=1 \e
|
|
msgfmt='speed:%E, in %s seconds\en' 2>&1 | unvis
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr cp 1 ,
|
|
.Xr mt 1 ,
|
|
.Xr tr 1
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility is expected to be a superset of the
|
|
.St -p1003.2
|
|
standard.
|
|
The
|
|
.Cm files
|
|
and
|
|
.Cm msgfmt
|
|
operands and the
|
|
.Cm ascii ,
|
|
.Cm ebcdic ,
|
|
.Cm ibm ,
|
|
.Cm oldascii ,
|
|
.Cm oldebcdic
|
|
and
|
|
.Cm oldibm
|
|
values are extensions to the
|
|
.Tn POSIX
|
|
standard.
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
utility appeared in
|
|
.At v5 .
|