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
13 dd — convert and copy a file
14
16 dd [operand...]
17
19 The dd utility shall copy the specified input file to the specified
20 output file with possible conversions using specific input and output
21 block sizes. It shall read the input one block at a time, using the
22 specified input block size; it shall then process the block of data
23 actually returned, which could be smaller than the requested block
24 size. It shall apply any conversions that have been specified and write
25 the resulting data to the output in blocks of the specified output
26 block size. If the bs=expr operand is specified and no conversions
27 other than sync, noerror, or notrunc are requested, the data returned
28 from each input block shall be written as a separate output block; if
29 the read returns less than a full block and the sync conversion is not
30 specified, the resulting output block shall be the same size as the
31 input block. If the bs=expr operand is not specified, or a conversion
32 other than sync, noerror, or notrunc is requested, the input shall be
33 processed and collected into full-sized output blocks until the end of
34 the input is reached.
35 The processing order shall be as follows:
37 1. An input block is read.
39 2. If the input block is shorter than the specified input block size
41 and the sync conversion is specified, null bytes shall be appended
42 to the input data up to the specified size. (If either block or
43 unblock is also specified, <space> characters shall be appended
44 instead of null bytes.) The remaining conversions and output shall
45 include the pad characters as if they had been read from the input.
46 3. If the bs=expr operand is specified and no conversion other than
48 sync or noerror is requested, the resulting data shall be written
49 to the output as a single block, and the remaining steps are omit‐
50 ted.
51 4. If the swab conversion is specified, each pair of input data bytes
53 shall be swapped. If there is an odd number of bytes in the input
54 block, the last byte in the input record shall not be swapped.
55 5. Any remaining conversions (block, unblock, lcase, and ucase) shall
57 be performed. These conversions shall operate on the input data
58 independently of the input blocking; an input or output fixed-
59 length record may span block boundaries.
60 6. The data resulting from input or conversion or both shall be aggre‐
62 gated into output blocks of the specified size. After the end of
63 input is reached, any remaining output shall be written as a block
64 without padding if conv=sync is not specified; thus, the final out‐
65 put block may be shorter than the output block size.
66
68 None.
69
71 All of the operands shall be processed before any input is read. The
72 following operands shall be supported:
73 if=file Specify the input pathname; the default is standard input.
75 of=file Specify the output pathname; the default is standard output.
77 If the seek=expr conversion is not also specified, the output
78 file shall be truncated before the copy begins if an explicit
79 of=file operand is specified, unless conv=notrunc is speci‐
80 fied. If seek=expr is specified, but conv=notrunc is not, the
81 effect of the copy shall be to preserve the blocks in the
82 output file over which dd seeks, but no other portion of the
83 output file shall be preserved. (If the size of the seek plus
84 the size of the input file is less than the previous size of
85 the output file, the output file shall be shortened by the
86 copy. If the input file is empty and either the size of the
87 seek is greater than the previous size of the output file or
88 the output file did not previously exist, the size of the
89 output file shall be set to the file offset after the seek.)
90 ibs=expr Specify the input block size, in bytes, by expr (default is
92 512).
93 obs=expr Specify the output block size, in bytes, by expr (default is
95 512).
96 bs=expr Set both input and output block sizes to expr bytes, super‐
98 seding ibs= and obs=. If no conversion other than sync,
99 noerror, and notrunc is specified, each input block shall be
100 copied to the output as a single block without aggregating
101 short blocks.
102 cbs=expr Specify the conversion block size for block and unblock in
104 bytes by expr (default is zero). If cbs= is omitted or given
105 a value of zero, using block or unblock produces unspecified
106 results.
107 The application shall ensure that this operand is also speci‐
109 fied if the conv= operand is specified with a value of ascii,
110 ebcdic, or ibm. For a conv= operand with an ascii value, the
111 input is handled as described for the unblock value, except
112 that characters are converted to ASCII before any trailing
113 <space> characters are deleted. For conv= operands with
114 ebcdic or ibm values, the input is handled as described for
115 the block value except that the characters are converted to
116 EBCDIC or IBM EBCDIC, respectively, after any trailing
117 <space> characters are added.
118 skip=n Skip n input blocks (using the specified input block size)
120 before starting to copy. On seekable files, the implementa‐
121 tion shall read the blocks or seek past them; on non-seekable
122 files, the blocks shall be read and the data shall be dis‐
123 carded.
124 seek=n Skip n blocks (using the specified output block size) from
126 the beginning of the output file before copying. On non-seek‐
127 able files, existing blocks shall be read and space from the
128 current end-of-file to the specified offset, if any, filled
129 with null bytes; on seekable files, the implementation shall
130 seek to the specified offset or read the blocks as described
131 for non-seekable files.
132 count=n Copy only n input blocks.
134 conv=value[,value ...]
136 Where values are <comma>-separated symbols from the following
137 list:
138 ascii Convert EBCDIC to ASCII; see Table 4-7, ASCII to
140 EBCDIC Conversion.
141 ebcdic Convert ASCII to EBCDIC; see Table 4-7, ASCII to
143 EBCDIC Conversion.
144 ibm Convert ASCII to a different EBCDIC set; see Table
146 4-8, ASCII to IBM EBCDIC Conversion.
147 The ascii, ebcdic, and ibm values are mutually-exclusive.
149 block Treat the input as a sequence of <newline>-termi‐
151 nated or end-of-file-terminated variable-length
152 records independent of the input block boundaries.
153 Each record shall be converted to a record with a
154 fixed length specified by the conversion block size.
155 Any <newline> shall be removed from the input line;
156 <space> characters shall be appended to lines that
157 are shorter than their conversion block size to fill
158 the block. Lines that are longer than the conversion
159 block size shall be truncated to the largest number
160 of characters that fit into that size; the number of
161 truncated lines shall be reported (see the STDERR
162 section).
163 The block and unblock values are mutually-exclusive.
165 unblock Convert fixed-length records to variable length.
167 Read a number of bytes equal to the conversion block
168 size (or the number of bytes remaining in the input,
169 if less than the conversion block size), delete all
170 trailing <space> characters, and append a <newline>.
171 lcase Map uppercase characters specified by the LC_CTYPE
173 keyword tolower to the corresponding lowercase char‐
174 acter. Characters for which no mapping is specified
175 shall not be modified by this conversion.
176 The lcase and ucase symbols are mutually-exclusive.
178 ucase Map lowercase characters specified by the LC_CTYPE
180 keyword toupper to the corresponding uppercase char‐
181 acter. Characters for which no mapping is specified
182 shall not be modified by this conversion.
183 swab Swap every pair of input bytes.
185 noerror Do not stop processing on an input error. When an
187 input error occurs, a diagnostic message shall be
188 written on standard error, followed by the current
189 input and output block counts in the same format as
190 used at completion (see the STDERR section). If the
191 sync conversion is specified, the missing input
192 shall be replaced with null bytes and processed nor‐
193 mally; otherwise, the input block shall be omitted
194 from the output.
195 notrunc Do not truncate the output file. Preserve blocks in
197 the output file not explicitly written by this invo‐
198 cation of the dd utility. (See also the preceding
199 of=file operand.)
200 sync Pad every input block to the size of the ibs= buf‐
202 fer, appending null bytes. (If either block or
203 unblock is also specified, append <space> charac‐
204 ters, rather than null bytes.)
205 The behavior is unspecified if operands other than conv= are specified
207 more than once.
208 For the bs=, cbs=, ibs=, and obs= operands, the application shall sup‐
210 ply an expression specifying a size in bytes. The expression, expr, can
211 be:
212 1. A positive decimal number
214 2. A positive decimal number followed by k, specifying multiplication
216 by 1024
217 3. A positive decimal number followed by b, specifying multiplication
219 by 512
220 4. Two or more positive decimal numbers (with or without k or b) sepa‐
222 rated by x, specifying the product of the indicated values
223 All of the operands are processed before any input is read.
225 The following two tables display the octal number character values used
227 for the ascii and ebcdic conversions (first table) and for the ibm con‐
228 version (second table). In both tables, the ASCII values are the row
229 and column headers and the EBCDIC values are found at their intersec‐
230 tions. For example, ASCII 0012 (LF) is the second row, third column,
231 yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to ASCII con‐
232 version) are not shown, but are in one-to-one correspondence with these
233 tables. The differences between the two tables are highlighted by small
234 boxes drawn around five entries.
235 Table 4-7: ASCII to EBCDIC Conversion
237 Table 4-8: ASCII to IBM EBCDIC Conversion
239
241 If no if= operand is specified, the standard input shall be used. See
242 the INPUT FILES section.
243
245 The input file can be any file type.
246
248 The following environment variables shall affect the execution of dd:
249 LANG Provide a default value for the internationalization vari‐
251 ables that are unset or null. (See the Base Definitions vol‐
252 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
253 ables for the precedence of internationalization variables
254 used to determine the values of locale categories.)
255 LC_ALL If set to a non-empty string value, override the values of
257 all the other internationalization variables.
258 LC_CTYPE Determine the locale for the interpretation of sequences of
260 bytes of text data as characters (for example, single-byte as
261 opposed to multi-byte characters in arguments and input
262 files), the classification of characters as uppercase or low‐
263 ercase, and the mapping of characters from one case to the
264 other.
265 LC_MESSAGES
267 Determine the locale that should be used to affect the format
268 and contents of diagnostic messages written to standard error
269 and informative messages written to standard output.
270 NLSPATH Determine the location of message catalogs for the processing
272 of LC_MESSAGES.
273
275 For SIGINT, the dd utility shall interrupt its current processing,
276 write status information to standard error, and exit as though termi‐
277 nated by SIGINT. It shall take the standard action for all other sig‐
278 nals; see the ASYNCHRONOUS EVENTS section in Section 1.4, Utility
279 Description Defaults.
280
282 If no of= operand is specified, the standard output shall be used. The
283 nature of the output depends on the operands selected.
284
286 On completion, dd shall write the number of input and output blocks to
287 standard error. In the POSIX locale the following formats shall be
288 used:
289 "%u+%u records in\n", <number of whole input blocks>,
291 <number of partial input blocks>
292 "%u+%u records out\n", <number of whole output blocks>,
294 <number of partial output blocks>
295 A partial input block is one for which read() returned less than the
297 input block size. A partial output block is one that was written with
298 fewer bytes than specified by the output block size.
299 In addition, when there is at least one truncated block, the number of
301 truncated blocks shall be written to standard error. In the POSIX
302 locale, the format shall be:
303 "%u truncated %s\n", <number of truncated blocks>, "record" (if
305 <number of truncated blocks> is one) "records" (otherwise)
306 Diagnostic messages may also be written to standard error.
308
310 If the of= operand is used, the output shall be the same as described
311 in the STDOUT section.
312
314 None.
315
317 The following exit values shall be returned:
318 0 The input file was copied successfully.
320 >0 An error occurred.
322
324 If an input error is detected and the noerror conversion has not been
325 specified, any partial output block shall be written to the output
326 file, a diagnostic message shall be written, and the copy operation
327 shall be discontinued. If some other error is detected, a diagnostic
328 message shall be written and the copy operation shall be discontinued.
329 The following sections are informative.
331
333 The input and output block size can be specified to take advantage of
334 raw physical I/O.
335 There are many different versions of the EBCDIC codesets. The ASCII and
337 EBCDIC conversions specified for the dd utility perform conversions for
338 the version specified by the tables.
339
341 The following command:
342 dd if=/dev/rmt0h of=/dev/rmt1h
344 copies from tape drive 0 to tape drive 1, using a common historical
346 device naming convention.
347 The following command:
349 dd ibs=10 skip=1
351 strips the first 10 bytes from standard input.
353 This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card
355 images per block into the ASCII file x:
356 dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
358
360 The OPTIONS section is listed as ``None'' because there are no options
361 recognized by historical dd utilities. Certainly, many of the operands
362 could have been designed to use the Utility Syntax Guidelines, which
363 would have resulted in the classic hyphenated option letters. In this
364 version of this volume of POSIX.1‐2008, dd retains its curious JCL-like
365 syntax due to the large number of applications that depend on the his‐
366 torical implementation.
367 A suggested implementation technique for conv=noerror,sync is to zero
369 (or <space>-fill, if blocking or unblocking) the input buffer before
370 each read and to write the contents of the input buffer to the output
371 even after an error. In this manner, any data transferred to the input
372 buffer before the error was detected is preserved. Another point is
373 that a failed read on a regular file or a disk generally does not
374 increment the file offset, and dd must then seek past the block on
375 which the error occurred; otherwise, the input error occurs repeti‐
376 tively. When the input is a magnetic tape, however, the tape normally
377 has passed the block containing the error when the error is reported,
378 and thus no seek is necessary.
379 The default ibs= and obs= sizes are specified as 512 bytes because
381 there are historical (largely portable) scripts that assume these val‐
382 ues. If they were left unspecified, unusual results could occur if an
383 implementation chose an odd block size.
384 Historical implementations of dd used creat() when processing of=file.
386 This makes the seek= operand unusable except on special files. The
387 conv=notrunc feature was added because more recent BSD-based implemen‐
388 tations use open() (without O_TRUNC) instead of creat(), but they fail
389 to delete output file contents after the data copied.
390 The w multiplier (historically meaning word), is used in System V to
392 mean 2 and in 4.2 BSD to mean 4. Since word is inherently non-portable,
393 its use is not supported by this volume of POSIX.1‐2008.
394 Standard EBCDIC does not have the characters '[' and ']'. The values
396 used in the table are taken from a common print train that does contain
397 them. Other than those characters, the print train values are not
398 filled in, but appear to provide some of the motivation for the histor‐
399 ical choice of translations reflected here.
400 The Standard EBCDIC table provides a 1:1 translation for all 256 bytes.
402 The IBM EBCDIC table does not provide such a translation. The marked
404 cells in the tables differ in such a way that:
405 1. EBCDIC 0112 ('¢') and 0152 (broken pipe) do not appear in the ta‐
407 ble.
408 2. EBCDIC 0137 ('¬') translates to/from ASCII 0236 ('^'). In the
410 standard table, EBCDIC 0232 (no graphic) is used.
411 3. EBCDIC 0241 ('~') translates to/from ASCII 0176 ('~'). In the
413 standard table, EBCDIC 0137 ('¬') is used.
414 4. 0255 ('[') and 0275 (']') appear twice, once in the same place as
416 for the standard table and once in place of 0112 ('¢') and 0241
417 ('~').
418 In net result:
420 EBCDIC 0275 (']') displaced EBCDIC 0241 ('~') in cell 0345.
422 That displaced EBCDIC 0137 ('¬') in cell 0176.
424 That displaced EBCDIC 0232 (no graphic) in cell 0136.
426 That replaced EBCDIC 0152 (broken pipe) in cell 0313.
428 EBCDIC 0255 ('[') replaced EBCDIC 0112 ('¢').
430 This translation, however, reflects historical practice that (ASCII)
432 '~' and '¬' were often mapped to each other, as were '[' and '¢'; and
433 ']' and (EBCDIC) '~'.
434 The cbs operand is required if any of the ascii, ebcdic, or ibm oper‐
436 ands are specified. For the ascii operand, the input is handled as
437 described for the unblock operand except that characters are converted
438 to ASCII before the trailing <space> characters are deleted. For the
439 ebcdic and ibm operands, the input is handled as described for the
440 block operand except that the characters are converted to EBCDIC or IBM
441 EBCDIC after the trailing <space> characters are added.
442 The block and unblock keywords are from historical BSD practice.
444 The consistent use of the word record in standard error messages
446 matches most historical practice. An earlier version of System V used
447 block, but this has been updated in more recent releases.
448 Early proposals only allowed two numbers separated by x to be used in a
450 product when specifying bs=, cbs=, ibs=, and obs= sizes. This was
451 changed to reflect the historical practice of allowing multiple numbers
452 in the product as provided by Version 7 and all releases of System V
453 and BSD.
454 A change to the swab conversion is required to match historical prac‐
456 tice and is the result of IEEE PASC Interpretations 1003.2 #03 and #04,
457 submitted for the ISO POSIX‐2:1993 standard.
458 A change to the handling of SIGINT is required to match historical
460 practice and is the result of IEEE PASC Interpretation 1003.2 #06 sub‐
461 mitted for the ISO POSIX‐2:1993 standard.
462
464 None.
465
467 Section 1.4, Utility Description Defaults, sed, tr
468 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
470 Variables
471
473 Portions of this text are reprinted and reproduced in electronic form
474 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
475 -- Portable Operating System Interface (POSIX), The Open Group Base
476 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
477 cal and Electronics Engineers, Inc and The Open Group. (This is
478 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
479 event of any discrepancy between this version and the original IEEE and
480 The Open Group Standard, the original IEEE and The Open Group Standard
481 is the referee document. The original Standard can be obtained online
482 at http://www.unix.org/online.html .
483 Any typographical or formatting errors that appear in this page are
485 most likely to have been introduced during the conversion of the source
486 files to man page format. To report such errors, see https://www.ker‐
487 nel.org/doc/man-pages/reporting_bugs.html .
488IEEE/The Open Group 2013 DD(1P)