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