| blob | 8ae530e28562bd41f46bc22787280b568838fb65 |
1 '\" te
2 .\" Copyright (c) 2014, Joyent, Inc. All rights Reserved.
3 .\" Copyright (c) 2014 by Delphix. All rights reserved.
4 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
5 .\" Copyright 1989 AT&T
6 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc. All Rights Reserved
7 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
8 .\" http://www.opengroup.org/bookstore/.
9 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
10 .\" This notice shall appear on any product containing this material.
11 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
12 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
13 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
14 .TH DD 1M "Dec 12, 2014"
15 .SH NAME
16 dd \- convert and copy a file
17 .SH SYNOPSIS
18 .LP
19 .nf
20 \fB/usr/bin/dd\fR [\fIoperand=value\fR]...
21 .fi
23 .SH DESCRIPTION
24 .LP
25 The \fBdd\fR utility copies the specified input file to the specified output
26 with possible conversions. The standard input and output are used by default.
27 The input and output block sizes may be specified to take advantage of raw
28 physical I/O. Sizes are specified in bytes; a number may end with \fBk\fR,
29 \fBb\fR, or \fBw\fR to specify multiplication by 1024, 512, or 2, respectively.
30 Numbers may also be separated by \fBx\fR to indicate multiplication.
31 .sp
32 .LP
33 The \fBdd\fR utility reads the input one block at a time, using the specified
34 input block size. \fBdd\fR then processes the block of data actually returned,
35 which could be smaller than the requested block size. \fBdd\fR applies any
36 conversions that have been specified and writes the resulting data to the
37 output in blocks of the specified output block size.
38 .sp
39 .LP
40 \fBcbs\fR is used only if \fBascii\fR, \fBasciib\fR, \fBunblock\fR,
41 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, \fBibmb\fR, or \fBblock\fR conversion
42 is specified. In the first two cases, \fBcbs\fR characters are copied into the
43 conversion buffer, any specified character mapping is done, trailing blanks are
44 trimmed, and a \fBNEWLINE\fR is added before sending the line to output. In the
45 last three cases, characters up to \fBNEWLINE\fR are read into the conversion
46 buffer and blanks are added to make up an output record of size \fBcbs\fR.
47 \fBASCII\fR files are presumed to contain \fBNEWLINE\fR characters. If
48 \fBcbs\fR is unspecified or \fB0\fR, the \fBascii\fR, \fBasciib\fR,
49 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR options convert the
50 character set without changing the input file's block structure. The
51 \fBunblock\fR and \fBblock\fR options become a simple file copy.
52 .sp
53 .LP
54 After completion, \fBdd\fR reports the number of whole and partial input and
55 output blocks.
56 .SH OPERANDS
57 .LP
58 The following operands are supported:
59 .sp
60 .ne 2
61 .na
62 \fB\fBif=\fR\fIfile\fR\fR
63 .ad
64 .sp .6
65 .RS 4n
66 Specifies the input path. Standard input is the default.
67 .RE
69 .sp
70 .ne 2
71 .na
72 \fB\fBof=\fR\fIfile\fR\fR
73 .ad
74 .sp .6
75 .RS 4n
76 Specifies the output path. Standard output is the default. If the
77 \fBseek=\fR\fBexpr\fR conversion is not also specified, the output file will be
78 truncated before the copy begins, unless \fBconv=notrunc\fR is specified. If
79 \fBseek=\fR\fBexpr\fR is specified, but \fBconv=notrunc\fR is not, the effect
80 of the copy will be to preserve the blocks in the output file over which
81 \fBdd\fR seeks, but no other portion of the output file will be preserved. (If
82 the size of the seek plus the size of the input file is less than the previous
83 size of the output file, the output file is shortened by the copy.)
84 .RE
86 .sp
87 .ne 2
88 .na
89 \fB\fBibs=\fR\fIn\fR\fR
90 .ad
91 .sp .6
92 .RS 4n
93 Specifies the input block size in \fIn\fR bytes (default is \fB512\fR).
94 .RE
96 .sp
97 .ne 2
98 .na
99 \fB\fBobs=\fR\fIn\fR\fR
100 .ad
101 .sp .6
102 .RS 4n
103 Specifies the output block size in \fIn\fR bytes (default is \fB512\fR).
104 .RE
106 .sp
107 .ne 2
108 .na
109 \fB\fBbs=\fR\fIn\fR\fR
110 .ad
111 .sp .6
112 .RS 4n
113 Sets both input and output block sizes to \fIn\fR bytes, superseding \fBibs=\fR
114 and \fBobs=\fR. If no conversion other than \fBsync\fR,\fB noerror\fR, and
115 \fBnotrunc\fR is specified, each input block is copied to the output as a
116 single block without aggregating short blocks.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fB\fBcbs=\fR\fIn\fR\fR
123 .ad
124 .sp .6
125 .RS 4n
126 Specifies the conversion block size for \fBblock\fR and \fBunblock\fR in bytes
127 by \fIn\fR (default is \fB0\fR). If \fBcbs=\fR is omitted or given a value of
128 \fB0\fR, using \fBblock\fR or \fBunblock\fR produces unspecified results.
129 .sp
130 This option is used only if \fBASCII\fR or \fBEBCDIC\fR conversion is
131 specified. For the \fBascii\fR and \fBasciib\fR operands, the input is handled
132 as described for the \fBunblock\fR operand except that characters are converted
133 to \fBASCII\fR before the trailing \fBSPACE\fR characters are deleted. For the
134 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR operands, the input is
135 handled as described for the \fBblock\fR operand except that the characters are
136 converted to \fBEBCDIC\fR or IBM \fBEBCDIC\fR after the trailing \fBSPACE\fR
137 characters are added.
138 .RE
140 .sp
141 .ne 2
142 .na
143 \fB\fBfiles=\fR\fIn\fR\fR
144 .ad
145 .sp .6
146 .RS 4n
147 Copies and concatenates \fIn\fR input files before terminating (makes sense
148 only where input is a magnetic tape or similar device).
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBskip=\fR\fIn\fR\fR
155 .ad
156 .sp .6
157 .RS 4n
158 Skips \fIn\fR input blocks (using the specified input block size) before
159 starting to copy. On seekable files, the implementation reads the blocks or
160 seeks past them. On non-seekable files, the blocks are read and the data is
161 discarded.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBiseek=\fR\fIn\fR\fR
168 .ad
169 .sp .6
170 .RS 4n
171 Seeks \fIn\fR blocks from beginning of input file before copying (appropriate
172 for disk files, where \fBskip\fR can be incredibly slow).
173 .RE
175 .sp
176 .ne 2
177 .na
178 \fB\fBoseek=\fR\fIn\fR\fR
179 .ad
180 .sp .6
181 .RS 4n
182 Seeks \fIn\fR blocks from beginning of output file before copying.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBseek=\fR\fIn\fR\fR
189 .ad
190 .sp .6
191 .RS 4n
192 Skips \fIn\fR blocks (using the specified output block size) from beginning of
193 output file before copying. On non-seekable files, existing blocks are read and
194 space from the current end-of-file to the specified offset, if any, is filled
195 with null bytes. On seekable files, the implementation seeks to the specified
196 offset or reads the blocks as described for non-seekable files.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fBostride=\fR\fIn\fR\fR
203 .ad
204 .sp .6
205 .RS 4n
206 Writes every \fIn\fRth block (using the specified output block size) when
207 writing output. Skips \fIn\fR - 1 blocks after writing each record.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBistride=\fR\fIn\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 Reads every \fIn\fRth block (using the specified input block size) when
218 reading input. Skips \fIn\fR - 1 blocks after reading each record.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBstride=\fR\fIn\fR\fR
225 .ad
226 .sp .6
227 .RS 4n
228 Reads every \fIn\fRth block (using the specified input block size) when
229 reading input. Skips \fIn\fR - 1 blocks after reading each record. Also
230 writes every \fIn\fRth block (using the specified output block size) when
231 writing output. Skips \fIn\fR - 1 blocks after writing each record.
232 .RE
234 .sp
235 .ne 2
236 .na
237 \fB\fBcount=\fR\fIn\fR\fR
238 .ad
239 .sp .6
240 .RS 4n
241 Copies only \fIn\fR input blocks.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fBconv=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
248 .ad
249 .sp .6
250 .RS 4n
251 Where \fIvalue\fRs are comma-separated symbols from the following list:
252 .sp
253 .ne 2
254 .na
255 \fB\fBascii\fR\fR
256 .ad
257 .RS 11n
258 Converts \fBEBCDIC\fR to \fBASCII\fR.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fBasciib\fR\fR
265 .ad
266 .RS 11n
267 Converts \fBEBCDIC\fR to \fBASCII\fR using \fBBSD\fR-compatible character
268 translations.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBebcdic\fR\fR
275 .ad
276 .RS 11n
277 Converts \fBASCII\fR to \fBEBCDIC\fR. If converting fixed-length \fBASCII\fR
278 records without NEWLINEs, sets up a pipeline with \fBdd conv=unblock\fR
279 beforehand.
280 .RE
282 .sp
283 .ne 2
284 .na
285 \fB\fBebcdicb\fR\fR
286 .ad
287 .RS 11n
288 Converts \fBASCII\fR to \fBEBCDIC\fR using \fBBSD\fR-compatible character
289 translations. If converting fixed-length \fBASCII\fR records without
290 \fBNEWLINE\fRs, sets up a pipeline with \fBdd conv=unblock\fR beforehand.
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fBibm\fR\fR
297 .ad
298 .RS 11n
299 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR. If converting
300 fixed-length \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline
301 with \fBdd conv=unblock\fR beforehand.
302 .RE
304 .sp
305 .ne 2
306 .na
307 \fB\fBibmb\fR\fR
308 .ad
309 .RS 11n
310 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR using
311 \fBBSD\fR-compatible character translations. If converting fixed-length
312 \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline with \fBdd
313 conv=unblock\fR beforehand.
314 .RE
316 The \fBascii\fR (or \fBasciib\fR), \fBebcdic\fR (or \fBebcdicb\fR), and
317 \fBibm\fR (or \fBibmb\fR) values are mutually exclusive.
318 .sp
319 .ne 2
320 .na
321 \fB\fBblock\fR\fR
322 .ad
323 .RS 11n
324 Treats the input as a sequence of \fBNEWLINE\fR-terminated or
325 \fBEOF\fR-terminated variable-length records independent of the input block
326 boundaries. Each record is converted to a record with a fixed length specified
327 by the conversion block size. Any \fBNEWLINE\fR character is removed from the
328 input line. \fBSPACE\fR characters are appended to lines that are shorter than
329 their conversion block size to fill the block. Lines that are longer than the
330 conversion block size are truncated to the largest number of characters that
331 will fit into that size. The number of truncated lines is reported.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fB\fBunblock\fR\fR
338 .ad
339 .RS 11n
340 Converts fixed-length records to variable length. Reads a number of bytes equal
341 to the conversion block size (or the number of bytes remaining in the input, if
342 less than the conversion block size), delete all trailing \fBSPACE\fR
343 characters, and append a \fBNEWLINE\fR character.
344 .RE
346 The \fBblock\fR and \fBunblock\fR values are mutually exclusive.
347 .sp
348 .ne 2
349 .na
350 \fB\fBlcase\fR\fR
351 .ad
352 .RS 9n
353 Maps upper-case characters specified by the \fBLC_CTYPE\fR keyword
354 \fBtolower\fR to the corresponding lower-case character. Characters for which
355 no mapping is specified are not modified by this conversion.
356 .RE
358 .sp
359 .ne 2
360 .na
361 \fB\fBucase\fR\fR
362 .ad
363 .RS 9n
364 Maps lower-case characters specified by the \fBLC_CTYPE\fR keyword
365 \fBtoupper\fR to the corresponding upper-case character. Characters for which
366 no mapping is specified are not modified by this conversion.
367 .RE
369 The \fBlcase\fR and \fBucase\fR symbols are mutually exclusive.
370 .sp
371 .ne 2
372 .na
373 \fB\fBswab\fR\fR
374 .ad
375 .RS 11n
376 Swaps every pair of input bytes. If the current input record is an odd number
377 of bytes, the last byte in the input record is ignored.
378 .RE
380 .sp
381 .ne 2
382 .na
383 \fB\fBnoerror\fR\fR
384 .ad
385 .RS 11n
386 Does not stop processing on an input error. When an input error occurs, a
387 diagnostic message is written on standard error, followed by the current input
388 and output block counts in the same format as used at completion. If the
389 \fBsync\fR conversion is specified, the missing input is replaced with null
390 bytes and processed normally. Otherwise, the input block will be omitted from
391 the output.
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBnotrunc\fR\fR
398 .ad
399 .RS 11n
400 Does not truncate the output file. Preserves blocks in the output file not
401 explicitly written by this invocation of \fBdd\fR. (See also the preceding
402 \fBof=\fR\fIfile\fR operand.)
403 .RE
405 .sp
406 .ne 2
407 .na
408 \fB\fBsync\fR\fR
409 .ad
410 .RS 11n
411 Pads every input block to the size of the \fBibs=\fR buffer, appending null
412 bytes. (If either \fBblock\fR or \fBunblock\fR is also specified, appends
413 \fBSPACE\fR characters, rather than null bytes.)
414 .RE
416 .RE
418 .sp
419 .ne 2
420 .na
421 \fB\fBoflag=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
422 .ad
423 .sp .6
424 Where \fIvalue\fRs are comma-separated symbols from the following list which
425 affect the behavior of writing the output file:
426 .sp
427 .ne 2
428 .na
429 \fB\fBdsync\fR\fR
430 .ad
431 .RS 11n
432 The output file is opened with the \fBO_DSYNC\fR flag set. All data writes will
433 be synchronous. For more information on \fBO_DSYNC\fR see \fBfcntl.h\fR(3HEAD).
434 .RE
436 .sp
437 .ne 2
438 .na
439 \fB\fBsync\fR\fR
440 .ad
441 .RS 11n
442 The output file is opened with the \fBO_SYNC\fR flag set. All data and metadata
443 writes will be synchronous. For more information on \fBO_SYNC\fR see
444 \fBfcntl.h\fR(3HEAD).
445 .RE
447 .sp
448 .LP
449 If operands other than \fBconv=\fR and \fBoflag=\fR are specified more than once,
450 the last specified \fBoperand=\fR\fIvalue\fR is used.
451 .sp
452 .LP
453 For the \fBbs=\fR, \fBcbs=\fR, \fBibs=\fR, and \fBobs=\fR operands, the
454 application must supply an expression specifying a size in bytes. The
455 expression, \fBexpr\fR, can be:
456 .RS +4
457 .TP
458 1.
459 a positive decimal number
460 .RE
461 .RS +4
462 .TP
463 2.
464 a positive decimal number followed by \fBk\fR, specifying multiplication by
465 1024
466 .RE
467 .RS +4
468 .TP
469 3.
470 a positive decimal number followed by \fBM\fR, specifying multiplication by
471 1024*1024
472 .RE
473 .RS +4
474 .TP
475 4.
476 a positive decimal number followed by \fBG\fR, specifying multiplication by
477 1024*1024*1024
478 .RE
479 .RS +4
480 .TP
481 5.
482 a positive decimal number followed by \fBT\fR, specifying multiplication by
483 1024*1024*1024*1024
484 .RE
485 .RS +4
486 .TP
487 6.
488 a positive decimal number followed by \fBP\fR, specifying multiplication by
489 1024*1024*1024*1024*1024
490 .RE
491 .RS +4
492 .TP
493 7.
494 a positive decimal number followed by \fBE\fR, specifying multiplication by
495 1024*1024*1024*1024*1024*1024
496 .RE
497 .RS +4
498 .TP
499 8.
500 a positive decimal number followed by \fBZ\fR, specifying multiplication by
501 1024*1024*1024*1024*1024*1024*1024
502 .RE
503 .RS +4
504 .TP
505 9.
506 a positive decimal number followed by \fBb\fR, specifying multiplication by
507 512
508 .RE
509 .RS +4
510 .TP
511 10.
512 two or more positive decimal numbers (with or without \fBk\fR or \fBb\fR)
513 separated by \fBx\fR, specifying the product of the indicated values.
514 .RE
515 .sp
516 .LP
517 All of the operands will be processed before any input is read.
518 .SH SIGNALS
519 .LP
520 When \fBdd\fR receives either SIGINFO or SIGUSR1, \fBdd\fR will emit the current
521 input and output block counts, total bytes written, total time elapsed, and the
522 number of bytes per second to standard error. This is the same information
523 format that \fBdd\fR emits when it successfully completes. Users may send
524 SIGINFO via their terminal. The default character is ^T, see \fBstty\fR(1) for
525 more information.
526 .sp
527 .LP
528 For \fBSIGINT\fR, \fBdd\fR writes status information to standard error before
529 exiting. \fBdd\fR takes the standard action for all other signals.
531 .SH USAGE
532 .LP
533 See \fBlargefile\fR(5) for the description of the behavior of \fBdd\fR when
534 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
535 .SH EXAMPLES
536 .LP
537 \fBExample 1 \fRCopying from one tape drive to another
538 .sp
539 .LP
540 The following example copies from tape drive \fB0\fR to tape drive \fB1\fR,
541 using a common historical device naming convention.
543 .sp
544 .in +2
545 .nf
546 example% \fBdd if=/dev/rmt/0h of=/dev/rmt/1h\fR
547 .fi
548 .in -2
549 .sp
551 .LP
552 \fBExample 2 \fRStripping the first 10 bytes from standard input
553 .sp
554 .LP
555 The following example strips the first 10 bytes from standard input:
557 .sp
558 .in +2
559 .nf
560 example% \fBdd ibs=10 skip=1\fR
561 .fi
562 .in -2
563 .sp
565 .LP
566 \fBExample 3 \fRReading a tape into an ASCII file
567 .sp
568 .LP
569 This example reads an \fBEBCDIC\fR tape blocked ten 80-byte \fBEBCDIC\fR card
570 images per block into the \fBASCII\fR file \fBx\fR:
572 .sp
573 .in +2
574 .nf
575 example% \fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase\fR
576 .fi
577 .in -2
578 .sp
580 .LP
581 \fBExample 4 \fRUsing conv=sync to write to tape
582 .sp
583 .LP
584 The following example uses \fBconv=sync\fR when writing to a tape:
586 .sp
587 .in +2
588 .nf
589 example% \fBtar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync\fR
590 .fi
591 .in -2
592 .sp
594 .SH ENVIRONMENT VARIABLES
595 .LP
596 See \fBenviron\fR(5) for descriptions of the following environment variables
597 that affect the execution of \fBdd\fR: \fBLANG\fR, \fBLC_ALL\fR,
598 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
599 .SH EXIT STATUS
600 .LP
601 The following exit values are returned:
602 .sp
603 .ne 2
604 .na
605 \fB\fB0\fR\fR
606 .ad
607 .RS 6n
608 The input file was copied successfully.
609 .RE
611 .sp
612 .ne 2
613 .na
614 \fB\fB>0\fR\fR
615 .ad
616 .RS 6n
617 An error occurred.
618 .RE
620 .sp
621 .LP
622 If an input error is detected and the \fBnoerror\fR conversion has not been
623 specified, any partial output block will be written to the output file, a
624 diagnostic message will be written, and the copy operation will be
625 discontinued. If some other error is detected, a diagnostic message will be
626 written and the copy operation will be discontinued.
627 .SH ATTRIBUTES
628 .LP
629 See \fBattributes\fR(5) for descriptions of the following attributes:
630 .sp
632 .sp
633 .TS
634 box;
635 c | c
636 l | l .
637 ATTRIBUTE TYPE ATTRIBUTE VALUE
638 _
639 Interface Stability Standard
640 .TE
642 .SH SEE ALSO
643 .LP
644 \fBcp\fR(1), \fBsed\fR(1), \fBtr\fR(1), \fBfcntl.h\fR(3HEAD),
645 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
646 .SH DIAGNOSTICS
647 .ne 2
648 .na
649 \fB\fBf+p records in(out)\fR\fR
650 .ad
651 .RS 23n
652 numbers of full and partial blocks read(written)
653 .RE
655 .SH NOTES
656 .LP
657 Do not use \fBdd\fR to copy files between file systems having different block
658 sizes.
659 .sp
660 .LP
661 Using a blocked device to copy a file will result in extra nulls being added
662 to the file to pad the final block to the block boundary.
663 .sp
664 .LP
665 When \fBdd\fR reads from a pipe, using the \fBibs=X\fR and \fBobs=Y\fR
666 operands, the output will always be blocked in chunks of size Y. When
667 \fBbs=Z\fR is used, the output blocks will be whatever was available to be read
668 from the pipe at the time.
669 .sp
670 .LP
671 When using \fBdd\fR to copy files to a tape device, the file size must be a
672 multiple of the device sector size (for example, 512 Kbyte). To copy files of
673 arbitrary size to a tape device, use \fBtar\fR(1) or \fBcpio\fR(1).