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