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