dd.html

IEEE 1003.1-2003, Single Unix Specification v3

IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
the precedence of internationalization variables used to determine the values of locale categories.)</dd>

<dt><i>LC_ALL</i></dt>

<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>

<dt><i>LC_CTYPE</i></dt>

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

<dt><i>LC_MESSAGES</i></dt>

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

<dt><i>NLSPATH</i></dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
"[Option End]" border="0"></dd>
</dl>
</blockquote>

<h4><a name="tag_04_34_09"></a>ASYNCHRONOUS EVENTS</h4>

<blockquote>
<p>For SIGINT, the <i>dd</i> utility shall interrupt its current processing, write status information to standard error, and exit
as though terminated by SIGINT. It shall take the standard action for all other signals; see the ASYNCHRONOUS EVENTS section in <a
href="xcu_chap01.html#tag_01_11"><i>Utility Description Defaults</i></a> .</p>
</blockquote>

<h4><a name="tag_04_34_10"></a>STDOUT</h4>

<blockquote>
<p>If no <b>of</b>= operand is specified, the standard output shall be used. The nature of the output depends on the operands
selected.</p>
</blockquote>

<h4><a name="tag_04_34_11"></a>STDERR</h4>

<blockquote>
<p>On completion, <i>dd</i> shall write the number of input and output blocks to standard error. In the POSIX locale the following
formats shall be used:</p>

<pre>
<tt>"%u+%u records in\n", &lt;</tt><i>number of whole input blocks</i><tt>&gt;,
    &lt;</tt><i>number of partial input blocks</i><tt>&gt;
<br>
"%u+%u records out\n", &lt;</tt><i>number of whole output blocks</i><tt>&gt;,
    &lt;</tt><i>number of partial output blocks</i><tt>&gt;
</tt>
</pre>

<p>A partial input block is one for which <a href="../functions/read.html"><i>read</i>()</a> 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.</p>

<p>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:</p>

<pre>
<tt>"%u truncated %s\n", &lt;</tt><i>number of truncated blocks</i><tt>&gt;, "record" (if
    &lt;</tt><i>number of truncated blocks</i><tt>&gt; is one) "records" (otherwise)
</tt>
</pre>

<p>Diagnostic messages may also be written to standard error.</p>
</blockquote>

<h4><a name="tag_04_34_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>If the <b>of</b>= operand is used, the output shall be the same as described in the STDOUT section.</p>
</blockquote>

<h4><a name="tag_04_34_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_34_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>The input file was copied successfully.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_34_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>If an input error is detected and the <b>noerror</b> 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.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_34_16"></a>APPLICATION USAGE</h4>

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

<p>There are many different versions of the EBCDIC codesets. The ASCII and EBCDIC conversions specified for the <i>dd</i> utility
perform conversions for the version specified by the tables.</p>
</blockquote>

<h4><a name="tag_04_34_17"></a>EXAMPLES</h4>

<blockquote>
<p>The following command:</p>

<pre>
<tt>dd if=/dev/rmt0h  of=/dev/rmt1h
</tt>
</pre>

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

<p>The following command:</p>

<pre>
<tt>dd ibs=10  skip=1
</tt>
</pre>

<p>strips the first 10 bytes from standard input.</p>

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

<pre>
<tt>dd if=/dev/tape of=x ibs=800 cbs=80 conv=ascii,lcase
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_34_18"></a>RATIONALE</h4>

<blockquote>
<p>The OPTIONS section is listed as &quot;None&quot; because there are no options recognized by historical <i>dd</i> 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&nbsp;Std&nbsp;1003.1-2001, <i>dd</i> retains its curious JCL-like
syntax due to the large number of applications that depend on the historical implementation.</p>

<p>A suggested implementation technique for <b>conv</b>= <b>noerror</b>, <b>sync</b> is to zero (or &lt;space&gt;-fill, if
<b>block</b>ing or <b>unblock</b>ing) 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 <i>dd</i> must then seek
past the block on which the error occurred; otherwise, the input error occurs repetitively. 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.</p>

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

<p>Historical implementations of <i>dd</i> used <a href="../functions/creat.html"><i>creat</i>()</a> when processing <b>of</b>=
<i>file</i>. This makes the <b>seek</b>= operand unusable except on special files. The <b>conv</b>= <b>notrunc</b> feature was
added because more recent BSD-based implementations use <a href="../functions/open.html"><i>open</i>()</a> (without O_TRUNC)
instead of <a href="../functions/creat.html"><i>creat</i>()</a>, but they fail to delete output file contents after the data
copied.</p>

<p>The <i>w</i> multiplier (historically meaning <i>word</i>), is used in System V to mean 2 and in 4.2 BSD to mean 4. Since
<i>word</i> is inherently non-portable, its use is not supported by this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</p>

<p>Standard EBCDIC does not have the characters <tt>'['</tt> and <tt>']'</tt> . 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 historical choice of translations reflected here.</p>

<p>The Standard EBCDIC table provides a 1:1 translation for all 256 bytes.</p>

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

<ol>
<li>
<p>EBCDIC 0112 ( <tt>'&cent;'</tt> ) and 0152 (broken pipe) do not appear in the table.</p>
</li>

<li>
<p>EBCDIC 0137 ( <tt>'&not;'</tt> ) translates to/from ASCII 0236 ( <tt>'^'</tt> ). In the standard table, EBCDIC 0232 (no graphic)
is used.</p>
</li>

<li>
<p>EBCDIC 0241 ( <tt>'&#152;'</tt> ) translates to/from ASCII 0176 ( <tt>'&#152;'</tt> ). In the standard table, EBCDIC 0137 (
<tt>'&not;'</tt> ) is used.</p>
</li>

<li>
<p>0255 ( <tt>'['</tt> ) and 0275 ( <tt>']'</tt> ) appear twice, once in the same place as for the standard table and once in place
of 0112 ( <tt>'&cent;'</tt> ) and 0241 ( <tt>'&#152;'</tt> ).</p>
</li>
</ol>

<p>In net result:</p>

<blockquote>EBCDIC 0275 ( <tt>']'</tt> ) displaced EBCDIC 0241 ( <tt>'&#152;'</tt> ) in cell 0345. 

<p>&nbsp;&nbsp;&nbsp;&nbsp;That displaced EBCDIC 0137 ( <tt>'&not;'</tt> ) in cell 0176.</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;That displaced EBCDIC 0232 (no graphic) in cell 0136.</p>

<p>&nbsp;&nbsp;&nbsp;&nbsp;That replaced EBCDIC 0152 (broken pipe) in cell 0313.</p>

<p>EBCDIC 0255 ( <tt>'['</tt> ) replaced EBCDIC 0112 ( <tt>'&cent;'</tt> ).</p>
</blockquote>

<p>This translation, however, reflects historical practice that (ASCII) <tt>'&#152;'</tt> and <tt>'&not;'</tt> were often mapped to
each other, as were <tt>'['</tt> and <tt>'&cent;'</tt> ; and <tt>']'</tt> and (EBCDIC) <tt>'&#152;'</tt> .</p>

<p>The <b>cbs</b> operand is required if any of the <b>ascii</b>, <b>ebcdic</b>, or <b>ibm</b> operands are specified. For the
<b>ascii</b> operand, the input is handled as described for the <b>unblock</b> operand except that characters are converted to
ASCII before the trailing &lt;space&gt;s are deleted. For the <b>ebcdic</b> and <b>ibm</b> operands, the input is handled as
described for the <b>block</b> operand except that the characters are converted to EBCDIC or IBM EBCDIC after the trailing
&lt;space&gt;s are added.</p>

<p>The <b>block</b> and <b>unblock</b> keywords are from historical BSD practice.</p>

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

<p>Early proposals only allowed two numbers separated by <b>x</b> to be used in a product when specifying <b>bs</b>=, <b>cbs</b>=,
<b>ibs</b>=, and <b>obs</b>= 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.</p>

<p>A change to the <b>swab</b> conversion is required to match historical practice and is the result of IEEE PASC Interpretations
1003.2 #03 and #04, submitted for the ISO&nbsp;POSIX-2:1993 standard.</p>

<p>A change to the handling of SIGINT is required to match historical practice and is the result of IEEE PASC Interpretation 1003.2
#06 submitted for the ISO&nbsp;POSIX-2:1993 standard.</p>
</blockquote>

<h4><a name="tag_04_34_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_34_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="xcu_chap01.html#tag_01_11"><i>Utility Description Defaults</i></a> , <a href="sed.html"><i>sed</i></a> , <a href=
"tr.html"><i>tr</i></a></p>
</blockquote>

<h4><a name="tag_04_34_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_34_22"></a>Issue 5</h4>

<blockquote>
<p>The second paragraph of the <b>cbs</b>= description is reworded and marked EX.</p>

<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

<h4><a name="tag_04_34_23"></a>Issue 6</h4>

<blockquote>
<p>Changes are made to <b>swab</b> conversion and SIGINT handling to align with the IEEE&nbsp;P1003.2b draft standard.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>IEEE PASC Interpretation 1003.2 #209 is applied, clarifying the interaction between <i>dd</i> <b>of</b>= <i>file</i> and
<b>conv</b>= <b>notrunc</b>.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>