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