BSD 4_4 release

[unix-history] / usr / src / bin / dd / dd.1

diff --git a/usr/src/bin/dd/dd.1 b/usr/src/bin/dd/dd.1
index aab3303..d47462c 100644 (file)
--- a/usr/src/bin/dd/dd.1
+++ b/usr/src/bin/dd/dd.1
@@ -1,189 +1,339 @@
-.\" Copyright (c) 1990 The Regents of the University of California.
-.\" All rights reserved.
+.\" Copyright (c) 1990, 1993
+.\"    The Regents of the University of California.  All rights reserved.

 .\"
 .\"

-.\" %sccs.include.redist.man%
+.\" This code is derived from software contributed to Berkeley by
+.\" Keith Muller of the University of California, San Diego.

 .\"
 .\"

-.\"     @(#)dd.1       6.3 (Berkeley) %G%
+.\" 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. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 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.

 .\"
 .\"

-.Dd 
+.\" 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.1 (Berkeley) 6/30/93
+.\"
+.Dd June 30, 1993

 .Dt DD 1
 .Dt DD 1

-.Os BSD 4.4
+.Os

 .Sh NAME
 .Nm dd
 .Nd convert and copy a file
 .Sh SYNOPSIS
 .Nm dd
 .Sh NAME
 .Nm dd
 .Nd convert and copy a file
 .Sh SYNOPSIS
 .Nm dd

-.Op options \&...
+.Op operands ...

 .Sh DESCRIPTION
 The
 .Nm
 .Sh DESCRIPTION
 The
 .Nm

-utility copies the specified input file to the specified
-output with possible conversions.
+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 dd
+displays the number of complete and partial input and output blocks
+and truncated input records to the standard error output.

 .Pp
 .Pp

-The following options are available:
-.Tw Fl
-.Tc Ic if=
-.Ar file
-.Cx
-Input pathname; standard input is
-default.
-.Tc Ic of=
-.Ar file
-.Cx
-Output pathname; standard output is
-default.
-.Tc Ic ibs=
-.Ar n
-.Cx
-Input block size
-.Va n
-bytes (default is
-512 bytes).
-.Tc Ic obs=
-.Ar n
-.Cx
-Output block size (default is 512 bytes).
-.Tc Ic bs=
-.Ar n
-.Cx
-Set both input and output block size,
-superseding
-.Ic ibs
+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
 and

-.Ic obs .
-.Tc Ic cbs=
-.Ar n
-.Cx
-Conversion buffer size
-.Tc Ic skip=
-.Ar n
-.Cx
-Skip
+.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
 .Va n

-input blocks (each block is the
-size of
-.Ic ibs )
-before starting copy.
-.Tc Ic seek=
-.Ar n
-.Cx
-Seek n blocks (each block is the size of
-obs) from beginning of output file before
-copying.
-.Tc Ic count=
-.Ar n
-.Cx
+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.
 Copy only
 .Va n
 input blocks.

-.Tc Ic conv=
-.Ar value
-.Oo
-.Op \&, Ar value \&...
-.Cx
-.Oo
-Where values are comma-separated symbols
-from the following list.
-.Tw Fl
-.Tp Ic block
-Convert variable length records to fixed
-length.
-Read characters into the
-.Ic cbs
-buffer, delete a trailing <newline>, and
-pad to the length of the
-.Ic cbs
-buffer with
-<space>s.
-.Ic block
-and
-.Ic unblock
-are mutually
-exclusive.
-.Tp Ic unblock
-Convert fixed length records to variable
-length.
-Read a number of characters
-equal to the size of the
-.Ic cbs
-buffer,
-delete all trailing <blank>s, and append
-a <newline>.
-.Tp Ic lcase
-Map characters in the alpha character
-classification from class upper to the
-corresponding value in class lower.
-.Ic lcase
+.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 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 seek= Ns Ar n
+Seek
+.Va n
+blocks from the beginning of the output before copying.
+On non-tape devices, a
+.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, a
+.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 Xo
+.Cm conv=
+.Ns Cm value Ns Op \&, Cm value \&...
+.Xc
+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 ECBDIC
+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 System V.
+The value
+.Cm oldascii
+specifies the one used in historic
+.Tn AT&T
+and pre-4.3BSD-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
 and

-.Ic ucase
-are mutually exclusive.
-.Tp Ic ucase
-Map characters in the alpha character
-classification from class lower to the
-corresponding value in class upper.
-.Tp Ic swab
-Swap every pair of bytes
-.Tp Ic noerror
-Do not stop processing on an error.
-.Tp Ic sync
-Pad every input block to the size of
-.Ic ibs
-buffer, appending <space> characters.
-.Tp
-.Tp
+.Cm oldibm
+are maps used in historic
+.Tn AT&T
+and pre-4.3BSD-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 dd .
+The
+.Cm notrunc
+value is not supported for tapes.
+.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
 .Pp

-Where sizes are specified, a decimal number of bytes is
-expected.
-A size can end with
-.Cm k
-or
-.Cm b
-to specify multiplication
-by 1024 or 512, respectively.
-A pair of sizes can be
-separated by
-.Cm x
-to indicate a product.
+Where sizes are specified, a decimal number of bytes is expected.
+If the number ends with a ``b'', ``k'', ``m'' or ``w'', the number
+is multiplied by 512, 1024 (1K), 1048576 (1M) or the number of bytes
+in an integer, respectively.
+Two or more numbers may be separated by an ``x'' to indicate a product.

 .Pp
 .Pp

-If the option
-.Ic if=
-is not specified, the standard input is used.
+When finished,
+.Nm dd
+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
 .Pp

-The input files can be any file type and
-on completion,
-.Nm
-writes the number of input and output
-blocks, full and partial counts, to the standard error.
+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
 .Pp

-A partial block may be caused by a read or write operation
-transferring less than
-.Ic ibs
-bytes.
-Only bytes read
-have conversions, as specified by the options, applied to
-them.
-.Pp
-For
-.Li SIGINT ,
-the
-.Nm
-utility writes status information to
-standard error before exiting.
-It takes the default action
-for all other signals.
+If
+.Nm dd
+receives a
+.Dv SIGINFO
+(see the ``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 dd
+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 dd
+will exit.

 .Pp
 The
 .Pp
 The

-.Nm
-utility exits 0 on success, and >0 if an error occurs.
-.Pp
-If an error is detected, and the noerror option has not
-been supplied, the cause is reported and the
-.Nm
-utility
-aborts the copy of the file.
+.Nm dd
+utility exits 0 on success and >0 if an error occurred.

 .Sh SEE ALSO
 .Sh SEE ALSO

+.Xr cp 1 ,
+.Xr mt 1 ,

 .Xr tr 1
 .Sh STANDARDS
 The
 .Xr tr 1
 .Sh STANDARDS
 The

-.Nm
-function is expected to be POSIX 1003.2 compatible.
+.Nm dd
+utility is expected to be a superset of the
+.St -p1003.2
+standard.
+The
+.Cm files
+operand and the
+.Cm ascii ,
+.Cm ebcdic ,
+.Cm ibm ,
+.Cm oldascii ,
+.Cm oldebcdic
+and
+.Cm oldibm
+values are extensions to the
+.Tn POSIX
+standard.