Annotation of src/bin/dd/dd.1, Revision 1.3
1.3 ! mycroft 1: .\" Copyright (c) 1990, 1993
! 2: .\" The Regents of the University of California. All rights reserved.
1.1 glass 3: .\"
4: .\" This code is derived from software contributed to Berkeley by
5: .\" Keith Muller of the University of California, San Diego.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
1.3 ! mycroft 35: .\" from: @(#)dd.1 8.2 (Berkeley) 1/13/94
1.2 mycroft 36: .\" $Id: $
1.1 glass 37: .\"
1.3 ! mycroft 38: .Dd January 13, 1994
1.1 glass 39: .Dt DD 1
40: .Os
41: .Sh NAME
42: .Nm dd
1.3 ! mycroft 43: .Nd convert and copy a file
1.1 glass 44: .Sh SYNOPSIS
45: .Nm dd
46: .Op operands ...
47: .Sh DESCRIPTION
48: The
49: .Nm
50: utility copies the standard input to the standard output.
51: Input data is read and written in 512-byte blocks.
52: If input reads are short, input from multiple reads are aggregated
53: to form the output block.
54: When finished,
55: .Nm dd
56: displays the number of complete and partial input and output blocks
57: and truncated input records to the standard error output.
58: .Pp
59: The following operands are available:
60: .Bl -tag -width of=file
61: .It Cm bs= Ns Ar n
62: Set both input and output block size, superseding the
63: .Cm ibs
64: and
65: .Cm obs
66: operands.
67: If no conversion values other than
68: .Cm noerror ,
69: .Cm notrunc
70: or
71: .Cm sync
72: are specified, then each input block is copied to the output as a
73: single block without any aggregation of short blocks.
74: .It Cm cbs= Ns Ar n
75: Set the conversion record size to
76: .Va n
77: bytes.
78: The conversion record size is required by the record oriented conversion
79: values.
80: .It Cm count= Ns Ar n
81: Copy only
82: .Va n
83: input blocks.
84: .It Cm files= Ns Ar n
85: Copy
86: .Va n
87: input files before terminating.
88: This operand is only applicable when the input device is a tape.
89: .It Cm ibs= Ns Ar n
90: Set the input block size to
91: .Va n
92: bytes instead of the default 512.
93: .It Cm if= Ns Ar file
94: Read input from
95: .Ar file
96: instead of the standard input.
97: .It Cm obs= Ns Ar n
98: Set the output block size to
99: .Va n
100: bytes instead of the default 512.
101: .It Cm of= Ns Ar file
102: Write output to
103: .Ar file
104: instead of the standard output.
105: Any regular output file is truncated unless the
106: .Cm notrunc
107: conversion value is specified.
108: If an initial portion of the output file is skipped (see the
109: .Cm seek
110: operand)
111: the output file is truncated at that point.
112: .It Cm seek= Ns Ar n
113: Seek
114: .Va n
115: blocks from the beginning of the output before copying.
116: On non-tape devices, a
117: .Xr lseek 2
118: operation is used.
119: Otherwise, existing blocks are read and the data discarded.
120: If the user does not have read permission for the tape, it is positioned
121: using the tape
122: .Xr ioctl 2
123: function calls.
124: If the seek operation is past the end of file, space from the current
125: end of file to the specified offset is filled with blocks of
126: .Tn NUL
127: bytes.
128: .It Cm skip= Ns Ar n
129: Skip
130: .Va n
131: blocks from the beginning of the input before copying.
132: On input which supports seeks, a
133: .Xr lseek 2
134: operation is used.
135: Otherwise, input data is read and discarded.
136: For pipes, the correct number of bytes is read.
137: For all other devices, the correct number of blocks is read without
138: distinguishing between a partial or complete block being read.
139: .It Xo
140: .Cm conv=
141: .Ns Cm value Ns Op \&, Cm value \&...
142: .Xc
143: Where
144: .Cm value
145: is one of the symbols from the following list.
146: .Bl -tag -width unblock
147: .It Cm ascii , oldascii
148: The same as the
149: .Cm unblock
150: value except that characters are translated from
151: .Tn ECBDIC
152: to
153: .Tn ASCII
154: before the
155: records are converted.
156: (These values imply
157: .Cm unblock
158: if the operand
159: .Cm cbs
160: is also specified.)
161: There are two conversion maps for
162: .Tn ASCII .
163: The value
164: .Cm ascii
165: specifies the recommended one which is compatible with System V.
166: The value
167: .Cm oldascii
168: specifies the one used in historic
169: .Tn AT&T
1.3 ! mycroft 170: and pre-4.3BSD-reno systems.
1.1 glass 171: .It Cm block
172: Treats the input as a sequence of newline or end-of-file terminated variable
173: length records independent of input and output block boundaries.
174: Any trailing newline character is discarded.
175: Each input record is converted to a fixed length output record where the
176: length is specified by the
177: .Cm cbs
178: operand.
179: Input records shorter than the conversion record size are padded with spaces.
180: Input records longer than the conversion record size are truncated.
181: The number of truncated input records, if any, are reported to the standard
1.3 ! mycroft 182: error output at the completion of the copy.
1.1 glass 183: .It Cm ebcdic , ibm , oldebcdic , oldibm
184: The same as the
185: .Cm block
186: value except that characters are translated from
187: .Tn ASCII
188: to
189: .Tn EBCDIC
190: after the
191: records are converted.
192: (These values imply
193: .Cm block
194: if the operand
195: .Cm cbs
196: is also specified.)
197: There are four conversion maps for
198: .Tn EBCDIC .
199: The value
200: .Cm ebcdic
201: specifies the recommended one which is compatible with
202: .At V .
203: The value
204: .Cm ibm
205: is a slightly different mapping, which is compatible with the
206: .At V
207: .Cm ibm
208: value.
209: The values
210: .Cm oldebcdic
211: and
212: .Cm oldibm
213: are maps used in historic
214: .Tn AT&T
1.3 ! mycroft 215: and pre-4.3BSD-reno systems.
1.1 glass 216: .It Cm lcase
217: Transform uppercase characters into lowercase characters.
218: .It Cm noerror
219: Do not stop processing on an input error.
220: When an input error occurs, a diagnostic message followed by the current
1.3 ! mycroft 221: input and output block counts will be written to the standard error output
! 222: in the same format as the standard completion message.
1.1 glass 223: If the
224: .Cm sync
225: conversion is also specified, any missing input data will be replaced
226: with
227: .Tn NUL
228: bytes (or with spaces if a block oriented conversion value was
229: specified) and processed as a normal input buffer.
230: If the
231: .Cm sync
232: conversion is not specified, the input block is omitted from the output.
233: On input files which are not tapes or pipes, the file offset
234: will be positioned past the block in which the error occurred using
235: .Xr lseek 2 .
236: .It Cm notrunc
237: Do not truncate the output file.
238: This will preserve any blocks in the output file not explicitly written
239: by
240: .Nm dd .
241: The
242: .Cm notrunc
243: value is not supported for tapes.
1.3 ! mycroft 244: .It Cm osync
! 245: Pad the final output block to the full output block size.
! 246: If the input file is not a multiple of the output block size
! 247: after conversion, this conversion forces the final output block
! 248: to be the same size as preceding blocks for use on devices that require
! 249: regularly sized blocks to be written.
! 250: This option is incompatible with use of the
! 251: .Cm bs= Ns Ar n
! 252: block size specification.
1.1 glass 253: .It Cm swab
254: Swap every pair of input bytes.
255: If an input buffer has an odd number of bytes, the last byte will be
256: ignored during swapping.
257: .It Cm sync
258: Pad every input block to the input buffer size.
259: Spaces are used for pad bytes if a block oriented conversion value is
260: specified, otherwise
261: .Tn NUL
262: bytes are used.
263: .It Cm ucase
264: Transform lowercase characters into uppercase characters.
265: .It Cm unblock
266: Treats the input as a sequence of fixed length records independent of input
267: and output block boundaries.
268: The length of the input records is specified by the
269: .Cm cbs
270: operand.
271: Any trailing space characters are discarded and a newline character is
272: appended.
273: .El
274: .El
275: .Pp
276: Where sizes are specified, a decimal number of bytes is expected.
277: If the number ends with a ``b'', ``k'', ``m'' or ``w'', the number
278: is multiplied by 512, 1024 (1K), 1048576 (1M) or the number of bytes
279: in an integer, respectively.
280: Two or more numbers may be separated by an ``x'' to indicate a product.
281: .Pp
282: When finished,
283: .Nm dd
284: displays the number of complete and partial input and output blocks,
285: truncated input records and odd-length byte-swapping blocks to the
286: standard error output.
287: A partial input block is one where less than the input block size
288: was read.
289: A partial output block is one where less than the output block size
290: was written.
291: Partial output blocks to tape devices are considered fatal errors.
292: Otherwise, the rest of the block will be written.
293: Partial output blocks to character devices will produce a warning message.
294: A truncated input block is one where a variable length record oriented
295: conversion value was specified and the input line was too long to
296: fit in the conversion record or was not newline terminated.
297: .Pp
298: Normally, data resulting from input or conversion or both are aggregated
299: into output blocks of the specified size.
300: After the end of input is reached, any remaining output is written as
301: a block.
302: This means that the final output block may be shorter than the output
303: block size.
304: .Pp
305: If
306: .Nm dd
307: receives a
308: .Dv SIGINFO
309: (see the ``status'' argument for
310: .Xr stty 1 )
311: signal, the current input and output block counts will
1.3 ! mycroft 312: be written to the standard error output
! 313: in the same format as the standard completion message.
1.1 glass 314: If
315: .Nm dd
316: receives a
317: .Dv SIGINT
318: signal, the current input and output block counts will
1.3 ! mycroft 319: be written to the standard error output
! 320: in the same format as the standard completion message and
1.1 glass 321: .Nm dd
322: will exit.
323: .Pp
324: The
325: .Nm dd
326: utility exits 0 on success and >0 if an error occurred.
327: .Sh SEE ALSO
328: .Xr cp 1 ,
329: .Xr mt 1 ,
330: .Xr tr 1
331: .Sh STANDARDS
332: The
333: .Nm dd
334: utility is expected to be a superset of the
335: .St -p1003.2
336: standard.
337: The
338: .Cm files
339: operand and the
340: .Cm ascii ,
341: .Cm ebcdic ,
342: .Cm ibm ,
343: .Cm oldascii ,
344: .Cm oldebcdic
345: and
346: .Cm oldibm
347: values are extensions to the
348: .Tn POSIX
349: standard.
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to dd.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / bin / dd