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
| 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: head/usr.bin/tr/tr.1 79755 2001-07-15 08:06:20Z dd $
| 36.\" $FreeBSD: head/usr.bin/tr/tr.1 81622 2001-08-14 10:01:54Z ru $
|
37.\"
38.Dd October 11, 1997
39.Dt TR 1
40.Os
41.Sh NAME
42.Nm tr
43.Nd translate characters
44.Sh SYNOPSIS
45.Nm
46.Op Fl csu
47.Ar string1 string2
48.Nm
49.Op Fl cu
50.Fl d
51.Ar string1
52.Nm
53.Op Fl cu
54.Fl s
55.Ar string1
56.Nm
57.Op Fl cu
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
69Complements the set of characters in
70.Ar string1 ,
71that is ``-c ab'' includes every character except for ``a'' and ``b''.
72.It Fl d
73The
74.Fl d
75option causes characters to be deleted from the input.
76.It Fl s
77The
78.Fl s
79option squeezes multiple occurrences of the characters listed in the last
80operand (either
81.Ar string1
82or
83.Ar string2 )
84in the input into a single instance of the character.
85This occurs after all deletion and translation is completed.
86.It Fl u
87The
88.Fl u
89option guarantees that any output is unbuffered.
90.El
91.Pp
92In the first synopsis form, the characters in
93.Ar string1
94are translated into the characters in
95.Ar string2
96where the first character in
97.Ar string1
98is translated into the first character in
99.Ar string2
100and so on.
101If
102.Ar string1
103is longer than
104.Ar string2 ,
105the last character found in
106.Ar string2
107is duplicated until
108.Ar string1
109is exhausted.
110.Pp
111In the second synopsis form, the characters in
112.Ar string1
113are deleted from the input.
114.Pp
115In the third synopsis form, the characters in
116.Ar string1
117are compressed as described for the
118.Fl s
119option.
120.Pp
121In the fourth synopsis form, the characters in
122.Ar string1
123are deleted from the input, and the characters in
124.Ar string2
125are compressed as described for the
126.Fl s
127option.
128.Pp
129The following conventions can be used in
130.Ar string1
131and
132.Ar string2
133to specify sets of characters:
134.Bl -tag -width [:equiv:]
135.It character
136Any character not described by one of the following conventions
137represents itself.
138.It \eoctal
139A backslash followed by 1, 2 or 3 octal digits represents a character
140with that encoded value.
141To follow an octal sequence with a digit as a character, left zero-pad
142the octal sequence to the full 3 octal digits.
143.It \echaracter
144A backslash followed by certain special characters maps to special
145values.
146.Pp
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
159Represents the range of characters between the range endpoints, inclusively.
160.It [:class:]
161Represents all characters belonging to the defined character class.
162Class names are:
163.Pp
164.Bl -column "xdigit"
165.It "alnum <alphanumeric characters>
166.It "alpha <alphabetic characters>
167.It "cntrl <control characters>
168.It "digit <numeric characters>
169.It "graph <graphic characters>
170.It "lower <lower-case alphabetic characters>
171.It "print <printable characters>
172.It "punct <punctuation characters>
173.It "space <space characters>
174.It "upper <upper-case characters>
175.It "xdigit <hexadecimal characters>
176.El
177.Pp
178.\" All classes may be used in
179.\" .Ar string1 ,
180.\" and in
181.\" .Ar string2
182.\" when both the
183.\" .Fl d
184.\" and
185.\" .Fl s
186.\" options are specified.
187.\" Otherwise, only the classes ``upper'' and ``lower'' may be used in
188.\" .Ar string2
189.\" and then only when the corresponding class (``upper'' for ``lower''
190.\" and vice-versa) is specified in the same relative position in
191.\" .Ar string1 .
192.\" .Pp
193With the exception of the ``upper'' and ``lower'' classes, characters
194in the classes are in unspecified order.
195In the ``upper'' and ``lower'' classes, characters are entered in
196ascending order.
197.Pp
198For specific information as to which ASCII characters are included
199in these classes, see
200.Xr ctype 3
201and related manual pages.
202.It [=equiv=]
203Represents all characters or collating (sorting) elements belonging to
204the same equivalence class as
205.Ar equiv .
206If
207there is a secondary ordering within the equivalence class, the characters
208are ordered in ascending sequence.
209Otherwise, they are ordered after their encoded values.
210An example of an equivalence class might be ``c'' and ``ch'' in Spanish;
211English has no equivalence classes.
212.It [#*n]
213Represents
214.Ar n
215repeated occurrences of the character represented by
216.Ar # .
217This
218expression is only valid when it occurs in
219.Ar string2 .
220If
221.Ar n
222is omitted or is zero, it is be interpreted as large enough to extend
223.Ar string2
224sequence to the length of
225.Ar string1 .
226If
227.Ar n
228has a leading zero, it is interpreted as an octal value, otherwise,
229it's interpreted as a decimal value.
230.El
231.Sh DIAGNOSTICS
232The
233.Nm
234utility exits 0 on success, and >0 if an error occurs.
235.Sh EXAMPLES
236The following examples are shown as given to the shell:
237.Pp
238Create a list of the words in file1, one per line, where a word is taken to
239be a maximal string of letters.
240.Pp
241.D1 Li "tr -cs \*q[:alpha:]\*q \*q\en\*q < file1"
242.Pp
243Translate the contents of file1 to upper-case.
244.Pp
245.D1 Li "tr \*q[:lower:]\*q \*q[:upper:]\*q < file1"
246.Pp
247Strip out non-printable characters from file1.
248.Pp
249.D1 Li "tr -cd \*q[:print:]\*q < file1"
250.Sh COMPATIBILITY
251System V has historically implemented character ranges using the syntax
| 37.\"
38.Dd October 11, 1997
39.Dt TR 1
40.Os
41.Sh NAME
42.Nm tr
43.Nd translate characters
44.Sh SYNOPSIS
45.Nm
46.Op Fl csu
47.Ar string1 string2
48.Nm
49.Op Fl cu
50.Fl d
51.Ar string1
52.Nm
53.Op Fl cu
54.Fl s
55.Ar string1
56.Nm
57.Op Fl cu
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
69Complements the set of characters in
70.Ar string1 ,
71that is ``-c ab'' includes every character except for ``a'' and ``b''.
72.It Fl d
73The
74.Fl d
75option causes characters to be deleted from the input.
76.It Fl s
77The
78.Fl s
79option squeezes multiple occurrences of the characters listed in the last
80operand (either
81.Ar string1
82or
83.Ar string2 )
84in the input into a single instance of the character.
85This occurs after all deletion and translation is completed.
86.It Fl u
87The
88.Fl u
89option guarantees that any output is unbuffered.
90.El
91.Pp
92In the first synopsis form, the characters in
93.Ar string1
94are translated into the characters in
95.Ar string2
96where the first character in
97.Ar string1
98is translated into the first character in
99.Ar string2
100and so on.
101If
102.Ar string1
103is longer than
104.Ar string2 ,
105the last character found in
106.Ar string2
107is duplicated until
108.Ar string1
109is exhausted.
110.Pp
111In the second synopsis form, the characters in
112.Ar string1
113are deleted from the input.
114.Pp
115In the third synopsis form, the characters in
116.Ar string1
117are compressed as described for the
118.Fl s
119option.
120.Pp
121In the fourth synopsis form, the characters in
122.Ar string1
123are deleted from the input, and the characters in
124.Ar string2
125are compressed as described for the
126.Fl s
127option.
128.Pp
129The following conventions can be used in
130.Ar string1
131and
132.Ar string2
133to specify sets of characters:
134.Bl -tag -width [:equiv:]
135.It character
136Any character not described by one of the following conventions
137represents itself.
138.It \eoctal
139A backslash followed by 1, 2 or 3 octal digits represents a character
140with that encoded value.
141To follow an octal sequence with a digit as a character, left zero-pad
142the octal sequence to the full 3 octal digits.
143.It \echaracter
144A backslash followed by certain special characters maps to special
145values.
146.Pp
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
159Represents the range of characters between the range endpoints, inclusively.
160.It [:class:]
161Represents all characters belonging to the defined character class.
162Class names are:
163.Pp
164.Bl -column "xdigit"
165.It "alnum <alphanumeric characters>
166.It "alpha <alphabetic characters>
167.It "cntrl <control characters>
168.It "digit <numeric characters>
169.It "graph <graphic characters>
170.It "lower <lower-case alphabetic characters>
171.It "print <printable characters>
172.It "punct <punctuation characters>
173.It "space <space characters>
174.It "upper <upper-case characters>
175.It "xdigit <hexadecimal characters>
176.El
177.Pp
178.\" All classes may be used in
179.\" .Ar string1 ,
180.\" and in
181.\" .Ar string2
182.\" when both the
183.\" .Fl d
184.\" and
185.\" .Fl s
186.\" options are specified.
187.\" Otherwise, only the classes ``upper'' and ``lower'' may be used in
188.\" .Ar string2
189.\" and then only when the corresponding class (``upper'' for ``lower''
190.\" and vice-versa) is specified in the same relative position in
191.\" .Ar string1 .
192.\" .Pp
193With the exception of the ``upper'' and ``lower'' classes, characters
194in the classes are in unspecified order.
195In the ``upper'' and ``lower'' classes, characters are entered in
196ascending order.
197.Pp
198For specific information as to which ASCII characters are included
199in these classes, see
200.Xr ctype 3
201and related manual pages.
202.It [=equiv=]
203Represents all characters or collating (sorting) elements belonging to
204the same equivalence class as
205.Ar equiv .
206If
207there is a secondary ordering within the equivalence class, the characters
208are ordered in ascending sequence.
209Otherwise, they are ordered after their encoded values.
210An example of an equivalence class might be ``c'' and ``ch'' in Spanish;
211English has no equivalence classes.
212.It [#*n]
213Represents
214.Ar n
215repeated occurrences of the character represented by
216.Ar # .
217This
218expression is only valid when it occurs in
219.Ar string2 .
220If
221.Ar n
222is omitted or is zero, it is be interpreted as large enough to extend
223.Ar string2
224sequence to the length of
225.Ar string1 .
226If
227.Ar n
228has a leading zero, it is interpreted as an octal value, otherwise,
229it's interpreted as a decimal value.
230.El
231.Sh DIAGNOSTICS
232The
233.Nm
234utility exits 0 on success, and >0 if an error occurs.
235.Sh EXAMPLES
236The following examples are shown as given to the shell:
237.Pp
238Create a list of the words in file1, one per line, where a word is taken to
239be a maximal string of letters.
240.Pp
241.D1 Li "tr -cs \*q[:alpha:]\*q \*q\en\*q < file1"
242.Pp
243Translate the contents of file1 to upper-case.
244.Pp
245.D1 Li "tr \*q[:lower:]\*q \*q[:upper:]\*q < file1"
246.Pp
247Strip out non-printable characters from file1.
248.Pp
249.D1 Li "tr -cd \*q[:print:]\*q < file1"
250.Sh COMPATIBILITY
251System V has historically implemented character ranges using the syntax
|
252``[c-c]'' instead of the ``c-c'' used by historic BSD implementations and
| 252``[c-c]'' instead of the ``c-c'' used by historic
253.Bx
254implementations and
|
253standardized by POSIX.
254System V shell scripts should work under this implementation as long as
255the range is intended to map in another range, i.e. the command
256``tr [a-z] [A-Z]'' will work as it will map the ``['' character in
257.Ar string1
258to the ``['' character in
259.Ar string2 .
260However, if the shell script is deleting or squeezing characters as in
261the command ``tr -d [a-z]'', the characters ``['' and ``]'' will be
262included in the deletion or compression list which would not have happened
263under an historic System V implementation.
264Additionally, any scripts that depended on the sequence ``a-z'' to
265represent the three characters ``a'', ``-'' and ``z'' will have to be
266rewritten as ``a\e-z''.
267.Pp
268The
269.Nm
270utility has historically not permitted the manipulation of NUL bytes in
271its input and, additionally, stripped NUL's from its input stream.
272This implementation has removed this behavior as a bug.
273.Pp
274The
275.Nm
276utility has historically been extremely forgiving of syntax errors,
277for example, the
278.Fl c
279and
280.Fl s
281options were ignored unless two strings were specified.
282This implementation will not permit illegal syntax.
283.Sh STANDARDS
284The
285.Nm
286utility is expected to be
287.St -p1003.2
288compatible.
289It should be noted that the feature wherein the last character of
290.Ar string2
291is duplicated if
292.Ar string2
293has less characters than
294.Ar string1
295is permitted by POSIX but is not required.
296Shell scripts attempting to be portable to other POSIX systems should use
297the ``[#*]'' convention instead of relying on this behavior.
298The
299.Fl u
300option is an extension to the
301.St -p1003.2
302standard.
| 255standardized by POSIX.
256System V shell scripts should work under this implementation as long as
257the range is intended to map in another range, i.e. the command
258``tr [a-z] [A-Z]'' will work as it will map the ``['' character in
259.Ar string1
260to the ``['' character in
261.Ar string2 .
262However, if the shell script is deleting or squeezing characters as in
263the command ``tr -d [a-z]'', the characters ``['' and ``]'' will be
264included in the deletion or compression list which would not have happened
265under an historic System V implementation.
266Additionally, any scripts that depended on the sequence ``a-z'' to
267represent the three characters ``a'', ``-'' and ``z'' will have to be
268rewritten as ``a\e-z''.
269.Pp
270The
271.Nm
272utility has historically not permitted the manipulation of NUL bytes in
273its input and, additionally, stripped NUL's from its input stream.
274This implementation has removed this behavior as a bug.
275.Pp
276The
277.Nm
278utility has historically been extremely forgiving of syntax errors,
279for example, the
280.Fl c
281and
282.Fl s
283options were ignored unless two strings were specified.
284This implementation will not permit illegal syntax.
285.Sh STANDARDS
286The
287.Nm
288utility is expected to be
289.St -p1003.2
290compatible.
291It should be noted that the feature wherein the last character of
292.Ar string2
293is duplicated if
294.Ar string2
295has less characters than
296.Ar string1
297is permitted by POSIX but is not required.
298Shell scripts attempting to be portable to other POSIX systems should use
299the ``[#*]'' convention instead of relying on this behavior.
300The
301.Fl u
302option is an extension to the
303.St -p1003.2
304standard.
|