NAME

dd - convert and copy a file

 SYNOPSIS

dd [operand ...]

 DESCRIPTION

The dd utility will copy the specified input file to the specified output file with possible conversions using specific input and output block sizes. It will read the input one block at a time, using the specified input block size; it then will process the block of data actually returned, which could be smaller than the requested block size. It will apply any conversions that have been specified and write the resulting data to the output in blocks of the specified output block size. If the bs=expr operand is specified and no conversions other than sync, noerror or notrunc are requested, the data returned from each input block will be written as a separate output block; if the read returns less than a full block and the sync conversion is not specified, the resulting output block will be the same size as the input block. If the bs=expr operand is not specified, or a conversion other than sync, noerror or notrunc is requested, the input will be processed and collected into full-sized output blocks until the end of the input is reached.

The processing order is as follows:

1. An input block is read.

2. If the input block is shorter than the specified input block size and the sync conversion is specified, null bytes are appended to the input data up to the specified size. (If either block or unblock is also specified, space characters are appended instead of null bytes.) The remaining conversions and output include the pad characters as if they had been read from the input.

3. If the bs=expr operand is specified and no conversion other than sync or noerror is requested, the resulting data will be written to the output as a single block, and the remaining steps are omitted.

4. If the swab conversion is specified, each pair of input data bytes will be swapped. If there is an odd number of bytes in the input block, the results are unspecified.

5. Any remaining conversions (block, unblock, lcase and ucase) will be performed. These conversions will operate on the input data independently of the input blocking; an input or output fixed-length record may span block boundaries.

6. The data resulting from input or conversion or both will be aggregated into output blocks of the specified size. After the end of input is reached, any remaining output will be written as a block without padding if conv=sync is not specified; thus the final output block may be shorter than the output block size.

 OPTIONS

None.

 OPERANDS

The following operands are supported:

if=file

Specify the input pathname; the default is standard input.

of=file

Specify the output pathname; the default is standard output. If the seek=expr conversion is not also specified, the output file will be truncated before the copy begins, unless conv=notrunc is specified. If seek=expr is specified, but conv=notrunc is not, the effect of the copy will be to preserve the blocks in the output file over which dd seeks, but no other portion of the output file will be preserved. (If the size of the seek plus the size of the input file is less than the previous size of the output file, the output file will be shortened by the copy.)

ibs=expr

Specify the input block size, in bytes, by expr (default is 512).

obs=expr

Specify the output block size, in bytes, by expr (default is 512).

bs=expr

Set both input and output block sizes to expr bytes, superseding ibs= and obs=. If no conversion other than sync, noerror and notrunc is specified, each input block will be copied to the output as a single block without aggregating short blocks.

cbs=expr

Specify the conversion block size for block and unblock in bytes by expr (default is zero). If cbs= is omitted or given a value of zero, using block or unblock produces unspecified results. This operand must also be specified if the conv= operand is specified with a value of ascii, ebcdic or ibm. For a conv= operand with an ascii value, the input is handled as described for the unblock value, except that characters are converted to ASCII before any trailing space characters are deleted. For conv= operands with ebcdic or ibm values, the input is handled as described for the block value except that the characters are converted to EBCDIC or IBM EBCDIC, respectively, after any trailing space characters are added.

skip=n

Skip n input blocks (using the specified input block size) before starting to copy. On seekable files, the implementation will read the blocks or seek past them; on non-seekable files, the blocks will be read and the data will be discarded.

seek=n

Skip n blocks (using the specified output block size) from beginning of output file before copying. On non-seekable files, existing blocks will be read and space from the current end-of-file to the specified offset, if any, filled with null bytes; on seekable files, the implementation will seek to the specified offset or read the blocks as described for non-seekable files.

count=n

Copy only n input blocks.

conv=value[,value ...]

Where values are comma-separated symbols from the following list.

ascii

Convert EBCDIC to ASCII. See ASCII to EBCDIC Conversion .

ebcdic

Convert ASCII to EBCDIC. See ASCII to EBCDIC Conversion .

ibm

Convert ASCII to a different EBCDIC set. See ASCII to IBM EBCDIC Conversion .

The ascii, ebcdic and ibm values are mutually exclusive.

block

Treat the input as a sequence of newline-character-terminated or end-of-file-terminated variable-length records independent of the input block boundaries. Each record is converted to a record with a fixed length specified by the conversion block size. Any newline character is removed from the input line; space characters are appended to lines that are shorter than their conversion block size to fill the block. Lines that are longer than the conversion block size are truncated to the largest number of characters that will fit into that size; the number of truncated lines is reported (see the STDERR section). The block and unblock values are mutually exclusive.

unblock

Convert fixed-length records to variable length. Read a number of bytes equal to the conversion block size (or the number of bytes remaining in the input, if less than the conversion block size), delete all trailing space characters, and append a newline character.

lcase

Map upper-case characters specified by the LC_CTYPE keyword tolower to the corresponding lower-case character. Characters for which no mapping is specified will not be modified by this conversion. The lcase and ucase symbols are mutually exclusive.

ucase

Map lower-case characters specified by the LC_CTYPE keyword toupper to the corresponding upper-case character. Characters for which no mapping is specified will not be modified by this conversion.

swab

Swap every pair of input bytes. If the current input record is an odd number of bytes, the last byte in the input record is ignored.

noerror

Do not stop processing on an input error. When an input error occurs, a diagnostic message will be written on standard error, followed by the current input and output block counts in the same format as used at completion (see the STDERR section). If the sync conversion is specified, the missing input will be replaced with null bytes and processed normally; otherwise, the input block will be omitted from the output.

notrunc

Do not truncate the output file. Preserve blocks in the output file not explicitly written by this invocation of the dd utility. (See also the preceding of=file operand.)

sync

Pad every input block to the size of the ibs= buffer, appending null bytes. (If either block or unblock is also specified, append space characters, rather than null bytes.)

The behaviour is unspecified if operands other than conv= are specified more than once.

For the bs=, cbs=, ibs= and obs= operands, the application must supply an expression specifying a size in bytes. The expression, expr, can be:

1. a positive decimal number

2. a positive decimal number followed by k, specifying multiplication by 1024

3. a positive decimal number followed by b, specifying multiplication by 512

4. two or more positive decimal numbers (with or without k or b) separated by x, specifying the product of the indicated values.

All of the operands will be processed before any input is read.

The following two tables display the octal number character values used for the ascii and ebcdic conversions (first table) and for the ibm conversion (second table). In both tables, the ASCII values are the row and column headers and the EBCDIC values are found at their intersections. For example, ASCII 0012 (LF) is the second row, third column, yielding 0045 in EBCDIC. The inverted tables (for EBCDIC to ASCII conversion) are not shown, but are in one-to-one correspondence with these tables. The differences between the two tables are highlighted by small boxes drawn around five entries.

 Table: ASCII to EBCDIC Conversion

 Table: ASCII to IBM EBCDIC Conversion

 STDIN

If no if= operand is specified, the standard input will be used. See the INPUT FILES section.

 INPUT FILES

The input file can be any file type.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of dd:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalisation variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- or lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error and informative messages written to standard output.

NLSPATH

Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

For SIGINT, the dd utility will write status information to standard error before exiting. It will take the standard action for all other signals; see the ASYNCHRONOUS EVENTS section in Utility Description Defaults .

 STDOUT

If no of= operand is specified, the standard output will be used. The nature of the output depends on the operands selected.

 STDERR

On completion, dd will write the number of input and output blocks to standard error. In the POSIX locale the following formats will be used:

"%u+%u records in\n", <number of whole input blocks>,
<number of partial input blocks>

"%u+%u records out\n", <number of whole output blocks>,
<number of partial output blocks>

A partial input block is one for which read() returned less than the input block size. A partial output block is one that was written with fewer bytes than specified by the output block size.

In addition, when there is at least one truncated block, the number of truncated blocks will be written to standard error. In the POSIX locale, the format is:

"%u truncated %s\n", <number of truncated blocks>, "record" (if <number of truncated blocks> is one) "records" (otherwise)


Diagnostic messages may also be written to standard error.

 OUTPUT FILES

If the of= operand is used, the output will be the same as described in the STDOUT section.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:

0

The input file was copied successfully.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

If an input error is detected and the noerror conversion has not been specified, any partial output block will be written to the output file, a diagnostic message will be written, and the copy operation will be discontinued. If some other error is detected, a diagnostic message will be written and the copy operation will be discontinued.

 APPLICATION USAGE

The input and output block size can be specified to take advantage of raw physical I/O.

There are many different versions of the EBCDIC codesets. The ASCII and EBCDIC conversions specified for the dd utility perform conversions for the version specified by the tables.

 EXAMPLES

The following command:

dd if=/dev/rmt0h  of=/dev/rmt1h

copies from tape drive 0 to tape drive 1, using a common historical device naming convention.

The following command:

dd ibs=10  skip=1

strips the first 10 bytes from standard input.

This example reads an EBCDIC tape blocked ten 80-byte EBCDIC card images per block into the ASCII file x :

dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

sed, tr.