8980 BIOS clock is sometimes one hour fast
[unleashed.git] / usr / src / man / man1m / dd.1m
blobb2055ba264554add8c12566c94664ac35c839e06
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document.  The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
45 .\" Portions Copyright (c) 1995, Sun Microsystems, Inc.  All Rights Reserved
46 .\" Copyright (c) 2014, Joyent, Inc.  All rights Reserved.
47 .\" Copyright (c) 2014 by Delphix. All rights reserved.
48 .\"
49 .TH DD 1M "Dec 12, 2014"
50 .SH NAME
51 dd \- convert and copy a file
52 .SH SYNOPSIS
53 .LP
54 .nf
55 \fB/usr/bin/dd\fR [\fIoperand=value\fR]...
56 .fi
58 .SH DESCRIPTION
59 .LP
60 The \fBdd\fR utility copies the specified input file to the specified output
61 with possible conversions. The standard input and output are used by default.
62 The input and output block sizes may be specified to take advantage of raw
63 physical I/O. Sizes are specified in bytes; a number may end with \fBk\fR,
64 \fBb\fR, or \fBw\fR to specify multiplication by 1024, 512, or 2, respectively.
65 Numbers may also be separated by \fBx\fR to indicate multiplication.
66 .sp
67 .LP
68 The \fBdd\fR utility reads the input one block at a time, using the specified
69 input block size. \fBdd\fR then processes the block of data actually returned,
70 which could be smaller than the requested block size. \fBdd\fR applies any
71 conversions that have been specified and writes the resulting data to the
72 output in blocks of the specified output block size.
73 .sp
74 .LP
75 \fBcbs\fR is used only if \fBascii\fR, \fBasciib\fR, \fBunblock\fR,
76 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, \fBibmb\fR, or \fBblock\fR conversion
77 is specified. In the first two cases, \fBcbs\fR characters are copied into the
78 conversion buffer, any specified character mapping is done, trailing blanks are
79 trimmed, and a \fBNEWLINE\fR is added before sending the line to output. In the
80 last three cases, characters up to \fBNEWLINE\fR are read into the conversion
81 buffer and blanks are added to make up an output record of size \fBcbs\fR.
82 \fBASCII\fR files are presumed to contain \fBNEWLINE\fR characters. If
83 \fBcbs\fR is unspecified or \fB0\fR, the \fBascii\fR, \fBasciib\fR,
84 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR options convert the
85 character set without changing the input file's block structure. The
86 \fBunblock\fR and \fBblock\fR options become a simple file copy.
87 .sp
88 .LP
89 After completion, \fBdd\fR reports the number of whole and partial input and
90 output blocks.
91 .SH OPERANDS
92 .LP
93 The following operands are supported:
94 .sp
95 .ne 2
96 .na
97 \fB\fBif=\fR\fIfile\fR\fR
98 .ad
99 .sp .6
100 .RS 4n
101 Specifies the input path. Standard input is the default.
105 .ne 2
107 \fB\fBof=\fR\fIfile\fR\fR
109 .sp .6
110 .RS 4n
111 Specifies the output path. Standard output is the default. If the
112 \fBseek=\fR\fBexpr\fR conversion is not also specified, the output file will be
113 truncated before the copy begins, unless \fBconv=notrunc\fR is specified. If
114 \fBseek=\fR\fBexpr\fR is specified, but \fBconv=notrunc\fR is not, the effect
115 of the copy will be to preserve the blocks in the output file over which
116 \fBdd\fR seeks, but no other portion of the output file will be preserved. (If
117 the size of the seek plus the size of the input file is less than the previous
118 size of the output file, the output file is shortened by the copy.)
122 .ne 2
124 \fB\fBibs=\fR\fIn\fR\fR
126 .sp .6
127 .RS 4n
128 Specifies the input block size in \fIn\fR bytes (default is \fB512\fR).
132 .ne 2
134 \fB\fBobs=\fR\fIn\fR\fR
136 .sp .6
137 .RS 4n
138 Specifies the output block size in \fIn\fR bytes (default is \fB512\fR).
142 .ne 2
144 \fB\fBbs=\fR\fIn\fR\fR
146 .sp .6
147 .RS 4n
148 Sets both input and output block sizes to \fIn\fR bytes, superseding \fBibs=\fR
149 and \fBobs=\fR. If no conversion other than \fBsync\fR,\fB noerror\fR, and
150 \fBnotrunc\fR is specified, each input block is copied to the output as a
151 single block without aggregating short blocks.
155 .ne 2
157 \fB\fBcbs=\fR\fIn\fR\fR
159 .sp .6
160 .RS 4n
161 Specifies the conversion block size for \fBblock\fR and \fBunblock\fR in bytes
162 by \fIn\fR (default is \fB0\fR). If \fBcbs=\fR is omitted or given a value of
163 \fB0\fR, using \fBblock\fR or \fBunblock\fR produces unspecified results.
165 This option is used only if \fBASCII\fR or \fBEBCDIC\fR conversion is
166 specified. For the \fBascii\fR and \fBasciib\fR operands, the input is handled
167 as described for the \fBunblock\fR operand except that characters are converted
168 to \fBASCII\fR before the trailing \fBSPACE\fR characters are deleted. For the
169 \fBebcdic\fR, \fBebcdicb\fR, \fBibm\fR, and \fBibmb\fR operands, the input is
170 handled as described for the \fBblock\fR operand except that the characters are
171 converted to \fBEBCDIC\fR or IBM \fBEBCDIC\fR after the trailing \fBSPACE\fR
172 characters are added.
176 .ne 2
178 \fB\fBfiles=\fR\fIn\fR\fR
180 .sp .6
181 .RS 4n
182 Copies and concatenates \fIn\fR input files before terminating (makes sense
183 only where input is a magnetic tape or similar device).
187 .ne 2
189 \fB\fBskip=\fR\fIn\fR\fR
191 .sp .6
192 .RS 4n
193 Skips \fIn\fR input blocks (using the specified input block size) before
194 starting to copy. On seekable files, the implementation reads the blocks or
195 seeks past them. On non-seekable files, the blocks are read and the data is
196 discarded.
200 .ne 2
202 \fB\fBiseek=\fR\fIn\fR\fR
204 .sp .6
205 .RS 4n
206 Seeks \fIn\fR blocks from beginning of input file before copying (appropriate
207 for disk files, where \fBskip\fR can be incredibly slow).
211 .ne 2
213 \fB\fBoseek=\fR\fIn\fR\fR
215 .sp .6
216 .RS 4n
217 Seeks \fIn\fR blocks from beginning of output file before copying.
221 .ne 2
223 \fB\fBseek=\fR\fIn\fR\fR
225 .sp .6
226 .RS 4n
227 Skips \fIn\fR blocks (using the specified output block size) from beginning of
228 output file before copying. On non-seekable files, existing blocks are read and
229 space from the current end-of-file to the specified offset, if any, is filled
230 with null bytes. On seekable files, the implementation seeks to the specified
231 offset or reads the blocks as described for non-seekable files.
235 .ne 2
237 \fB\fBostride=\fR\fIn\fR\fR
239 .sp .6
240 .RS 4n
241 Writes every \fIn\fRth block (using the specified output block size) when
242 writing output.  Skips \fIn\fR - 1 blocks after writing each record.
246 .ne 2
248 \fB\fBistride=\fR\fIn\fR\fR
250 .sp .6
251 .RS 4n
252 Reads every \fIn\fRth block (using the specified input block size) when
253 reading input.  Skips \fIn\fR - 1 blocks after reading each record.
257 .ne 2
259 \fB\fBstride=\fR\fIn\fR\fR
261 .sp .6
262 .RS 4n
263 Reads every \fIn\fRth block (using the specified input block size) when
264 reading input.  Skips \fIn\fR - 1 blocks after reading each record.  Also
265 writes every \fIn\fRth block (using the specified output block size) when
266 writing output.  Skips \fIn\fR - 1 blocks after writing each record.
270 .ne 2
272 \fB\fBcount=\fR\fIn\fR\fR
274 .sp .6
275 .RS 4n
276 Copies only \fIn\fR input blocks.
280 .ne 2
282 \fB\fBconv=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
284 .sp .6
285 .RS 4n
286 Where \fIvalue\fRs are comma-separated symbols from the following list:
288 .ne 2
290 \fB\fBascii\fR\fR
292 .RS 11n
293 Converts \fBEBCDIC\fR to \fBASCII\fR.
297 .ne 2
299 \fB\fBasciib\fR\fR
301 .RS 11n
302 Converts \fBEBCDIC\fR to \fBASCII\fR using \fBBSD\fR-compatible character
303 translations.
307 .ne 2
309 \fB\fBebcdic\fR\fR
311 .RS 11n
312 Converts \fBASCII\fR to \fBEBCDIC\fR. If converting fixed-length \fBASCII\fR
313 records without NEWLINEs, sets up a pipeline with \fBdd conv=unblock\fR
314 beforehand.
318 .ne 2
320 \fB\fBebcdicb\fR\fR
322 .RS 11n
323 Converts \fBASCII\fR to \fBEBCDIC\fR using \fBBSD\fR-compatible character
324 translations. If converting fixed-length \fBASCII\fR records without
325 \fBNEWLINE\fRs, sets up a pipeline with \fBdd conv=unblock\fR beforehand.
329 .ne 2
331 \fB\fBibm\fR\fR
333 .RS 11n
334 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR. If converting
335 fixed-length \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline
336 with \fBdd conv=unblock\fR beforehand.
340 .ne 2
342 \fB\fBibmb\fR\fR
344 .RS 11n
345 Slightly different map of \fBASCII\fR to \fBEBCDIC\fR using
346 \fBBSD\fR-compatible character translations. If converting fixed-length
347 \fBASCII\fR records without \fBNEWLINE\fRs, sets up a pipeline with \fBdd
348 conv=unblock\fR beforehand.
351 The \fBascii\fR (or \fBasciib\fR), \fBebcdic\fR (or \fBebcdicb\fR), and
352 \fBibm\fR (or \fBibmb\fR) values are mutually exclusive.
354 .ne 2
356 \fB\fBblock\fR\fR
358 .RS 11n
359 Treats the input as a sequence of \fBNEWLINE\fR-terminated or
360 \fBEOF\fR-terminated variable-length records independent of the input block
361 boundaries. Each record is converted to a record with a fixed length specified
362 by the conversion block size. Any \fBNEWLINE\fR character is removed from the
363 input line. \fBSPACE\fR characters are appended to lines that are shorter than
364 their conversion block size to fill the block. Lines that are longer than the
365 conversion block size are truncated to the largest number of characters that
366 will fit into that size. The number of truncated lines is reported.
370 .ne 2
372 \fB\fBunblock\fR\fR
374 .RS 11n
375 Converts fixed-length records to variable length. Reads a number of bytes equal
376 to the conversion block size (or the number of bytes remaining in the input, if
377 less than the conversion block size), delete all trailing \fBSPACE\fR
378 characters, and append a \fBNEWLINE\fR character.
381 The  \fBblock\fR and \fBunblock\fR values are mutually exclusive.
383 .ne 2
385 \fB\fBlcase\fR\fR
387 .RS 9n
388 Maps upper-case characters specified by the \fBLC_CTYPE\fR keyword
389 \fBtolower\fR to the corresponding lower-case character. Characters for which
390 no mapping is specified are not modified by this conversion.
394 .ne 2
396 \fB\fBucase\fR\fR
398 .RS 9n
399 Maps lower-case characters specified by the \fBLC_CTYPE\fR keyword
400 \fBtoupper\fR to the corresponding upper-case character. Characters for which
401 no mapping is specified are not modified by this conversion.
404 The \fBlcase\fR and \fBucase\fR symbols are mutually exclusive.
406 .ne 2
408 \fB\fBswab\fR\fR
410 .RS 11n
411 Swaps every pair of input bytes. If the current input record is an odd number
412 of bytes, the last byte in the input record is ignored.
416 .ne 2
418 \fB\fBnoerror\fR\fR
420 .RS 11n
421 Does not stop processing on an input error. When an input error occurs, a
422 diagnostic message is written on standard error, followed by the current input
423 and output block counts in the same format as used at completion. If the
424 \fBsync\fR conversion is specified, the missing input is replaced with null
425 bytes and processed normally. Otherwise, the input block will be omitted from
426 the output.
430 .ne 2
432 \fB\fBnotrunc\fR\fR
434 .RS 11n
435 Does not truncate the output file. Preserves blocks in the output file not
436 explicitly written by this invocation of \fBdd\fR. (See also the preceding
437 \fBof=\fR\fIfile\fR operand.)
441 .ne 2
443 \fB\fBsync\fR\fR
445 .RS 11n
446 Pads every input block to the size of the \fBibs=\fR buffer, appending null
447 bytes. (If either \fBblock\fR or \fBunblock\fR is also specified, appends
448 \fBSPACE\fR characters, rather than null bytes.)
454 .ne 2
456 \fB\fBoflag=\fR\fIvalue\fR[\fB,\fR\fIvalue\fR.\|.\|.\|]\fR
458 .sp .6
459 Where \fIvalue\fRs are comma-separated symbols from the following list which
460 affect the behavior of writing the output file:
462 .ne 2
464 \fB\fBdsync\fR\fR
466 .RS 11n
467 The output file is opened with the \fBO_DSYNC\fR flag set. All data writes will
468 be synchronous. For more information on \fBO_DSYNC\fR see \fBfcntl.h\fR(3HEAD).
472 .ne 2
474 \fB\fBsync\fR\fR
476 .RS 11n
477 The output file is opened with the \fBO_SYNC\fR flag set. All data and metadata
478 writes will be synchronous. For more information on \fBO_SYNC\fR see
479 \fBfcntl.h\fR(3HEAD).
484 If operands other than \fBconv=\fR and \fBoflag=\fR are specified more than once,
485 the last specified \fBoperand=\fR\fIvalue\fR is used.
488 For the \fBbs=\fR, \fBcbs=\fR, \fBibs=\fR, and \fBobs=\fR operands, the
489 application must supply an expression specifying a size in bytes. The
490 expression, \fBexpr\fR, can be:
491 .RS +4
494 a positive decimal number
496 .RS +4
499 a positive decimal number followed by \fBk\fR, specifying multiplication by
500 1024
502 .RS +4
505 a positive decimal number followed by \fBM\fR, specifying multiplication by
506 1024*1024
508 .RS +4
511 a positive decimal number followed by \fBG\fR, specifying multiplication by
512 1024*1024*1024
514 .RS +4
517 a positive decimal number followed by \fBT\fR, specifying multiplication by
518 1024*1024*1024*1024
520 .RS +4
523 a positive decimal number followed by \fBP\fR, specifying multiplication by
524 1024*1024*1024*1024*1024
526 .RS +4
529 a positive decimal number followed by \fBE\fR, specifying multiplication by
530 1024*1024*1024*1024*1024*1024
532 .RS +4
535 a positive decimal number followed by \fBZ\fR, specifying multiplication by
536 1024*1024*1024*1024*1024*1024*1024
538 .RS +4
541 a positive decimal number followed by \fBb\fR, specifying multiplication by
544 .RS +4
547 two or more positive decimal numbers (with or without \fBk\fR or \fBb\fR)
548 separated by \fBx\fR, specifying the product of the indicated values.
552 All of the operands will be processed before any input is read.
553 .SH SIGNALS
555 When \fBdd\fR receives either SIGINFO or SIGUSR1, \fBdd\fR will emit the current
556 input and output block counts, total bytes written, total time elapsed, and the
557 number of bytes per second to standard error. This is the same information
558 format that \fBdd\fR emits when it successfully completes. Users may send
559 SIGINFO via their terminal. The default character is ^T, see \fBstty\fR(1) for
560 more information.
563 For \fBSIGINT\fR, \fBdd\fR writes status information to standard error before
564 exiting. \fBdd\fR takes the standard action for all other signals.
566 .SH USAGE
568 See \fBlargefile\fR(5) for the description of the behavior of \fBdd\fR when
569 encountering files greater than or equal to 2 Gbyte ( 2^31 bytes).
570 .SH EXAMPLES
572 \fBExample 1 \fRCopying from one tape drive to another
575 The following example copies from tape drive \fB0\fR to tape drive \fB1\fR,
576 using a common historical device naming convention.
579 .in +2
581 example% \fBdd if=/dev/rmt/0h  of=/dev/rmt/1h\fR
583 .in -2
587 \fBExample 2 \fRStripping the first 10 bytes from standard input
590 The following example strips the first 10 bytes from standard input:
593 .in +2
595 example% \fBdd ibs=10  skip=1\fR
597 .in -2
601 \fBExample 3 \fRReading a tape into an ASCII file
604 This example reads an \fBEBCDIC\fR tape blocked ten 80-byte \fBEBCDIC\fR card
605 images per block into the \fBASCII\fR file \fBx\fR:
608 .in +2
610 example% \fBdd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase\fR
612 .in -2
616 \fBExample 4 \fRUsing conv=sync to write to tape
619 The following example uses \fBconv=sync\fR when writing to a tape:
622 .in +2
624 example% \fBtar cvf - . | compress | dd obs=1024k of=/dev/rmt/0 conv=sync\fR
626 .in -2
629 .SH ENVIRONMENT VARIABLES
631 See \fBenviron\fR(5) for descriptions of the following environment variables
632 that affect the execution of \fBdd\fR: \fBLANG\fR, \fBLC_ALL\fR,
633 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
634 .SH EXIT STATUS
636 The following exit values are returned:
638 .ne 2
640 \fB\fB0\fR\fR
642 .RS 6n
643 The input file was copied successfully.
647 .ne 2
649 \fB\fB>0\fR\fR
651 .RS 6n
652 An error occurred.
657 If an input error is detected and the \fBnoerror\fR conversion has not been
658 specified, any partial output block will be written to the output file, a
659 diagnostic message will be written, and the copy operation will be
660 discontinued. If some other error is detected, a diagnostic message will be
661 written and the copy operation will be discontinued.
662 .SH ATTRIBUTES
664 See \fBattributes\fR(5) for descriptions of the following attributes:
669 box;
670 c | c
671 l | l .
672 ATTRIBUTE TYPE  ATTRIBUTE VALUE
674 Interface Stability     Standard
677 .SH SEE ALSO
679 \fBcp\fR(1), \fBsed\fR(1), \fBtr\fR(1), \fBfcntl.h\fR(3HEAD),
680 \fBattributes\fR(5), \fBenviron\fR(5), \fBlargefile\fR(5), \fBstandards\fR(5)
681 .SH DIAGNOSTICS
682 .ne 2
684 \fB\fBf+p records in(out)\fR\fR
686 .RS 23n
687 numbers of full and partial blocks read(written)
690 .SH NOTES
692 Do not use \fBdd\fR to copy files between file systems having different block
693 sizes.
696 Using a  blocked device to copy a file will result in extra nulls being added
697 to the file to pad the final block to the block boundary.
700 When  \fBdd\fR reads from a pipe, using the  \fBibs=X\fR and  \fBobs=Y\fR
701 operands, the output will always be blocked in chunks of size Y. When
702 \fBbs=Z\fR is used, the output blocks will be whatever was available to be read
703 from the pipe at the time.
706 When using \fBdd\fR to copy files to a tape device, the file size must be a
707 multiple of the device sector size (for example, 512 Kbyte).  To  copy files of
708 arbitrary size to a tape device, use  \fBtar\fR(1) or  \fBcpio\fR(1).