1.\" Copyright (c) 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by the University of 18.\" California, Berkeley and its contributors. 19.\" 4. Neither the name of the University nor the names of its contributors 20.\" may be used to endorse or promote products derived from this software 21.\" without specific prior written permission. 22.\" 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 26.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 33.\" SUCH DAMAGE. 34.\" 35.\" @(#)tr.1 8.1 (Berkeley) 6/6/93 36.\" 37.Dd October 11, 1997 38.Dt TR 1 39.Os 40.Sh NAME 41.Nm tr 42.Nd translate characters 43.Sh SYNOPSIS 44.Nm tr 45.Op Fl csu 46.Ar string1 string2 47.Nm tr 48.Op Fl cu 49.Fl d 50.Ar string1 51.Nm tr 52.Op Fl cu 53.Fl s 54.Ar string1 55.Nm tr 56.Op Fl cu 57.Fl ds 58.Ar string1 string2 59.Sh DESCRIPTION 60The 61.Nm 62utility copies the standard input to the standard output with substitution 63or deletion of selected characters. 64.Pp 65The following options are available: 66.Bl -tag -width Ds 67.It Fl c 68Complements the set of characters in 69.Ar string1 , 70that is ``-c ab'' includes every character except for ``a'' and ``b''. 71.It Fl d 72The 73.Fl d 74option causes characters to be deleted from the input. 75.It Fl s 76The 77.Fl s 78option squeezes multiple occurrences of the characters listed in the last 79operand (either 80.Ar string1 81or 82.Ar string2 ) 83in the input into a single instance of the character. 84This occurs after all deletion and translation is completed. 85.It Fl u 86The 87.Fl u 88option guarantees that any output is unbuffered. 89.El 90.Pp 91In the first synopsis form, the characters in 92.Ar string1 93are translated into the characters in 94.Ar string2 95where the first character in 96.Ar string1 97is translated into the first character in 98.Ar string2 99and so on. 100If 101.Ar string1 102is longer than 103.Ar string2 , 104the last character found in 105.Ar string2 106is duplicated until 107.Ar string1 108is exhausted. 109.Pp 110In the second synopsis form, the characters in 111.Ar string1 112are deleted from the input. 113.Pp 114In the third synopsis form, the characters in 115.Ar string1 116are compressed as described for the 117.Fl s 118option. 119.Pp 120In the fourth synopsis form, the characters in 121.Ar string1 122are deleted from the input, and the characters in 123.Ar string2 124are compressed as described for the 125.Fl s 126option. 127.Pp 128The following conventions can be used in 129.Ar string1 130and 131.Ar string2 132to specify sets of characters: 133.Bl -tag -width [:equiv:] 134.It character 135Any character not described by one of the following conventions 136represents itself. 137.It \eoctal 138A backslash followed by 1, 2 or 3 octal digits represents a character 139with that encoded value. 140To follow an octal sequence with a digit as a character, left zero-pad 141the octal sequence to the full 3 octal digits. 142.It \echaracter 143A backslash followed by certain special characters maps to special 144values. 145.sp 146.Bl -column 147.It \ea <alert character> 148.It \eb <backspace> 149.It \ef <form-feed> 150.It \en <newline> 151.It \er <carriage return> 152.It \et <tab> 153.It \ev <vertical tab> 154.El 155.sp 156A backslash followed by any other character maps to that character. 157.It c-c 158Represents the range of characters between the range endpoints, inclusively. 159.It [:class:] 160Represents all characters belonging to the defined character class. 161Class names are: 162.sp 163.Bl -column 164.It alnum <alphanumeric characters> 165.It alpha <alphabetic characters> 166.It cntrl <control characters> 167.It digit <numeric characters> 168.It graph <graphic characters> 169.It lower <lower-case alphabetic characters> 170.It print <printable characters> 171.It punct <punctuation characters> 172.It space <space characters> 173.It upper <upper-case characters> 174.It xdigit <hexadecimal characters> 175.El 176.Pp 177\." All classes may be used in 178\." .Ar string1 , 179\." and in 180\." .Ar string2 181\." when both the 182\." .Fl d 183\." and 184\." .Fl s 185\." options are specified. 186\." Otherwise, only the classes ``upper'' and ``lower'' may be used in 187\." .Ar string2 188\." and then only when the corresponding class (``upper'' for ``lower'' 189\." and vice-versa) is specified in the same relative position in 190\." .Ar string1 . 191\." .Pp 192With the exception of the ``upper'' and ``lower'' classes, characters 193in the classes are in unspecified order. 194In the ``upper'' and ``lower'' classes, characters are entered in 195ascending order. 196.Pp 197For specific information as to which ASCII characters are included 198in these classes, see 199.Xr ctype 3 200and related manual pages. 201.It [=equiv=] 202Represents all characters or collating (sorting) elements belonging to 203the same equivalence class as 204.Ar equiv . 205If 206there is a secondary ordering within the equivalence class, the characters 207are ordered in ascending sequence. 208Otherwise, they are ordered after their encoded values. 209An example of an equivalence class might be ``c'' and ``ch'' in Spanish; 210English has no equivalence classes. 211.It [#*n] 212Represents 213.Ar n 214repeated occurrences of the character represented by 215.Ar # . 216This 217expression is only valid when it occurs in 218.Ar string2 . 219If 220.Ar n 221is omitted or is zero, it is be interpreted as large enough to extend 222.Ar string2 223sequence to the length of 224.Ar string1 . 225If 226.Ar n 227has a leading zero, it is interpreted as an octal value, otherwise, 228it's interpreted as a decimal value. 229.El 230.Pp 231The 232.Nm 233utility exits 0 on success, and >0 if an error occurs. 234.Sh EXAMPLES 235The following examples are shown as given to the shell: 236.sp 237Create a list of the words in file1, one per line, where a word is taken to 238be a maximal string of letters. 239.sp 240.D1 Li "tr -cs \*q[:alpha:]\*q \*q\en\*q < file1" 241.sp 242Translate the contents of file1 to upper-case. 243.sp 244.D1 Li "tr \*q[:lower:]\*q \*q[:upper:]\*q < file1" 245.sp 246Strip out non-printable characters from file1. 247.sp 248.D1 Li "tr -cd \*q[:print:]\*q < file1" 249.Sh COMPATIBILITY 250System V has historically implemented character ranges using the syntax 251``[c-c]'' instead of the ``c-c'' used by historic BSD implementations and 252standardized by POSIX. 253System V shell scripts should work under this implementation as long as 254the range is intended to map in another range, i.e. the command 255``tr [a-z] [A-Z]'' will work as it will map the ``['' character in 256.Ar string1 257to the ``['' character in 258.Ar string2. 259However, if the shell script is deleting or squeezing characters as in 260the command ``tr -d [a-z]'', the characters ``['' and ``]'' will be 261included in the deletion or compression list which would not have happened 262under an historic System V implementation. 263Additionally, any scripts that depended on the sequence ``a-z'' to 264represent the three characters ``a'', ``-'' and ``z'' will have to be 265rewritten as ``a\e-z''. 266.Pp 267The 268.Nm 269utility has historically not permitted the manipulation of NUL bytes in 270its input and, additionally, stripped NUL's from its input stream. 271This implementation has removed this behavior as a bug. 272.Pp 273The 274.Nm 275utility has historically been extremely forgiving of syntax errors, 276for example, the 277.Fl c 278and 279.Fl s 280options were ignored unless two strings were specified. 281This implementation will not permit illegal syntax. 282.Sh STANDARDS 283The 284.Nm 285utility is expected to be 286.St -p1003.2 287compatible. 288It should be noted that the feature wherein the last character of 289.Ar string2 290is duplicated if 291.Ar string2 292has less characters than 293.Ar string1 294is permitted by POSIX but is not required. 295Shell scripts attempting to be portable to other POSIX systems should use 296the ``[#*]'' convention instead of relying on this behavior. 297The 298.Fl u 299option is an extension to the 300.St -p1003.2 301standard. 302