dd man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

DD(1P)			   POSIX Programmer's Manual			DD(1P)

       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

       dd — convert and copy a file

       dd [operand...]

       The dd utility shall copy the specified input  file  to	the  specified
       output  file  with possible conversions using specific input and output
       block sizes. It shall read the input one block at  a  time,  using  the
       specified  input	 block	size;  it shall then process the block of data
       actually returned, which could be  smaller  than	 the  requested	 block
       size. It shall 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 shall 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 shall 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 shall be
       processed and collected into full-sized output blocks until the end  of
       the input is reached.

       The processing order shall be 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 shall be  appended
	   to  the  input  data	 up to the specified size. (If either block or
	   unblock is also specified, <space>  characters  shall  be  appended
	   instead  of null bytes.) The remaining conversions and output shall
	   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 shall be written
	   to the output as a single block, and the remaining steps are	 omit‐

	4. If  the swab conversion is specified, each pair of input data bytes
	   shall be swapped. If there is an odd number of bytes in  the	 input
	   block, the last byte in the input record shall not be swapped.

	5. Any	remaining conversions (block, unblock, lcase, and ucase) shall
	   be performed. These conversions shall 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 shall be aggre‐
	   gated  into	output	blocks of the specified size. After the end of
	   input is reached, any remaining output shall be written as a	 block
	   without padding if conv=sync is not specified; thus, the final out‐
	   put block may be shorter than the output block size.


       All of the operands shall be processed before any input is  read.   The
       following operands shall be 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 shall be truncated before the copy begins if an explicit
		 of=file operand is specified, unless conv=notrunc  is	speci‐
		 fied. If seek=expr is specified, but conv=notrunc is not, the
		 effect of the copy shall be to preserve  the  blocks  in  the
		 output	 file over which dd seeks, but no other portion of the
		 output file shall 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 shall be  shortened  by  the
		 copy.	If  the input file is empty and either the size of the
		 seek is greater than the previous size of the output file  or
		 the  output  file  did	 not previously exist, the size of the
		 output file shall be set to the file offset after the seek.)

       ibs=expr	 Specify the input block size, in bytes, by expr  (default  is

       obs=expr	 Specify  the output block size, in bytes, by expr (default is

       bs=expr	 Set both input and output block sizes to expr	bytes,	super‐
		 seding	 ibs=  and  obs=.   If	no conversion other than sync,
		 noerror, and notrunc is specified, each input block shall  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

		 The application shall ensure that this operand is also speci‐
		 fied 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 implementa‐
		 tion shall read the blocks or seek past them; on non-seekable
		 files,	 the  blocks  shall be read and the data shall be dis‐

       seek=n	 Skip n blocks (using the specified output  block  size)  from
		 the beginning of the output file before copying. On non-seek‐
		 able files, existing blocks shall 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	 shall
		 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

		 ascii	  Convert  EBCDIC  to  ASCII;  see Table 4-7, ASCII to
			  EBCDIC Conversion.

		 ebcdic	  Convert ASCII to EBCDIC; see	Table  4-7,  ASCII  to
			  EBCDIC Conversion.

		 ibm	  Convert  ASCII  to a different EBCDIC set; see Table
			  4-8, ASCII to IBM EBCDIC Conversion.

		 The ascii, ebcdic, and ibm values are mutually-exclusive.

		 block	  Treat the input as a	sequence  of  <newline>-termi‐
			  nated	  or   end-of-file-terminated  variable-length
			  records independent of the input  block  boundaries.
			  Each	record	shall  be converted to a record with a
			  fixed length specified by the conversion block size.
			  Any  <newline> shall be removed from the input line;
			  <space> characters shall be appended to  lines  that
			  are shorter than their conversion block size to fill
			  the block. Lines that are longer than the conversion
			  block	 size shall be truncated to the largest number
			  of characters that fit into that size; the number of
			  truncated  lines  shall  be reported (see the STDERR

			  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>.

		 lcase	  Map uppercase characters specified by	 the  LC_CTYPE
			  keyword tolower to the corresponding lowercase char‐
			  acter. Characters for which no mapping is  specified
			  shall not be modified by this conversion.

			  The lcase and ucase symbols are mutually-exclusive.

		 ucase	  Map  lowercase  characters specified by the LC_CTYPE
			  keyword toupper to the corresponding uppercase char‐
			  acter.  Characters for which no mapping is specified
			  shall not be modified by this conversion.

		 swab	  Swap every pair of input bytes.

		 noerror  Do not stop processing on an input  error.  When  an
			  input	 error	occurs,	 a diagnostic message shall 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
			  shall be replaced with null bytes and processed nor‐
			  mally;  otherwise,  the input block shall be omitted
			  from the output.

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

		 sync	  Pad  every  input block to the size of the ibs= buf‐
			  fer, appending  null	bytes.	(If  either  block  or
			  unblock  is  also  specified, append <space> charac‐
			  ters, rather than null bytes.)

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

       For  the bs=, cbs=, ibs=, and obs= operands, the application shall sup‐
       ply an expression specifying a size in bytes. The expression, expr, can

	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) sepa‐
	   rated by x, specifying the product of the indicated values

       All of the operands are 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 con‐
       version (second table). In both tables, the ASCII values	 are  the  row
       and  column  headers and the EBCDIC values are found at their intersec‐
       tions. For example, ASCII 0012 (LF) is the second  row,	third  column,
       yielding	 0045 in EBCDIC. The inverted tables (for EBCDIC to ASCII con‐
       version) 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 4-7: ASCII to EBCDIC Conversion

		      Table 4-8: ASCII to IBM EBCDIC Conversion

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

       The input file can be any file type.

       The following environment variables shall affect the execution of dd:

       LANG	 Provide  a  default  value for the internationalization vari‐
		 ables that are unset or null. (See the Base Definitions  vol‐
		 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
		 ables for the precedence  of  internationalization  variables
		 used to determine the values of locale categories.)

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

       LC_CTYPE	 Determine the locale for the interpretation of	 sequences  of
		 bytes of text data as characters (for example, single-byte as
		 opposed to  multi-byte	 characters  in	 arguments  and	 input
		 files), the classification of characters as uppercase or low‐
		 ercase, and the mapping of characters from one	 case  to  the

		 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 catalogs for the processing

       For SIGINT, the dd utility  shall  interrupt  its  current  processing,
       write  status  information to standard error, and exit as though termi‐
       nated by SIGINT. It shall take the standard action for all  other  sig‐
       nals;  see  the	ASYNCHRONOUS  EVENTS  section  in Section 1.4, Utility
       Description Defaults.

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

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

	   "%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 shall be written  to  standard	error.	In  the	 POSIX
       locale, the format shall be:

	   "%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.

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


       The following exit values shall be returned:

	0    The input file was copied successfully.

       >0    An error occurred.

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

       The following sections are informative.

       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.

       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

       The  OPTIONS section is listed as ``None'' because there are no options
       recognized by historical dd utilities. Certainly, many of the  operands
       could  have  been  designed to use the Utility Syntax Guidelines, which
       would have resulted in the classic hyphenated option letters.  In  this
       version of this volume of POSIX.1‐2008, dd retains its curious JCL-like
       syntax due to the large number of applications that depend on the  his‐
       torical implementation.

       A  suggested  implementation technique for conv=noerror,sync is to zero
       (or <space>-fill, if blocking or unblocking) the	 input	buffer	before
       each  read  and to write the contents of the input buffer to the output
       even after an error. In this manner, any data transferred to the	 input
       buffer  before  the  error  was detected is preserved. Another point is
       that a failed read on a regular file  or	 a  disk  generally  does  not
       increment  the  file  offset,  and  dd must then seek past the block on
       which the error occurred; otherwise, the	 input	error  occurs  repeti‐
       tively.	When  the input is a magnetic tape, however, the tape normally
       has passed the block containing the error when the error	 is  reported,
       and thus no seek is necessary.

       The  default  ibs=  and	obs=  sizes are specified as 512 bytes because
       there are historical (largely portable) scripts that assume these  val‐
       ues.  If	 they were left unspecified, unusual results could occur if an
       implementation chose an odd block size.

       Historical implementations of dd used creat() when processing  of=file.
       This  makes  the	 seek=	operand	 unusable except on special files. The
       conv=notrunc feature was added because more recent BSD-based  implemen‐
       tations	use open() (without O_TRUNC) instead of creat(), but they fail
       to delete output file contents after the data copied.

       The w multiplier (historically meaning word), is used in	 System	 V  to
       mean 2 and in 4.2 BSD to mean 4. Since word is inherently non-portable,
       its use is not supported by this volume of POSIX.1‐2008.

       Standard EBCDIC does not have the characters '[' and ']'.   The	values
       used in the table are taken from a common print train that does contain
       them. Other than those characters,  the	print  train  values  are  not
       filled in, but appear to provide some of the motivation for the histor‐
       ical choice of translations reflected here.

       The Standard EBCDIC table provides a 1:1 translation for all 256 bytes.

       The IBM EBCDIC table does not provide such a  translation.  The	marked
       cells in the tables differ in such a way that:

	1. EBCDIC  0112	 ('¢') and 0152 (broken pipe) do not appear in the ta‐

	2. EBCDIC 0137 ('¬') translates to/from	 ASCII	0236  ('^').   In  the
	   standard table, EBCDIC 0232 (no graphic) is used.

	3. EBCDIC  0241	 ('~')	translates  to/from  ASCII 0176 ('~').	In the
	   standard table, EBCDIC 0137 ('¬') is used.

	4. 0255 ('[') and 0275 (']') appear twice, once in the same  place  as
	   for	the  standard  table  and once in place of 0112 ('¢') and 0241

       In net result:

	      EBCDIC 0275 (']') displaced EBCDIC 0241 ('~') in cell 0345.

		  That displaced EBCDIC 0137 ('¬') in cell 0176.

		  That displaced EBCDIC 0232 (no graphic) in cell 0136.

		  That replaced EBCDIC 0152 (broken pipe) in cell 0313.

	      EBCDIC 0255 ('[') replaced EBCDIC 0112 ('¢').

       This translation, however, reflects historical  practice	 that  (ASCII)
       '~'  and	 '¬' were often mapped to each other, as were '[' and '¢'; and
       ']' and (EBCDIC) '~'.

       The cbs operand is required if any of the ascii, ebcdic, or  ibm	 oper‐
       ands  are  specified.  For  the	ascii operand, the input is handled as
       described for the unblock operand except that characters are  converted
       to  ASCII  before  the trailing <space> characters are deleted. For the
       ebcdic and ibm operands, the input is  handled  as  described  for  the
       block operand except that the characters are converted to EBCDIC or IBM
       EBCDIC after the trailing <space> characters are added.

       The block and unblock keywords are from historical BSD practice.

       The consistent use of  the  word	 record	 in  standard  error  messages
       matches	most  historical practice. An earlier version of System V used
       block, but this has been updated in more recent releases.

       Early proposals only allowed two numbers separated by x to be used in a
       product	when  specifying  bs=,	cbs=,  ibs=,  and obs= sizes. This was
       changed to reflect the historical practice of allowing multiple numbers
       in  the	product	 as provided by Version 7 and all releases of System V
       and BSD.

       A change to the swab conversion is required to match  historical	 prac‐
       tice and is the result of IEEE PASC Interpretations 1003.2 #03 and #04,
       submitted for the ISO POSIX‐2:1993 standard.

       A change to the handling of SIGINT  is  required	 to  match  historical
       practice	 and is the result of IEEE PASC Interpretation 1003.2 #06 sub‐
       mitted for the ISO POSIX‐2:1993 standard.


       Section 1.4, Utility Description Defaults, sed, tr

       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment

       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal  and	 Electronics  Engineers,  Inc  and  The	 Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum	 1  applied.)  In  the
       event of any discrepancy between this version 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.unix.org/online.html .

       Any typographical or formatting errors that appear  in  this  page  are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors,	 see  https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013				DD(1P)

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
Vote for polarhome
Free Shell Accounts :: the biggest list on the net