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