diff options
Diffstat (limited to 'bin/dd/dd.1')
| -rw-r--r-- | bin/dd/dd.1 | 588 |
1 files changed, 588 insertions, 0 deletions
diff --git a/bin/dd/dd.1 b/bin/dd/dd.1 new file mode 100644 index 0000000..44ea896 --- /dev/null +++ b/bin/dd/dd.1 @@ -0,0 +1,588 @@ +.\" $NetBSD: dd.1,v 1.36 2019/01/30 10:28:50 wiz 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 January 29, 2019 +.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 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 . |