tr.html

IEEE 1003.1-2003, Single Unix Specification v3

to one, it is only valid when it occurs in <i>string2</i>. If <i>n</i> is omitted or is zero, it shall be interpreted as large
enough to extend the <i>string2</i>-based sequence to the length of the <i>string1</i>-based sequence. If <i>n</i> has a leading
zero, it shall be interpreted as an octal value. Otherwise, it shall be interpreted as a decimal value.</dd>
</dl>

<p>When the <b>-d</b> option is not specified:</p>

<ul>
<li>
<p>Each input character found in the array specified by <i>string1</i> shall be replaced by the character in the same relative
position in the array specified by <i>string2</i>. When the array specified by <i>string2</i> is shorter that the one specified by
<i>string1</i>, the results are unspecified.</p>
</li>

<li>
<p>If the <b>-C</b> option is specified, the complements of the characters specified by <i>string1</i> (the set of all characters
in the current character set, as defined by the current setting of <i>LC_CTYPE ,</i> except for those actually specified in the
<i>string1</i> operand) shall be placed in the array in ascending collation sequence, as defined by the current setting of
<i>LC_COLLATE .</i></p>
</li>

<li>
<p>If the <b>-c</b> option is specified, the complement of the values specified by <i>string1</i> shall be placed in the array in
ascending order by binary value.</p>
</li>

<li>
<p>Because the order in which characters specified by character class expressions or equivalence class expressions is undefined,
such expressions should only be used if the intent is to map several characters into one. An exception is case conversion, as
described previously.</p>
</li>
</ul>

<p>When the <b>-d</b> option is specified:</p>

<ul>
<li>
<p>Input characters found in the array specified by <i>string1</i> shall be deleted.</p>
</li>

<li>
<p>When the <b>-C</b> option is specified with <b>-d</b>, all characters except those specified by <i>string1</i> shall be deleted.
The contents of <i>string2</i> are ignored, unless the <b>-s</b> option is also specified.</p>
</li>

<li>
<p>When the <b>-c</b> option is specified with <b>-d</b>, all values except those specified by <i>string1</i> shall be deleted. The
contents of <i>string2</i> shall be ignored, unless the <b>-s</b> option is also specified.</p>
</li>

<li>
<p>The same string cannot be used for both the <b>-d</b> and the <b>-s</b> option; when both options are specified, both
<i>string1</i> (used for deletion) and <i>string2</i> (used for squeezing) shall be required.</p>
</li>
</ul>

<p>When the <b>-s</b> option is specified, after any deletions or translations have taken place, repeated sequences of the same
character shall be replaced by one occurrence of the same character, if the character is found in the array specified by the last
operand. If the last operand contains a character class, such as the following example:</p>

<pre>
<tt>tr -s '[:space:]'
</tt>
</pre>

<p>the last operand's array shall contain all of the characters in that character class. However, in a case conversion, as
described previously, such as:</p>

<pre>
<tt>tr -s '[:upper:]' '[:lower:]'
</tt>
</pre>

<p>the last operand's array shall contain only those characters defined as the second characters in each of the <b>toupper</b> or
<b>tolower</b> character pairs, as appropriate.</p>

<p>An empty string used for <i>string1</i> or <i>string2</i> produces undefined results.</p>
</blockquote>

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

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

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

<dd>All input was processed successfully.</dd>

<dt>&gt;0</dt>

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

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

<blockquote>
<p>Default.</p>
</blockquote>

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

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

<blockquote>
<p>If necessary, <i>string1</i> and <i>string2</i> can be quoted to avoid pattern matching by the shell.</p>

<p>If an ordinary digit (representing itself) is to follow an octal sequence, the octal sequence must use the full three digits to
avoid ambiguity.</p>

<p>When <i>string2</i> is shorter than <i>string1</i>, a difference results between historical System&nbsp;V and BSD systems. A BSD
system pads <i>string2</i> with the last character found in <i>string2</i>. Thus, it is possible to do the following:</p>

<pre>
<tt>tr 0123456789 d
</tt>
</pre>

<p>which would translate all digits to the letter <tt>'d'</tt> . Since this area is specifically unspecified in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, both the BSD and System&nbsp;V behaviors are allowed, but a conforming application cannot rely on
the BSD behavior. It would have to code the example in the following way:</p>

<pre>
<tt>tr 0123456789 '[d*]'
</tt>
</pre>

<p>It should be noted that, despite similarities in appearance, the string operands used by <i>tr</i> are not regular
expressions.</p>

<p>Unlike some historical implementations, this definition of the <i>tr</i> utility correctly processes NUL characters in its input
stream. NUL characters can be stripped by using:</p>

<pre>
<tt>tr -d '\000'
</tt>
</pre>
</blockquote>

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

<blockquote>
<ol>
<li>
<p>The following example creates a list of all words in <b>file1</b> one per line in <b>file2</b>, where a word is taken to be a
maximal string of letters.</p>

<pre>
<tt>tr -cs "[:alpha:]" "[\n*]" &lt;file1 &gt;file2
</tt>
</pre>
</li>

<li>
<p>The next example translates all lowercase characters in <b>file1</b> to uppercase and writes the results to standard output.</p>

<pre>
<tt>tr "[:lower:]" "[:upper:]" &lt;file1
</tt>
</pre>
</li>

<li>
<p>This example uses an equivalence class to identify accented variants of the base character <tt>'e'</tt> in <b>file1</b>, which
are stripped of diacritical marks and written to <b>file2</b>.</p>

<pre>
<tt>tr "[=e=]" e &lt;file1 &gt;file2
</tt>
</pre>
</li>
</ol>
</blockquote>

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

<blockquote>
<p>In some early proposals, an explicit option <b>-n</b> was added to disable the historical behavior of stripping NUL characters
from the input. It was considered that automatically stripping NUL characters from the input was not correct functionality.
However, the removal of <b>-n</b> in a later proposal does not remove the requirement that <i>tr</i> correctly process NUL
characters in its input stream. NUL characters can be stripped by using <i>tr</i> <b>-d</b> '\000'.</p>

<p>Historical implementations of <i>tr</i> differ widely in syntax and behavior. For example, the BSD version has not needed the
bracket characters for the repetition sequence. The <i>tr</i> utility syntax is based more closely on the System V and XPG3 model
while attempting to accommodate historical BSD implementations. In the case of the short <i>string2</i> padding, the decision was
to unspecify the behavior and preserve System V and XPG3 scripts, which might find difficulty with the BSD method. The assumption
was made that BSD users of <i>tr</i> have to make accommodations to meet the syntax defined here. Since it is possible to use the
repetition sequence to duplicate the desired behavior, whereas there is no simple way to achieve the System V method, this was the
correct, if not desirable, approach.</p>

<p>The use of octal values to specify control characters, while having historical precedents, is not portable. The introduction of
escape sequences for control characters should provide the necessary portability. It is recognized that this may cause some
historical scripts to break.</p>

<p>An early proposal included support for multi-character collating elements. It was pointed out that, while <i>tr</i> does employ
some syntactical elements from REs, the aim of <i>tr</i> is quite different; ranges, for example, do not have a similar meaning
(``any of the chars in the range matches&quot;, <i>versus</i> &quot;translate each character in the range to the output counterpart&quot;). As
a result, the previously included support for multi-character collating elements has been removed. What remains are ranges in
current collation order (to support, for example, accented characters), character classes, and equivalence classes.</p>

<p>In XPG3 the [: <i>class</i>:] and [= <i>equiv</i>=] conventions are shown with double brackets, as in RE syntax. However,
<i>tr</i> does not implement RE principles; it just borrows part of the syntax. Consequently, [: <i>class</i>:] and [=
<i>equiv</i>=] should be regarded as syntactical elements on a par with [ <i>x</i>* <i>n</i>], which is not an RE bracket
expression.</p>

<p>The standard developers will consider changes to <i>tr</i> that allow it to translate characters between different character
encodings, or they will consider providing a new utility to accomplish this.</p>

<p>On historical System V systems, a range expression requires enclosing square-brackets, such as:</p>

<pre>
<tt>tr '[a-z]' '[A-Z]'
</tt>
</pre>

<p>However, BSD-based systems did not require the brackets, and this convention is used here to avoid breaking large numbers of BSD
scripts:</p>

<pre>
<tt>tr a-z A-Z
</tt>
</pre>

<p>The preceding System V script will continue to work because the brackets, treated as regular characters, are translated to
themselves. However, any System V script that relied on <tt>"a-z"</tt> representing the three characters <tt>'a'</tt> ,
<tt>'-'</tt> , and <tt>'z'</tt> have to be rewritten as <tt>"az-"</tt> .</p>

<p>The ISO&nbsp;POSIX-2:1993 standard had a <b>-c</b> option that behaved similarly to the <b>-C</b> option, but did not supply
functionality equivalent to the <b>-c</b> option specified in IEEE&nbsp;Std&nbsp;1003.1-2001. This meant that historical practice
of being able to specify <i>tr</i> <b>-d</b>\200-\377 (which would delete all bytes with the top bit set) would have no effect
because, in the C locale, bytes with the values octal 200 to octal 377 are not characters.</p>

<p>The earlier version also said that octal sequences referred to collating elements and could be placed adjacent to each other to
specify multi-byte characters. However, it was noted that this caused ambiguities because <i>tr</i> would not be able to tell
whether adjacent octal sequences were intending to specify multi-byte characters or multiple single byte characters.
IEEE&nbsp;Std&nbsp;1003.1-2001 specifies that octal sequences always refer to single byte binary values.</p>
</blockquote>

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

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

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

<blockquote>
<p><a href="sed.html"><i>sed</i></a></p>
</blockquote>

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

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

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

<blockquote>
<p>The <b>-C</b> operand is added, and the description of the <b>-c</b> operand is changed 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>
</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>