diff options
Diffstat (limited to 'bin/dd/dd.1')
| -rw-r--r-- | bin/dd/dd.1 | 450 |
1 files changed, 450 insertions, 0 deletions
diff --git a/bin/dd/dd.1 b/bin/dd/dd.1 new file mode 100644 index 0000000..0908642 --- /dev/null +++ b/bin/dd/dd.1 @@ -0,0 +1,450 @@ +.\"- +.\" 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 28, 2014 +.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 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 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 , +or +.Dq Li w , +the +number is multiplied by 512, 1024 (1K), 1048576 (1M), 1073741824 (1G) +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/acd0 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. |
