1DD(1P) POSIX Programmer's Manual DD(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 dd - convert and copy a file
13
15 dd [operand ...]
16
18 The dd utility shall copy the specified input file to the specified
19 output file with possible conversions using specific input and output
20 block sizes. It shall read the input one block at a time, using the
21 specified input block size; it shall then process the block of data
22 actually returned, which could be smaller than the requested block
23 size. It shall apply any conversions that have been specified and write
24 the resulting data to the output in blocks of the specified output
25 block size. If the bs= expr operand is specified and no conversions
26 other than sync, noerror, or notrunc are requested, the data returned
27 from each input block shall be written as a separate output block; if
28 the read returns less than a full block and the sync conversion is not
29 specified, the resulting output block shall be the same size as the
30 input block. If the bs= expr operand is not specified, or a conversion
31 other than sync, noerror, or notrunc is requested, the input shall be
32 processed and collected into full-sized output blocks until the end of
33 the input is reached.
34 The processing order shall be as follows:
36 1. An input block is read.
38 2. If the input block is shorter than the specified input block size
40 and the sync conversion is specified, null bytes shall be appended
41 to the input data up to the specified size. (If either block or
42 unblock is also specified, <space>s shall be appended instead of
43 null bytes.) The remaining conversions and output shall include the
44 pad characters as if they had been read from the input.
45 3. If the bs= expr operand is specified and no conversion other than
47 sync or noerror is requested, the resulting data shall be written
48 to the output as a single block, and the remaining steps are omit‐
49 ted.
50 4. If the swab conversion is specified, each pair of input data bytes
52 shall be swapped. If there is an odd number of bytes in the input
53 block, the last byte in the input record shall not be swapped.
54 5. Any remaining conversions ( block, unblock, lcase, and ucase) shall
56 be performed. These conversions shall operate on the input data
57 independently of the input blocking; an input or output fixed-
58 length record may span block boundaries.
59 6. The data resulting from input or conversion or both shall be aggre‐
61 gated into output blocks of the specified size. After the end of
62 input is reached, any remaining output shall be written as a block
63 without padding if conv= sync is not specified; thus, the final
64 output block may be shorter than the output block size.
65
67 None.
68
70 All of the operands shall be processed before any input is read. The
71 following operands shall be supported:
72 if=file
74 Specify the input pathname; the default is standard input.
75 of=file
77 Specify the output pathname; the default is standard output. If
78 the seek= expr conversion is not also specified, the output file
79 shall be truncated before the copy begins if an explicit of=
80 file operand is specified, unless conv= notrunc is specified. If
81 seek= expr is specified, but conv= notrunc is not, the effect of
82 the copy shall be to preserve the blocks in the output file over
83 which dd seeks, but no other portion of the output file shall be
84 preserved. (If the size of the seek plus the size of the input
85 file is less than the previous size of the output file, the out‐
86 put file shall be shortened by the copy.)
87 ibs=expr
89 Specify the input block size, in bytes, by expr (default is
90 512).
91 obs=expr
93 Specify the output block size, in bytes, by expr (default is
94 512).
95 bs=expr
97 Set both input and output block sizes to expr bytes, superseding
98 ibs= and obs=. If no conversion other than sync, noerror, and
99 notrunc is specified, each input block shall be copied to the
100 output as a single block without aggregating short blocks.
101 cbs=expr
103 Specify the conversion block size for block and unblock in bytes
104 by expr (default is zero). If cbs= is omitted or given a value
105 of zero, using block or unblock produces unspecified results.
106 The application shall ensure that this operand is also specified if the
108 conv= operand is specified with a value of ascii, ebcdic, or ibm. For a
109 conv= operand with an ascii value, the input is handled as described
110 for the unblock value, except that characters are converted to ASCII
111 before any trailing <space>s are deleted. For conv= operands with
112 ebcdic or ibm values, the input is handled as described for the block
113 value except that the characters are converted to EBCDIC or IBM EBCDIC,
114 respectively, after any trailing <space>s are added.
115 skip=n Skip n input blocks (using the specified input block size)
117 before starting to copy. On seekable files, the implementation
118 shall read the blocks or seek past them; on non-seekable files,
119 the blocks shall be read and the data shall be discarded.
120 seek=n Skip n blocks (using the specified output block size) from the
122 beginning of the output file before copying. On non-seekable
123 files, existing blocks shall be read and space from the current
124 end-of-file to the specified offset, if any, filled with null
125 bytes; on seekable files, the implementation shall seek to the
126 specified offset or read the blocks as described for non-seek‐
127 able files.
128 count=n
130 Copy only n input blocks.
131 conv=value[,value ...]
133 Where values are comma-separated symbols from the following
135 list:
136 ascii
138 Convert EBCDIC to ASCII; see ASCII to EBCDIC Conversion .
139 ebcdic
141 Convert ASCII to EBCDIC; see ASCII to EBCDIC Conversion .
142 ibm
144 Convert ASCII to a different EBCDIC set; see ASCII to IBM EBCDIC
145 Conversion .
146 The ascii, ebcdic, and ibm values are mutually-exclusive.
149 block
151 Treat the input as a sequence of <newline>-terminated or end-of-
152 file-terminated variable-length records independent of the input
153 block boundaries. Each record shall be converted to a record
154 with a fixed length specified by the conversion block size. Any
155 <newline> shall be removed from the input line; <space>s shall
156 be appended to lines that are shorter than their conversion
157 block size to fill the block. Lines that are longer than the
158 conversion block size shall be truncated to the largest number
159 of characters that fit into that size; the number of truncated
160 lines shall be reported (see the STDERR section).
161 The block and unblock values are mutually-exclusive.
163 unblock
165 Convert fixed-length records to variable length. Read a number
166 of bytes equal to the conversion block size (or the number of
167 bytes remaining in the input, if less than the conversion block
168 size), delete all trailing <space>s, and append a <newline>.
169 lcase
171 Map uppercase characters specified by the LC_CTYPE keyword
172 tolower to the corresponding lowercase character. Characters
173 for which no mapping is specified shall not be modified by this
174 conversion.
175 The lcase and ucase symbols are mutually-exclusive.
177 ucase
179 Map lowercase characters specified by the LC_CTYPE keyword toup‐
180 per to the corresponding uppercase character. Characters for
181 which no mapping is specified shall not be modified by this con‐
182 version.
183 swab
185 Swap every pair of input bytes.
186 noerror
188 Do not stop processing on an input error. When an input error
189 occurs, a diagnostic message shall be written on standard error,
190 followed by the current input and output block counts in the
191 same format as used at completion (see the STDERR section). If
192 the sync conversion is specified, the missing input shall be
193 replaced with null bytes and processed normally; otherwise, the
194 input block shall be omitted from the output.
195 notrunc
197 Do not truncate the output file. Preserve blocks in the output
198 file not explicitly written by this invocation of the dd util‐
199 ity. (See also the preceding of= file operand.)
200 sync
202 Pad every input block to the size of the ibs= buffer, appending
203 null bytes. (If either block or unblock is also specified,
204 append <space>s, rather than null bytes.)
205 The behavior is unspecified if operands other than conv= are specified
209 more than once.
210 For the bs=, cbs=, ibs=, and obs= operands, the application shall sup‐
212 ply an expression specifying a size in bytes. The expression, expr, can
213 be:
214 1. A positive decimal number
216 2. A positive decimal number followed by k, specifying multiplication
218 by 1024
219 3. A positive decimal number followed by b, specifying multiplication
221 by 512
222 4. Two or more positive decimal numbers (with or without k or b) sepa‐
224 rated by x, specifying the product of the indicated values
225 All of the operands are processed before any input is read.
227 The following two tables display the octal number character values used
229 for the ascii and ebcdic conversions (first table) and for the ibm con‐
230 version (second table). In both tables, the ASCII values are the row
231 and column headers and the EBCDIC values are found at their intersec‐
232 tions. For example, ASCII 0012 (LF) is the second row, third column,
233 yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to ASCII con‐
234 version) are not shown, but are in one-to-one correspondence with these
235 tables. The differences between the two tables are highlighted by
236 small boxes drawn around five entries.
237 Table: ASCII to EBCDIC Conversion
239 Table: ASCII to IBM EBCDIC Conversion
242
244 If no if= operand is specified, the standard input shall be used. See
245 the INPUT FILES section.
246
248 The input file can be any file type.
249
251 The following environment variables shall affect the execution of dd:
252 LANG Provide a default value for the internationalization variables
254 that are unset or null. (See the Base Definitions volume of
255 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
256 ables for the precedence of internationalization variables used
257 to determine the values of locale categories.)
258 LC_ALL If set to a non-empty string value, override the values of all
260 the other internationalization variables.
261 LC_CTYPE
263 Determine the locale for the interpretation of sequences of
264 bytes of text data as characters (for example, single-byte as
265 opposed to multi-byte characters in arguments and input files),
266 the classification of characters as uppercase or lowercase, and
267 the mapping of characters from one case to the other.
268 LC_MESSAGES
270 Determine the locale that should be used to affect the format
271 and contents of diagnostic messages written to standard error
272 and informative messages written to standard output.
273 NLSPATH
275 Determine the location of message catalogs for the processing of
276 LC_MESSAGES .
277
280 For SIGINT, the dd utility shall interrupt its current processing,
281 write status information to standard error, and exit as though termi‐
282 nated by SIGINT. It shall take the standard action for all other sig‐
283 nals; see the ASYNCHRONOUS EVENTS section in Utility Description
284 Defaults .
285
287 If no of= operand is specified, the standard output shall be used. The
288 nature of the output depends on the operands selected.
289
291 On completion, dd shall write the number of input and output blocks to
292 standard error. In the POSIX locale the following formats shall be
293 used:
294 "%u+%u records in\n", <number of whole input blocks>,
297 <number of partial input blocks>
298 "%u+%u records out\n", <number of whole output blocks>,
301 <number of partial output blocks>
302 A partial input block is one for which read() returned less than the
304 input block size. A partial output block is one that was written with
305 fewer bytes than specified by the output block size.
306 In addition, when there is at least one truncated block, the number of
308 truncated blocks shall be written to standard error. In the POSIX
309 locale, the format shall be:
310 "%u truncated %s\n", <number of truncated blocks>, "record" (if
313 <number of truncated blocks> is one) "records" (otherwise)
314 Diagnostic messages may also be written to standard error.
316
318 If the of= operand is used, the output shall be the same as described
319 in the STDOUT section.
320
322 None.
323
325 The following exit values shall be returned:
326 0 The input file was copied successfully.
328 >0 An error occurred.
330
333 If an input error is detected and the noerror conversion has not been
334 specified, any partial output block shall be written to the output
335 file, a diagnostic message shall be written, and the copy operation
336 shall be discontinued. If some other error is detected, a diagnostic
337 message shall be written and the copy operation shall be discontinued.
338 The following sections are informative.
340
342 The input and output block size can be specified to take advantage of
343 raw physical I/O.
344 There are many different versions of the EBCDIC codesets. The ASCII and
346 EBCDIC conversions specified for the dd utility perform conversions for
347 the version specified by the tables.
348
350 The following command:
351 dd if=/dev/rmt0h of=/dev/rmt1h
354 copies from tape drive 0 to tape drive 1, using a common historical
356 device naming convention.
357 The following command:
359 dd ibs=10 skip=1
362 strips the first 10 bytes from standard input.
364 This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card
366 images per block into the ASCII file x:
367 dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
370
372 The OPTIONS section is listed as "None" because there are no options
373 recognized by historical dd utilities. Certainly, many of the operands
374 could have been designed to use the Utility Syntax Guidelines, which
375 would have resulted in the classic hyphenated option letters. In this
376 version of this volume of IEEE Std 1003.1-2001, dd retains its curious
377 JCL-like syntax due to the large number of applications that depend on
378 the historical implementation.
379 A suggested implementation technique for conv= noerror, sync is to zero
381 (or <space>-fill, if blocking or unblocking) the input buffer before
382 each read and to write the contents of the input buffer to the output
383 even after an error. In this manner, any data transferred to the input
384 buffer before the error was detected is preserved. Another point is
385 that a failed read on a regular file or a disk generally does not
386 increment the file offset, and dd must then seek past the block on
387 which the error occurred; otherwise, the input error occurs repeti‐
388 tively. When the input is a magnetic tape, however, the tape normally
389 has passed the block containing the error when the error is reported,
390 and thus no seek is necessary.
391 The default ibs= and obs= sizes are specified as 512 bytes because
393 there are historical (largely portable) scripts that assume these val‐
394 ues. If they were left unspecified, unusual results could occur if an
395 implementation chose an odd block size.
396 Historical implementations of dd used creat() when processing of= file.
398 This makes the seek= operand unusable except on special files. The
399 conv= notrunc feature was added because more recent BSD-based implemen‐
400 tations use open() (without O_TRUNC) instead of creat(), but they fail
401 to delete output file contents after the data copied.
402 The w multiplier (historically meaning word), is used in System V to
404 mean 2 and in 4.2 BSD to mean 4. Since word is inherently non-portable,
405 its use is not supported by this volume of IEEE Std 1003.1-2001.
406 Standard EBCDIC does not have the characters '[' and ']' . The values
408 used in the table are taken from a common print train that does contain
409 them. Other than those characters, the print train values are not
410 filled in, but appear to provide some of the motivation for the histor‐
411 ical choice of translations reflected here.
412 The Standard EBCDIC table provides a 1:1 translation for all 256 bytes.
414 The IBM EBCDIC table does not provide such a translation. The marked
416 cells in the tables differ in such a way that:
417 1. EBCDIC 0112 ( 'cent' ) and 0152 (broken pipe) do not appear in the
419 table.
420 2. EBCDIC 0137 ( 'not' ) translates to/from ASCII 0236 ( '^' ). In the
422 standard table, EBCDIC 0232 (no graphic) is used.
423 3. EBCDIC 0241 ( '~' ) translates to/from ASCII 0176 ( '~' ). In the
425 standard table, EBCDIC 0137 ( 'not' ) is used.
426 4. 0255 ( '[' ) and 0275 ( ']' ) appear twice, once in the same place
428 as for the standard table and once in place of 0112 ( 'cent' ) and
429 0241 ( '~' ).
430 In net result: EBCDIC 0275 ( ']' ) displaced EBCDIC 0241 ( '~' ) in
432 cell 0345.
433 That displaced EBCDIC 0137 ( 'not' ) in cell 0176.
435 That displaced EBCDIC 0232 (no graphic) in cell 0136.
437 That replaced EBCDIC 0152 (broken pipe) in cell 0313.
439 EBCDIC 0255 ( '[' ) replaced EBCDIC 0112 ( 'cent' ).
441 This translation, however, reflects historical practice that (ASCII)
443 '~' and 'not' were often mapped to each other, as were '[' and 'cent' ;
444 and ']' and (EBCDIC) '~' .
445 The cbs operand is required if any of the ascii, ebcdic, or ibm oper‐
447 ands are specified. For the ascii operand, the input is handled as
448 described for the unblock operand except that characters are converted
449 to ASCII before the trailing <space>s are deleted. For the ebcdic and
450 ibm operands, the input is handled as described for the block operand
451 except that the characters are converted to EBCDIC or IBM EBCDIC after
452 the trailing <space>s are added.
453 The block and unblock keywords are from historical BSD practice.
455 The consistent use of the word record in standard error messages
457 matches most historical practice. An earlier version of System V used
458 block, but this has been updated in more recent releases.
459 Early proposals only allowed two numbers separated by x to be used in a
461 product when specifying bs=, cbs=, ibs=, and obs= sizes. This was
462 changed to reflect the historical practice of allowing multiple numbers
463 in the product as provided by Version 7 and all releases of System V
464 and BSD.
465 A change to the swab conversion is required to match historical prac‐
467 tice and is the result of IEEE PASC Interpretations 1003.2 #03 and #04,
468 submitted for the ISO POSIX-2:1993 standard.
469 A change to the handling of SIGINT is required to match historical
471 practice and is the result of IEEE PASC Interpretation 1003.2 #06 sub‐
472 mitted for the ISO POSIX-2:1993 standard.
473
475 None.
476
478 Utility Description Defaults, sed, tr
479
481 Portions of this text are reprinted and reproduced in electronic form
482 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
483 -- Portable Operating System Interface (POSIX), The Open Group Base
484 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
485 Electrical and Electronics Engineers, Inc and The Open Group. In the
486 event of any discrepancy between this version and the original IEEE and
487 The Open Group Standard, the original IEEE and The Open Group Standard
488 is the referee document. The original Standard can be obtained online
489 at http://www.opengroup.org/unix/online.html .
490IEEE/The Open Group 2003 DD(1P)