1TR(1P) POSIX Programmer's Manual TR(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
13 tr — translate characters
14
16 tr [−c|−C] [−s] string1 string2
17 tr −s [−c|−C] string1
19 tr −d [−c|−C] string1
21 tr −ds [−c|−C] string1 string2
23
25 The tr utility shall copy the standard input to the standard output
26 with substitution or deletion of selected characters. The options spec‐
27 ified and the string1 and string2 operands shall control translations
28 that occur while copying characters and single-character collating ele‐
29 ments.
30
32 The tr utility shall conform to the Base Definitions volume of
33 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
34 The following options shall be supported:
36 −c Complement the set of values specified by string1. See the
38 EXTENDED DESCRIPTION section.
39 −C Complement the set of characters specified by string1. See
41 the EXTENDED DESCRIPTION section.
42 −d Delete all occurrences of input characters that are specified
44 by string1.
45 −s Replace instances of repeated characters with a single char‐
47 acter, as described in the EXTENDED DESCRIPTION section.
48
50 The following operands shall be supported:
51 string1, string2
53 Translation control strings. Each string shall represent a
54 set of characters to be converted into an array of characters
55 used for the translation. For a detailed description of how
56 the strings are interpreted, see the EXTENDED DESCRIPTION
57 section.
58
60 The standard input can be any type of file.
61
63 None.
64
66 The following environment variables shall affect the execution of tr:
67 LANG Provide a default value for the internationalization vari‐
69 ables that are unset or null. (See the Base Definitions vol‐
70 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
71 ables for the precedence of internationalization variables
72 used to determine the values of locale categories.)
73 LC_ALL If set to a non-empty string value, override the values of
75 all the other internationalization variables.
76 LC_COLLATE
78 Determine the locale for the behavior of range expressions
79 and equivalence classes.
80 LC_CTYPE Determine the locale for the interpretation of sequences of
82 bytes of text data as characters (for example, single-byte as
83 opposed to multi-byte characters in arguments) and the behav‐
84 ior of character classes.
85 LC_MESSAGES
87 Determine the locale that should be used to affect the format
88 and contents of diagnostic messages written to standard
89 error.
90 NLSPATH Determine the location of message catalogs for the processing
92 of LC_MESSAGES.
93
95 Default.
96
98 The tr output shall be identical to the input, with the exception of
99 the specified transformations.
100
102 The standard error shall be used only for diagnostic messages.
103
105 None.
106
108 The operands string1 and string2 (if specified) define two arrays of
109 characters. The constructs in the following list can be used to specify
110 characters or single-character collating elements. If any of the con‐
111 structs result in multi-character collating elements, tr shall exclude,
112 without a diagnostic, those multi-character elements from the resulting
113 array.
114 character Any character not described by one of the conventions below
116 shall represent itself.
117 \octal Octal sequences can be used to represent characters with spe‐
119 cific coded values. An octal sequence shall consist of a
120 <backslash> followed by the longest sequence of one, two, or
121 three-octal-digit characters (01234567). The sequence shall
122 cause the value whose encoding is represented by the one,
123 two, or three-digit octal integer to be placed into the
124 array. Multi-byte characters require multiple, concatenated
125 escape sequences of this type, including the leading <back‐
126 slash> for each byte.
127 \character
129 The <backslash>-escape sequences in the Base Definitions vol‐
130 ume of POSIX.1‐2008, Table 5-1, Escape Sequences and Associ‐
131 ated Actions ('\\', '\a', '\b', '\f', '\n', '\r', '\t', '\v')
132 shall be supported. The results of using any other character,
133 other than an octal digit, following the <backslash> are
134 unspecified. Also, if there is no character following the
135 <backslash>, the results are unspecified.
136 c−c In the POSIX locale, this construct shall represent the range
138 of collating elements between the range endpoints (as long as
139 neither endpoint is an octal sequence of the form \octal),
140 inclusive, as defined by the collation sequence. The charac‐
141 ters or collating elements in the range shall be placed in
142 the array in ascending collation sequence. If the second end‐
143 point precedes the starting endpoint in the collation
144 sequence, it is unspecified whether the range of collating
145 elements is empty, or this construct is treated as invalid.
146 In locales other than the POSIX locale, this construct has
147 unspecified behavior.
148 If either or both of the range endpoints are octal sequences
150 of the form \octal, this shall represent the range of spe‐
151 cific coded values between the two range endpoints, inclu‐
152 sive.
153 [:class:] Represents all characters belonging to the defined character
155 class, as defined by the current setting of the LC_CTYPE
156 locale category. The following character class names shall be
157 accepted when specified in string1:
158 alnum blank digit lower punct upper
160 alpha cntrl graph print space xdigit
161 In addition, character class expressions of the form [:name:]
163 shall be recognized in those locales where the name keyword
164 has been given a charclass definition in the LC_CTYPE cate‐
165 gory.
166 When both the −d and −s options are specified, any of the
168 character class names shall be accepted in string2. Other‐
169 wise, only character class names lower or upper are valid in
170 string2 and then only if the corresponding character class
171 (upper and lower, respectively) is specified in the same rel‐
172 ative position in string1. Such a specification shall be
173 interpreted as a request for case conversion. When [:lower:]
174 appears in string1 and [:upper:] appears in string2, the
175 arrays shall contain the characters from the toupper mapping
176 in the LC_CTYPE category of the current locale. When
177 [:upper:] appears in string1 and [:lower:] appears in
178 string2, the arrays shall contain the characters from the
179 tolower mapping in the LC_CTYPE category of the current
180 locale. The first character from each mapping pair shall be
181 in the array for string1 and the second character from each
182 mapping pair shall be in the array for string2 in the same
183 relative position.
184 Except for case conversion, the characters specified by a
186 character class expression shall be placed in the array in an
187 unspecified order.
188 If the name specified for class does not define a valid char‐
190 acter class in the current locale, the behavior is undefined.
191 [=equiv=] Represents all characters or collating elements belonging to
193 the same equivalence class as equiv, as defined by the cur‐
194 rent setting of the LC_COLLATE locale category. An equiva‐
195 lence class expression shall be allowed only in string1, or
196 in string2 when it is being used by the combined −d and −s
197 options. The characters belonging to the equivalence class
198 shall be placed in the array in an unspecified order.
199 [x*n] Represents n repeated occurrences of the character x.
201 Because this expression is used to map multiple characters to
202 one, it is only valid when it occurs in string2. If n is
203 omitted or is zero, it shall be interpreted as large enough
204 to extend the string2-based sequence to the length of the
205 string1-based sequence. If n has a leading zero, it shall be
206 interpreted as an octal value. Otherwise, it shall be inter‐
207 preted as a decimal value.
208 When the −d option is not specified:
210 * If string2 is present, each input character found in the array
212 specified by string1 shall be replaced by the character in the same
213 relative position in the array specified by string2. If the array
214 specified by string2 is shorter that the one specified by string1,
215 or if a character occurs more than once in string1, the results are
216 unspecified.
217 * If the −C option is specified, the complements of the characters
219 specified by string1 (the set of all characters in the current
220 character set, as defined by the current setting of LC_CTYPE,
221 except for those actually specified in the string1 operand) shall
222 be placed in the array in ascending collation sequence, as defined
223 by the current setting of LC_COLLATE.
224 * If the −c option is specified, the complement of the values speci‐
226 fied by string1 shall be placed in the array in ascending order by
227 binary value.
228 * Because the order in which characters specified by character class
230 expressions or equivalence class expressions is undefined, such
231 expressions should only be used if the intent is to map several
232 characters into one. An exception is case conversion, as described
233 previously.
234 When the −d option is specified:
236 * Input characters found in the array specified by string1 shall be
238 deleted.
239 * When the −C option is specified with −d, all characters except
241 those specified by string1 shall be deleted. The contents of
242 string2 are ignored, unless the −s option is also specified.
243 * When the −c option is specified with −d, all values except those
245 specified by string1 shall be deleted. The contents of string2
246 shall be ignored, unless the −s option is also specified.
247 * The same string cannot be used for both the −d and the −s option;
249 when both options are specified, both string1 (used for deletion)
250 and string2 (used for squeezing) shall be required.
251 When the −s option is specified, after any deletions or translations
253 have taken place, repeated sequences of the same character shall be
254 replaced by one occurrence of the same character, if the character is
255 found in the array specified by the last operand. If the last operand
256 contains a character class, such as the following example:
257 tr −s '[:space:]'
259 the last operand's array shall contain all of the characters in that
261 character class. However, in a case conversion, as described previ‐
262 ously, such as:
263 tr −s '[:upper:]' '[:lower:]'
265 the last operand's array shall contain only those characters defined as
267 the second characters in each of the toupper or tolower character
268 pairs, as appropriate.
269 An empty string used for string1 or string2 produces undefined results.
271
273 The following exit values shall be returned:
274 0 All input was processed successfully.
276 >0 An error occurred.
278
280 Default.
281 The following sections are informative.
283
285 If necessary, string1 and string2 can be quoted to avoid pattern match‐
286 ing by the shell.
287 If an ordinary digit (representing itself) is to follow an octal
289 sequence, the octal sequence must use the full three digits to avoid
290 ambiguity.
291 When string2 is shorter than string1, a difference results between his‐
293 torical System V and BSD systems. A BSD system pads string2 with the
294 last character found in string2. Thus, it is possible to do the fol‐
295 lowing:
296 tr 0123456789 d
298 which would translate all digits to the letter 'd'. Since this area is
300 specifically unspecified in this volume of POSIX.1‐2008, both the BSD
301 and System V behaviors are allowed, but a conforming application cannot
302 rely on the BSD behavior. It would have to code the example in the fol‐
303 lowing way:
304 tr 0123456789 '[d*]'
306 It should be noted that, despite similarities in appearance, the string
308 operands used by tr are not regular expressions.
309 Unlike some historical implementations, this definition of the tr util‐
311 ity correctly processes NUL characters in its input stream. NUL charac‐
312 ters can be stripped by using:
313 tr −d '\000'
315
317 1. The following example creates a list of all words in file1 one per
318 line in file2, where a word is taken to be a maximal string of let‐
319 ters.
320 tr −cs "[:alpha:]" "[\n*]" <file1 >file2
322 2. The next example translates all lowercase characters in file1 to
324 uppercase and writes the results to standard output.
325 tr "[:lower:]" "[:upper:]" <file1
327 3. This example uses an equivalence class to identify accented vari‐
329 ants of the base character 'e' in file1, which are stripped of dia‐
330 critical marks and written to file2.
331 tr "[=e=]" "[e*]" <file1 >file2
333
335 In some early proposals, an explicit option −n was added to disable the
336 historical behavior of stripping NUL characters from the input. It was
337 considered that automatically stripping NUL characters from the input
338 was not correct functionality. However, the removal of −n in a later
339 proposal does not remove the requirement that tr correctly process NUL
340 characters in its input stream. NUL characters can be stripped by using
341 tr −d '\000'.
342 Historical implementations of tr differ widely in syntax and behavior.
344 For example, the BSD version has not needed the bracket characters for
345 the repetition sequence. The tr utility syntax is based more closely on
346 the System V and XPG3 model while attempting to accommodate historical
347 BSD implementations. In the case of the short string2 padding, the
348 decision was to unspecify the behavior and preserve System V and XPG3
349 scripts, which might find difficulty with the BSD method. The assump‐
350 tion was made that BSD users of tr have to make accommodations to meet
351 the syntax defined here. Since it is possible to use the repetition
352 sequence to duplicate the desired behavior, whereas there is no simple
353 way to achieve the System V method, this was the correct, if not desir‐
354 able, approach.
355 The use of octal values to specify control characters, while having
357 historical precedents, is not portable. The introduction of escape
358 sequences for control characters should provide the necessary portabil‐
359 ity. It is recognized that this may cause some historical scripts to
360 break.
361 An early proposal included support for multi-character collating ele‐
363 ments. It was pointed out that, while tr does employ some syntactical
364 elements from REs, the aim of tr is quite different; ranges, for exam‐
365 ple, do not have a similar meaning (``any of the chars in the range
366 matches'', versus ``translate each character in the range to the output
367 counterpart''). As a result, the previously included support for multi-
368 character collating elements has been removed. What remains are ranges
369 in current collation order (to support, for example, accented charac‐
370 ters), character classes, and equivalence classes.
371 In XPG3 the [:class:] and [=equiv=] conventions are shown with double
373 brackets, as in RE syntax. However, tr does not implement RE princi‐
374 ples; it just borrows part of the syntax. Consequently, [:class:] and
375 [=equiv=] should be regarded as syntactical elements on a par with
376 [x*n], which is not an RE bracket expression.
377 The standard developers will consider changes to tr that allow it to
379 translate characters between different character encodings, or they
380 will consider providing a new utility to accomplish this.
381 On historical System V systems, a range expression requires enclosing
383 square-brackets, such as:
384 tr '[a-z]' '[A-Z]'
386 However, BSD-based systems did not require the brackets, and this con‐
388 vention is used here to avoid breaking large numbers of BSD scripts:
389 tr a-z A-Z
391 The preceding System V script will continue to work because the brack‐
393 ets, treated as regular characters, are translated to themselves. How‐
394 ever, any System V script that relied on "a‐z" representing the three
395 characters 'a', '−', and 'z' have to be rewritten as "az−".
396 The ISO POSIX‐2:1993 standard had a −c option that behaved similarly to
398 the −C option, but did not supply functionality equivalent to the −c
399 option specified in POSIX.1‐2008. This meant that historical practice
400 of being able to specify tr −cd\000−\177 (which would delete all bytes
401 with the top bit set) would have no effect because, in the C locale,
402 bytes with the values octal 200 to octal 377 are not characters.
403 The earlier version also said that octal sequences referred to collat‐
405 ing elements and could be placed adjacent to each other to specify
406 multi-byte characters. However, it was noted that this caused ambigui‐
407 ties because tr would not be able to tell whether adjacent octal
408 sequences were intending to specify multi-byte characters or multiple
409 single byte characters. POSIX.1‐2008 specifies that octal sequences
410 always refer to single byte binary values when used to specify an end‐
411 point of a range of collating elements.
412 Earlier versions of this standard allowed for implementations with
414 bytes other than eight bits, but this has been modified in this ver‐
415 sion.
416
418 None.
419
421 sed
422 The Base Definitions volume of POSIX.1‐2008, Table 5-1, Escape
424 Sequences and Associated Actions, Chapter 8, Environment Variables,
425 Section 12.2, Utility Syntax Guidelines
426
428 Portions of this text are reprinted and reproduced in electronic form
429 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
430 -- Portable Operating System Interface (POSIX), The Open Group Base
431 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
432 cal and Electronics Engineers, Inc and The Open Group. (This is
433 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
434 event of any discrepancy between this version and the original IEEE and
435 The Open Group Standard, the original IEEE and The Open Group Standard
436 is the referee document. The original Standard can be obtained online
437 at http://www.unix.org/online.html .
438 Any typographical or formatting errors that appear in this page are
440 most likely to have been introduced during the conversion of the source
441 files to man page format. To report such errors, see https://www.ker‐
442 nel.org/doc/man-pages/reporting_bugs.html .
443IEEE/The Open Group 2013 TR(1P)