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. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)tr.1 8.1 (Berkeley) 6/6/93 32.\" 33.Dd October 13, 2006 34.Dt TR 1 35.Os 36.Sh NAME 37.Nm tr 38.Nd translate characters 39.Sh SYNOPSIS 40.Nm 41.Op Fl Ccsu 42.Ar string1 string2 43.Nm 44.Op Fl Ccu 45.Fl d 46.Ar string1 47.Nm 48.Op Fl Ccu 49.Fl s 50.Ar string1 51.Nm 52.Op Fl Ccu 53.Fl ds 54.Ar string1 string2 55.Sh DESCRIPTION 56The 57.Nm 58utility copies the standard input to the standard output with substitution 59or deletion of selected characters. 60.Pp 61The following options are available: 62.Bl -tag -width Ds 63.It Fl C 64Complement the set of characters in 65.Ar string1 , 66that is 67.Dq Fl C Li ab 68includes every character except for 69.Ql a 70and 71.Ql b . 72.It Fl c 73Same as 74.Fl C 75but complement the set of values in 76.Ar string1 . 77.It Fl d 78Delete characters in 79.Ar string1 80from the input. 81.It Fl s 82Squeeze multiple occurrences of the characters listed in the last 83operand (either 84.Ar string1 85or 86.Ar string2 ) 87in the input into a single instance of the character. 88This occurs after all deletion and translation is completed. 89.It Fl u 90Guarantee that any output is unbuffered. 91.El 92.Pp 93In the first synopsis form, the characters in 94.Ar string1 95are translated into the characters in 96.Ar string2 97where the first character in 98.Ar string1 99is translated into the first character in 100.Ar string2 101and so on. 102If 103.Ar string1 104is longer than 105.Ar string2 , 106the last character found in 107.Ar string2 108is duplicated until 109.Ar string1 110is exhausted. 111.Pp 112In the second synopsis form, the characters in 113.Ar string1 114are deleted from the input. 115.Pp 116In the third synopsis form, the characters in 117.Ar string1 118are compressed as described for the 119.Fl s 120option. 121.Pp 122In the fourth synopsis form, the characters in 123.Ar string1 124are deleted from the input, and the characters in 125.Ar string2 126are compressed as described for the 127.Fl s 128option. 129.Pp 130The following conventions can be used in 131.Ar string1 132and 133.Ar string2 134to specify sets of characters: 135.Bl -tag -width [:equiv:] 136.It character 137Any character not described by one of the following conventions 138represents itself. 139.It \eoctal 140A backslash followed by 1, 2 or 3 octal digits represents a character 141with that encoded value. 142To follow an octal sequence with a digit as a character, left zero-pad 143the octal sequence to the full 3 octal digits. 144.It \echaracter 145A backslash followed by certain special characters maps to special 146values. 147.Bl -column "\ea" 148.It "\ea <alert character>" 149.It "\eb <backspace>" 150.It "\ef <form-feed>" 151.It "\en <newline>" 152.It "\er <carriage return>" 153.It "\et <tab>" 154.It "\ev <vertical tab>" 155.El 156.Pp 157A backslash followed by any other character maps to that character. 158.It c-c 159For non-octal range endpoints 160represents the range of characters between the range endpoints, inclusive, 161in ascending order, 162as defined by the collation sequence. 163If either or both of the range endpoints are octal sequences, it 164represents the range of specific coded values between the 165range endpoints, inclusive. 166.Pp 167.Bf Em 168See the 169.Sx COMPATIBILITY 170section below for an important note regarding 171differences in the way the current 172implementation interprets range expressions differently from 173previous implementations. 174.Ef 175.It [:class:] 176Represents all characters belonging to the defined character class. 177Class names are: 178.Bl -column "phonogram" 179.It "alnum <alphanumeric characters>" 180.It "alpha <alphabetic characters>" 181.It "blank <whitespace characters>" 182.It "cntrl <control characters>" 183.It "digit <numeric characters>" 184.It "graph <graphic characters>" 185.It "ideogram <ideographic characters>" 186.It "lower <lower-case alphabetic characters>" 187.It "phonogram <phonographic characters>" 188.It "print <printable characters>" 189.It "punct <punctuation characters>" 190.It "rune <valid characters>" 191.It "space <space characters>" 192.It "special <special characters>" 193.It "upper <upper-case characters>" 194.It "xdigit <hexadecimal characters>" 195.El 196.Pp 197.\" All classes may be used in 198.\" .Ar string1 , 199.\" and in 200.\" .Ar string2 201.\" when both the 202.\" .Fl d 203.\" and 204.\" .Fl s 205.\" options are specified. 206.\" Otherwise, only the classes ``upper'' and ``lower'' may be used in 207.\" .Ar string2 208.\" and then only when the corresponding class (``upper'' for ``lower'' 209.\" and vice-versa) is specified in the same relative position in 210.\" .Ar string1 . 211.\" .Pp 212When 213.Dq Li [:lower:] 214appears in 215.Ar string1 216and 217.Dq Li [:upper:] 218appears in the same relative position in 219.Ar string2 , 220it represents the characters pairs from the 221.Dv toupper 222mapping in the 223.Ev LC_CTYPE 224category of the current locale. 225When 226.Dq Li [:upper:] 227appears in 228.Ar string1 229and 230.Dq Li [:lower:] 231appears in the same relative position in 232.Ar string2 , 233it represents the characters pairs from the 234.Dv tolower 235mapping in the 236.Ev LC_CTYPE 237category of the current locale. 238.Pp 239With the exception of case conversion, 240characters in the classes are in unspecified order. 241.Pp 242For specific information as to which 243.Tn ASCII 244characters are included 245in these classes, see 246.Xr ctype 3 247and related manual pages. 248.It [=equiv=] 249Represents all characters belonging to the same equivalence class as 250.Ar equiv , 251ordered by their encoded values. 252.It [#*n] 253Represents 254.Ar n 255repeated occurrences of the character represented by 256.Ar # . 257This 258expression is only valid when it occurs in 259.Ar string2 . 260If 261.Ar n 262is omitted or is zero, it is be interpreted as large enough to extend 263.Ar string2 264sequence to the length of 265.Ar string1 . 266If 267.Ar n 268has a leading zero, it is interpreted as an octal value, otherwise, 269it is interpreted as a decimal value. 270.El 271.Sh ENVIRONMENT 272The 273.Ev LANG , LC_ALL , LC_CTYPE 274and 275.Ev LC_COLLATE 276environment variables affect the execution of 277.Nm 278as described in 279.Xr environ 7 . 280.Sh EXIT STATUS 281.Ex -std 282.Sh EXAMPLES 283The following examples are shown as given to the shell: 284.Pp 285Create a list of the words in file1, one per line, where a word is taken to 286be a maximal string of letters. 287.Pp 288.D1 Li "tr -cs \*q[:alpha:]\*q \*q\en\*q < file1" 289.Pp 290Translate the contents of file1 to upper-case. 291.Pp 292.D1 Li "tr \*q[:lower:]\*q \*q[:upper:]\*q < file1" 293.Pp 294(This should be preferred over the traditional 295.Ux 296idiom of 297.Dq Li "tr a-z A-Z" , 298since it works correctly in all locales.) 299.Pp 300Strip out non-printable characters from file1. 301.Pp 302.D1 Li "tr -cd \*q[:print:]\*q < file1" 303.Pp 304Remove diacritical marks from all accented variants of the letter 305.Ql e : 306.Pp 307.Dl "tr \*q[=e=]\*q \*qe\*q" 308.Sh COMPATIBILITY 309Previous 310.Fx 311implementations of 312.Nm 313did not order characters in range expressions according to the current 314locale's collation order, making it possible to convert unaccented Latin 315characters (esp.\& as found in English text) from upper to lower case using 316the traditional 317.Ux 318idiom of 319.Dq Li "tr A-Z a-z" . 320Since 321.Nm 322now obeys the locale's collation order, this idiom may not produce 323correct results when there is not a 1:1 mapping between lower and 324upper case, or when the order of characters within the two cases differs. 325As noted in the 326.Sx EXAMPLES 327section above, the character class expressions 328.Dq Li [:lower:] 329and 330.Dq Li [:upper:] 331should be used instead of explicit character ranges like 332.Dq Li a-z 333and 334.Dq Li A-Z . 335.Pp 336.Dq Li [=equiv=] 337expression and collation for ranges 338are implemented for single byte locales only. 339.Pp 340System V has historically implemented character ranges using the syntax 341.Dq Li [c-c] 342instead of the 343.Dq Li c-c 344used by historic 345.Bx 346implementations and 347standardized by POSIX. 348System V shell scripts should work under this implementation as long as 349the range is intended to map in another range, i.e., the command 350.Dq Li "tr [a-z] [A-Z]" 351will work as it will map the 352.Ql \&[ 353character in 354.Ar string1 355to the 356.Ql \&[ 357character in 358.Ar string2 . 359However, if the shell script is deleting or squeezing characters as in 360the command 361.Dq Li "tr -d [a-z]" , 362the characters 363.Ql \&[ 364and 365.Ql \&] 366will be 367included in the deletion or compression list which would not have happened 368under a historic System V implementation. 369Additionally, any scripts that depended on the sequence 370.Dq Li a-z 371to 372represent the three characters 373.Ql a , 374.Ql \- 375and 376.Ql z 377will have to be 378rewritten as 379.Dq Li a\e-z . 380.Pp 381The 382.Nm 383utility has historically not permitted the manipulation of NUL bytes in 384its input and, additionally, stripped NUL's from its input stream. 385This implementation has removed this behavior as a bug. 386.Pp 387The 388.Nm 389utility has historically been extremely forgiving of syntax errors, 390for example, the 391.Fl c 392and 393.Fl s 394options were ignored unless two strings were specified. 395This implementation will not permit illegal syntax. 396.Sh STANDARDS 397The 398.Nm 399utility conforms to 400.St -p1003.1-2001 . 401The 402.Dq ideogram , 403.Dq phonogram , 404.Dq rune , 405and 406.Dq special 407character classes are extensions. 408.Pp 409It should be noted that the feature wherein the last character of 410.Ar string2 411is duplicated if 412.Ar string2 413has less characters than 414.Ar string1 415is permitted by POSIX but is not required. 416Shell scripts attempting to be portable to other POSIX systems should use 417the 418.Dq Li [#*] 419convention instead of relying on this behavior. 420The 421.Fl u 422option is an extension to the 423.St -p1003.1-2001 424standard. 425