dd man page on Fedora

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

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

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

NAME
       dd - convert and copy a file

SYNOPSIS
       dd [operand ...]

DESCRIPTION
       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>s 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‐
	   ted.

	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
	   output block may be shorter than the output block size.

OPTIONS
       None.

OPERANDS
       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 specified. 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 out‐
	      put file shall 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 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 results.

       The application shall ensure that this operand is also 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>s	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>s are added.

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

       seek=n Skip  n  blocks (using the specified output block size) from the
	      beginning of the output file  before  copying.  On  non-seekable
	      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-seek‐
	      able 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>-terminated 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>s 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 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>s, and append a <newline>.

       lcase
	      Map  uppercase  characters  specified  by	 the  LC_CTYPE keyword
	      tolower to the corresponding  lowercase  character.   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 toup‐
	      per  to  the  corresponding uppercase character.	Characters for
	      which no mapping is specified shall not be modified by this con‐
	      version.

       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 normally; 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 invocation of the  dd	 util‐
	      ity. (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>s, 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
       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) 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: ASCII to EBCDIC Conversion

			Table: ASCII to IBM EBCDIC Conversion

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

INPUT FILES
       The input file can be any file type.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of dd:

       LANG   Provide a default value for the  internationalization  variables
	      that  are	 unset	or  null.  (See the Base Definitions volume of
	      IEEE Std 1003.1-2001, 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 lowercase,  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 catalogs for the processing of
	      LC_MESSAGES .

ASYNCHRONOUS EVENTS
       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  Utility Description
       Defaults .

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

STDERR
       On  completion, dd shall write the number of input and output blocks to
       standard error. In the POSIX locale  the	 following  formats  shall  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 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.

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

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be 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	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.

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

RATIONALE
       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 IEEE Std 1003.1-2001, dd retains its curious
       JCL-like syntax due to the large number of applications that depend  on
       the historical 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 IEEE Std 1003.1-2001.

       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 ( 'cent' ) and 0152 (broken pipe) do not appear in the
	   table.

	2. EBCDIC 0137 ( 'not' ) 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 ( 'not' ) is used.

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

       In net result: EBCDIC 0275 ( ']' ) displaced EBCDIC 0241	 (  '~'	 )  in
       cell 0345.

	   That displaced EBCDIC 0137 ( 'not' ) 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 ( 'cent' ).

       This  translation,  however,  reflects historical practice that (ASCII)
       '~' and 'not' were often mapped to each other, as were '[' and 'cent' ;
       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>s 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>s 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       Utility Description Defaults, sed, tr

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003	by  the	 Institute  of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. 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.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003				DD(1P)
[top]

List of man pages available for Fedora

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]
Tweet
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