Annotation of src/usr.bin/tr/tr.1, Revision 1.1.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