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