458 lines
13 KiB
Groff
458 lines
13 KiB
Groff
.\"-
|
|
.\" 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.
|
|
.\" 4. 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
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd August 25, 2016
|
|
.Dt DD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm dd
|
|
.Nd convert and copy a file
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Ar operands ...
|
|
.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 ".Cm of Ns = Ns Ar file"
|
|
.It Cm bs Ns = Ns Ar n
|
|
Set both input and output block size to
|
|
.Ar n
|
|
bytes, 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 = Ns Ar n
|
|
Set the conversion record size to
|
|
.Ar n
|
|
bytes.
|
|
The conversion record size is required by the record oriented conversion
|
|
values.
|
|
.It Cm count Ns = Ns Ar n
|
|
Copy only
|
|
.Ar n
|
|
input blocks.
|
|
.It Cm files Ns = Ns Ar n
|
|
Copy
|
|
.Ar n
|
|
input files before terminating.
|
|
This operand is only applicable when the input device is a tape.
|
|
.It Cm fillchar Ns = Ns Ar c
|
|
When padding a block in conversion mode or due to use of
|
|
.Cm noerror
|
|
and
|
|
.Cm sync
|
|
modes, fill with the specified
|
|
.Tn ASCII
|
|
character, rather than using a space or
|
|
.Dv NUL .
|
|
.It Cm ibs Ns = Ns Ar n
|
|
Set the input block size to
|
|
.Ar n
|
|
bytes instead of the default 512.
|
|
.It Cm if Ns = Ns Ar file
|
|
Read input from
|
|
.Ar file
|
|
instead of the standard input.
|
|
.It Cm iseek Ns = Ns Ar n
|
|
Seek on the input file
|
|
.Ar n
|
|
blocks.
|
|
This is synonymous with
|
|
.Cm skip Ns = Ns Ar n .
|
|
.It Cm obs Ns = Ns Ar n
|
|
Set the output block size to
|
|
.Ar n
|
|
bytes instead of the default 512.
|
|
.It Cm of Ns = 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 seeked past (see the
|
|
.Cm oseek
|
|
operand),
|
|
the output file is truncated at that point.
|
|
.It Cm oseek Ns = Ns Ar n
|
|
Seek on the output file
|
|
.Ar n
|
|
blocks.
|
|
This is synonymous with
|
|
.Cm seek Ns = Ns Ar n .
|
|
.It Cm seek Ns = Ns Ar n
|
|
Seek
|
|
.Ar 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
|
|
.Dv NUL
|
|
bytes.
|
|
.It Cm skip Ns = Ns Ar n
|
|
Skip
|
|
.Ar 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 speed Ns = Ns Ar n
|
|
Limit the copying speed to
|
|
.Ar n
|
|
bytes per second.
|
|
.It Cm status Ns = Ns Ar value
|
|
Where
|
|
.Cm value
|
|
is one of the symbols from the following list.
|
|
.Bl -tag -width ".Cm noxfer"
|
|
.It Cm noxfer
|
|
Do not print the transfer statistics as the last line of status output.
|
|
.It Cm none
|
|
Do not print the status output.
|
|
Error messages are shown; informational messages are not.
|
|
.El
|
|
.It Cm conv Ns = Ns Ar value Ns Op , Ns Ar value ...
|
|
Where
|
|
.Cm value
|
|
is one of the symbols from the following list.
|
|
.Bl -tag -width ".Cm 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
|
|
.At
|
|
and
|
|
.No pre- Ns 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
|
|
.At
|
|
and
|
|
.No pre- Ns Bx 4.3 reno
|
|
systems.
|
|
.It Cm lcase
|
|
Transform uppercase characters into lowercase characters.
|
|
.It Cm pareven , parnone , parodd , parset
|
|
Output data with the specified parity.
|
|
The parity bit on input is stripped unless
|
|
.Tn EBCDIC
|
|
to
|
|
.Tn ASCII
|
|
conversions is also specified.
|
|
.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
|
|
.Dv NUL
|
|
bytes (or with spaces if a block oriented conversion value was
|
|
specified) and processed as a normal input buffer.
|
|
If the
|
|
.Cm fillchar
|
|
option is specified, the fill character provided on the command line
|
|
will override
|
|
the automatic selection of the fill character.
|
|
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 = Ns Ar n
|
|
block size specification.
|
|
.It Cm sparse
|
|
If one or more 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 ,
|
|
resulting in a sparse file.
|
|
.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
|
|
.Dv 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 or speed are specified, a decimal, octal, or hexadecimal number of
|
|
bytes is expected.
|
|
If the number ends with a
|
|
.Dq Li b ,
|
|
.Dq Li k ,
|
|
.Dq Li m ,
|
|
.Dq Li g ,
|
|
.Dq Li t ,
|
|
.Dq Li p ,
|
|
or
|
|
.Dq Li w ,
|
|
the
|
|
number is multiplied by 512, 1024 (1K), 1048576 (1M), 1073741824 (1G),
|
|
1099511627776 (1T), 1125899906842624 (1P)
|
|
or the number of bytes in an integer, respectively.
|
|
Two or more numbers may be separated by an
|
|
.Dq Li x
|
|
to indicate a product.
|
|
.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
|
|
(see the
|
|
.Cm status
|
|
argument for
|
|
.Xr stty 1 )
|
|
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.
|
|
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 EXIT STATUS
|
|
.Ex -std
|
|
.Sh EXAMPLES
|
|
Check that a disk drive contains no bad blocks:
|
|
.Pp
|
|
.Dl "dd if=/dev/ada0 of=/dev/null bs=1m"
|
|
.Pp
|
|
Do a refresh of a disk drive, in order to prevent presently
|
|
recoverable read errors from progressing into unrecoverable read errors:
|
|
.Pp
|
|
.Dl "dd if=/dev/ada0 of=/dev/ada0 bs=1m"
|
|
.Pp
|
|
Remove parity bit from a file:
|
|
.Pp
|
|
.Dl "dd if=file conv=parnone of=file.txt"
|
|
.Pp
|
|
Check for (even) parity errors on a file:
|
|
.Pp
|
|
.Dl "dd if=file conv=pareven | cmp -x - file"
|
|
.Pp
|
|
To create an image of a Mode-1 CD-ROM, which is a commonly used format
|
|
for data CD-ROM disks, use a block size of 2048 bytes:
|
|
.Pp
|
|
.Dl "dd if=/dev/cd0 of=filename.iso bs=2048"
|
|
.Pp
|
|
Write a filesystem image to a memory stick, padding the end with zeros,
|
|
if necessary, to a 1MiB boundary:
|
|
.Pp
|
|
.Dl "dd if=memstick.img of=/dev/da0 bs=1m conv=noerror,sync"
|
|
.Sh SEE ALSO
|
|
.Xr cp 1 ,
|
|
.Xr mt 1 ,
|
|
.Xr recoverdisk 1 ,
|
|
.Xr tr 1 ,
|
|
.Xr geom 4
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
utility is expected to be a superset of the
|
|
.St -p1003.2
|
|
standard.
|
|
The
|
|
.Cm files
|
|
and
|
|
.Cm status
|
|
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 BUGS
|
|
Protection mechanisms in the
|
|
.Xr geom 4
|
|
subsystem might prevent the super-user from writing blocks to a disk.
|
|
Instructions for temporarily disabling these protection mechanisms can be
|
|
found in the
|
|
.Xr geom 4
|
|
manpage.
|