home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / textutils-1.19-bin.lha / info / textutils.info-2 (.txt) < prev    next >
GNU Info File  |  1996-10-12  |  44KB  |  813 lines
  1. This is Info file textutils.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/fsf/textutils/doc/textutils.texi.
  3. START-INFO-DIR-ENTRY
  4. * Text utilities: (textutils).          GNU text utilities.
  5. * cat: (textutils)cat invocation.               Concatenate and write files.
  6. * cksum: (textutils)cksum invocation.           Print POSIX CRC checksum.
  7. * comm: (textutils)comm invocation.             Compare sorted files by line.
  8. * csplit: (textutils)csplit invocation.         Split by context.
  9. * cut: (textutils)cut invocation.               Print selected parts of lines.
  10. * expand: (textutils)expand invocation.         Convert tabs to spaces.
  11. * fmt: (textutils)fmt invocation.               Reformat paragraph text.
  12. * fold: (textutils)fold invocation.             Wrap long input lines.
  13. * head: (textutils)head invocation.             Output the first part of files.
  14. * join: (textutils)join invocation.             Join lines on a common field.
  15. * md5sum: (textutils)md5sum invocation.         Print or check message-digests.
  16. * nl: (textutils)nl invocation.                 Number lines and write files.
  17. * od: (textutils)od invocation.                 Dump files in octal, etc.
  18. * paste: (textutils)paste invocation.           Merge lines of files.
  19. * pr: (textutils)pr invocation.                 Paginate or columnate files.
  20. * sort: (textutils)sort invocation.             Sort text files.
  21. * split: (textutils)split invocation.           Split into fixed-size pieces.
  22. * sum: (textutils)sum invocation.               Print traditional checksum.
  23. * tac: (textutils)tac invocation.               Reverse files.
  24. * tail: (textutils)tail invocation.             Output the last part of files.
  25. * tr: (textutils)tr invocation.                 Translate characters.
  26. * unexpand: (textutils)unexpand invocation.     Convert spaces to tabs.
  27. * uniq: (textutils)uniq invocation.             Uniqify files.
  28. * wc: (textutils)wc invocation.                 Byte, word, and line counts.
  29. END-INFO-DIR-ENTRY
  30.    This file documents the GNU text utilities.
  31.    Copyright (C) 1994, 95, 96 Free Software Foundation, Inc.
  32.    Permission is granted to make and distribute verbatim copies of this
  33. manual provided the copyright notice and this permission notice are
  34. preserved on all copies.
  35.    Permission is granted to copy and distribute modified versions of
  36. this manual under the conditions for verbatim copying, provided that
  37. the entire resulting derived work is distributed under the terms of a
  38. permission notice identical to this one.
  39.    Permission is granted to copy and distribute translations of this
  40. manual into another language, under the above conditions for modified
  41. versions, except that this permission notice may be stated in a
  42. translation approved by the Foundation.
  43. File: textutils.info,  Node: sort invocation,  Next: uniq invocation,  Up: Operating on sorted files
  44. `sort': Sort text files
  45. =======================
  46.    `sort' sorts, merges, or compares all the lines from the given
  47. files, or standard input if none are given or for a FILE of `-'.  By
  48. default, `sort' writes the results to standard output.  Synopsis:
  49.      sort [OPTION]... [FILE]...
  50.    `sort' has three modes of operation: sort (the default), merge, and
  51. check for sortedness.  The following options change the operation mode:
  52.      Check whether the given files are already sorted: if they are not
  53.      all sorted, print an error message and exit with a status of 1.
  54.      Otherwise, exit successfully.
  55.      Merge the given files by sorting them as a group.  Each input file
  56.      must always be individually sorted.  It always works to sort
  57.      instead of merge; merging is provided because it is faster, in the
  58.      case where it works.
  59.    A pair of lines is compared as follows: if any key fields have been
  60. specified, `sort' compares each pair of fields, in the order specified
  61. on the command line, according to the associated ordering options,
  62. until a difference is found or no fields are left.
  63.    If any of the global options `Mbdfinr' are given but no key fields
  64. are specified, `sort' compares the entire lines according to the global
  65. options.
  66.    Finally, as a last resort when all keys compare equal (or if no
  67. ordering options were specified at all), `sort' compares the lines byte
  68. by byte in machine collating sequence.  The last resort comparison
  69. honors the `-r' global option.  The `-s' (stable) option disables this
  70. last-resort comparison so that lines in which all fields compare equal
  71. are left in their original relative order.  If no fields or global
  72. options are specified, `-s' has no effect.
  73.    GNU `sort' (as specified for all GNU utilities) has no limits on
  74. input line length or restrictions on bytes allowed within lines.  In
  75. addition, if the final byte of an input file is not a newline, GNU
  76. `sort' silently supplies one.
  77.    Upon any error, `sort' exits with a status of `2'.
  78.    If the environment variable `TMPDIR' is set, `sort' uses its value
  79. as the directory for temporary files instead of `/tmp'.  The `-T
  80. TEMPDIR' option in turn overrides the environment variable.
  81.    The following options affect the ordering of output lines.  They may
  82. be specified globally or as part of a specific key field.  If no key
  83. fields are specified, global options apply to comparison of entire
  84. lines; otherwise the global options are inherited by key fields that do
  85. not specify any special options of their own.
  86.      Ignore leading blanks when finding sort keys in each line.
  87.      Sort in "phone directory" order: ignore all characters except
  88.      letters, digits and blanks when sorting.
  89.      Fold lowercase characters into the equivalent uppercase characters
  90.      when sorting so that, for example, `b' and `B' sort as equal.
  91.      Sort numerically, but use strtod(3) to arrive at the numeric
  92.      values.  This allows floating point numbers to be specified in
  93.      scientific notation, like `1.0e-34' and `10e100'.  Use this option
  94.      only if there is no alternative;  it is much slower than `-n' and
  95.      numbers with too many significant digits will be compared as if
  96.      they had been truncated.  In addition, numbers outside the range
  97.      of representable double precision floating point numbers are
  98.      treated as if they were zeroes; overflow and underflow are not
  99.      reported.
  100.      Ignore characters outside the printable ASCII range 040-0176 octal
  101.      (inclusive) when sorting.
  102.      An initial string, consisting of any amount of whitespace, followed
  103.      by three letters abbreviating a month name, is folded to UPPER
  104.      case and compared in the order `JAN' < `FEB' < ... < `DEC'.
  105.      Invalid names compare low to valid names.
  106.      Sort numerically: the number begins each line; specifically, it
  107.      consists of optional whitespace, an optional `-' sign, and zero or
  108.      more digits, optionally followed by a decimal point and zero or
  109.      more digits.
  110.      `sort -n' uses what might be considered an unconventional method
  111.      to compare strings representing floating point numbers.  Rather
  112.      than first converting each string to the C `double' type and then
  113.      comparing those values, sort aligns the decimal points in the two
  114.      strings and compares the strings a character at a time.  One
  115.      benefit of using this approach is its speed.  In practice this is
  116.      much more efficient than performing the two corresponding
  117.      string-to-double (or even string-to-integer) conversions and then
  118.      comparing doubles.  In addition, there is no corresponding loss of
  119.      precision.  Converting each string to `double' before comparison
  120.      would limit precision to about 16 digits on most systems.
  121.      Neither a leading `+' nor exponential notation is recognized.  To
  122.      compare such strings numerically, use the `-g' option.
  123.      Reverse the result of comparison, so that lines with greater key
  124.      values appear earlier in the output instead of later.
  125.    Other options are:
  126. `-o OUTPUT-FILE'
  127.      Write output to OUTPUT-FILE instead of standard output.  If
  128.      OUTPUT-FILE is one of the input files, `sort' copies it to a
  129.      temporary file before sorting and writing the output to
  130.      OUTPUT-FILE.
  131. `-t SEPARATOR'
  132.      Use character SEPARATOR as the field separator when finding the
  133.      sort keys in each line.  By default, fields are separated by the
  134.      empty string between a non-whitespace character and a whitespace
  135.      character.  That is, given the input line ` foo bar', `sort'
  136.      breaks it into fields ` foo' and ` bar'.  The field separator is
  137.      not considered to be part of either the field preceding or the
  138.      field following.
  139.      For the default case or the `-m' option, only output the first of
  140.      a sequence of lines that compare equal.  For the `-c' option,
  141.      check that no pair of consecutive lines compares equal.
  142. `-k POS1[,POS2]'
  143.      The recommended, POSIX, option for specifying a sort field.  The
  144.      field consists of the line between POS1 and POS2 (or the end of
  145.      the line, if POS2 is omitted), inclusive.  Fields and character
  146.      positions are numbered starting with 1.  See below.
  147.      Treat the input as a set of lines, each terminated by a zero byte
  148.      (ASCII NUL (Null) character) instead of a ASCII LF (Line Feed.)
  149.      This option can be useful in conjunction with `perl -0' or `find
  150.      -print0' and `xargs -0' which do the same in order to reliably
  151.      handle arbitrary pathnames (even those which contain Line Feed
  152.      characters.)
  153. `+POS1[-POS2]'
  154.      The obsolete, traditional option for specifying a sort field.  The
  155.      field consists of the line between POS1 and up to but *not
  156.      including* POS2 (or the end of the line if POS2 is omitted).
  157.      Fields and character positions are numbered starting with 0.  See
  158.      below.
  159.    In addition, when GNU `sort' is invoked with exactly one argument,
  160. options `--help' and `--version' are recognized.  *Note Common
  161. options::.
  162.    Historical (BSD and System V) implementations of `sort' have
  163. differed in their interpretation of some options, particularly `-b',
  164. `-f', and `-n'.  GNU sort follows the POSIX behavior, which is usually
  165. (but not always!) like the System V behavior.  According to POSIX, `-n'
  166. no longer implies `-b'.  For consistency, `-M' has been changed in the
  167. same way.  This may affect the meaning of character positions in field
  168. specifications in obscure cases.  The only fix is to add an explicit
  169. `-b'.
  170.    A position in a sort field specified with the `-k' or `+' option has
  171. the form `F.C', where F is the number of the field to use and C is the
  172. number of the first character from the beginning of the field (for
  173. `+POS') or from the end of the previous field (for `-POS').  If the `.C'
  174. is omitted, it is taken to be the first character in the field.  If the
  175. `-b' option was specified, the `.C' part of a field specification is
  176. counted from the first nonblank character of the field (for `+POS') or
  177. from the first nonblank character following the previous field (for
  178. `-POS').
  179.    A sort key option may also have any of the option letters `Mbdfinr'
  180. appended to it, in which case the global ordering options are not used
  181. for that particular field.  The `-b' option may be independently
  182. attached to either or both of the `+POS' and `-POS' parts of a field
  183. specification, and if it is inherited from the global options it will
  184. be attached to both.  If a `-n' or `-M' option is used, thus implying a
  185. `-b' option, the `-b' option is taken to apply to both the `+POS' and
  186. the `-POS' parts of a key specification.  Keys may span multiple fields.
  187.    Here are some examples to illustrate various combinations of options.
  188. In them, the POSIX `-k' option is used to specify sort keys rather than
  189. the obsolete `+POS1-POS2' syntax.
  190.    * Sort in descending (reverse) numeric order.
  191.           sort -nr
  192.      Sort alphabetically, omitting the first and second fields.  This
  193.      uses a single key composed of the characters beginning at the
  194.      start of field three and extending to the end of each line.
  195.           sort -k3
  196.    * Sort numerically on the second field and resolve ties by sorting
  197.      alphabetically on the third and fourth characters of field five.
  198.      Use `:' as the field delimiter.
  199.           sort -t : -k 2,2n -k 5.3,5.4
  200.      Note that if you had written `-k 2' instead of `-k 2,2' `sort'
  201.      would have used all characters beginning in the second field and
  202.      extending to the end of the line as the primary *numeric* key.
  203.      For the large majority of applications, treating keys spanning
  204.      more than one field as numeric will not do what you expect.
  205.      Also note that the `n' modifier was applied to the field-end
  206.      specifier for the first key.  It would have been equivalent to
  207.      specify `-k 2n,2' or `-k 2n,2n'.  All modifiers except `b' apply
  208.      to the associated *field*, regardless of whether the modifier
  209.      character is attached to the field-start and/or the field-end part
  210.      of the key specifier.
  211.    * Sort the password file on the fifth field and ignore any leading
  212.      white space.  Sort lines with equal values in field five on the
  213.      numeric user ID in field three.
  214.           sort -t : -k 5b,5 -k 3,3n /etc/passwd
  215.      An alternative is to use the global numeric modifier `-n'.
  216.           sort -t : -n -k 5b,5 -k 3,3 /etc/passwd
  217.    * Generate a tags file in case insensitive sorted order.
  218.           find src -type f -print0 | sort -t / -z -f | xargs -0 etags --append
  219.      The use of `-print0', `-z', and `-0' in this case mean that
  220.      pathnames that contain Line Feed characters will not get broken up
  221.      by the sort operation.
  222.      Finally, to ignore both leading and trailing white space, you
  223.      could have applied the `b' modifier to the field-end specifier for
  224.      the first key,
  225.           sort -t : -n -k 5b,5b -k 3,3 /etc/passwd
  226.      or by using the global `-b' modifier instead of `-n' and an
  227.      explicit `n' with the second key specifier.
  228.           sort -t : -b -k 5,5 -k 3,3n /etc/passwd
  229. File: textutils.info,  Node: uniq invocation,  Next: comm invocation,  Prev: sort invocation,  Up: Operating on sorted files
  230. `uniq': Uniqify files
  231. =====================
  232.    `uniq' writes the unique lines in the given `input', or standard
  233. input if nothing is given or for an INPUT name of `-'.  Synopsis:
  234.      uniq [OPTION]... [INPUT [OUTPUT]]
  235.    By default, `uniq' prints the unique lines in a sorted file, i.e.,
  236. discards all but one of identical successive lines.  Optionally, it can
  237. instead show only lines that appear exactly once, or lines that appear
  238. more than once.
  239.    The input must be sorted.  If your input is not sorted, perhaps you
  240. want to use `sort -u'.
  241.    If no OUTPUT file is specified, `uniq' writes to standard output.
  242.    The program accepts the following options.  Also see *Note Common
  243. options::.
  244. `-f N'
  245. `--skip-fields=N'
  246.      Skip N fields on each line before checking for uniqueness.  Fields
  247.      are sequences of non-space non-tab characters that are separated
  248.      from each other by at least one spaces or tabs.
  249. `-s N'
  250. `--skip-chars=N'
  251.      Skip N characters before checking for uniqueness.  If you use both
  252.      the field and character skipping options, fields are skipped over
  253.      first.
  254. `--count'
  255.      Print the number of times each line occurred along with the line.
  256. `--ignore-case'
  257.      Ignore differences in case when comparing lines.
  258. `--repeated'
  259.      Print only duplicate lines.
  260. `--unique'
  261.      Print only unique lines.
  262. `-w N'
  263. `--check-chars=N'
  264.      Compare N characters on each line (after skipping any specified
  265.      fields and characters).  By default the entire rest of the lines
  266.      are compared.
  267. File: textutils.info,  Node: comm invocation,  Prev: uniq invocation,  Up: Operating on sorted files
  268. `comm': Compare two sorted files line by line
  269. =============================================
  270.    `comm' writes to standard output lines that are common, and lines
  271. that are unique, to two input files; a file name of `-' means standard
  272. input.  Synopsis:
  273.      comm [OPTION]... FILE1 FILE2
  274.    The input files must be sorted before `comm' can be used.
  275.    With no options, `comm' produces three column output.  Column one
  276. contains lines unique to FILE1, column two contains lines unique to
  277. FILE2, and column three contains lines common to both files.  Columns
  278. are separated by TAB.
  279.    The options `-1', `-2', and `-3' suppress printing of the
  280. corresponding columns.  Also see *Note Common options::.
  281. File: textutils.info,  Node: Operating on fields within a line,  Next: Operating on characters,  Prev: Operating on sorted files,  Up: Top
  282. Operating on fields within a line
  283. *********************************
  284. * Menu:
  285. * cut invocation::              Print selected parts of lines.
  286. * paste invocation::            Merge lines of files.
  287. * join invocation::             Join lines on a common field.
  288. File: textutils.info,  Node: cut invocation,  Next: paste invocation,  Up: Operating on fields within a line
  289. `cut': Print selected parts of lines
  290. ====================================
  291.    `cut' writes to standard output selected parts of each line of each
  292. input file, or standard input if no files are given or for a file name
  293. of `-'.  Synopsis:
  294.      cut [OPTION]... [FILE]...
  295.    In the table which follows, the BYTE-LIST, CHARACTER-LIST, and
  296. FIELD-LIST are one or more numbers or ranges (two numbers separated by
  297. a dash) separated by commas.  Bytes, characters, and fields are
  298. numbered from starting at 1.  Incomplete ranges may be given: `-M'
  299. means `1-M'; `N-' means `N' through end of line or last field.
  300.    The program accepts the following options.  Also see *Note Common
  301. options::.
  302. `-b BYTE-LIST'
  303. `--bytes=BYTE-LIST'
  304.      Print only the bytes in positions listed in BYTE-LIST.  Tabs and
  305.      backspaces are treated like any other character; they take up 1
  306.      byte.
  307. `-c CHARACTER-LIST'
  308. `--characters=CHARACTER-LIST'
  309.      Print only characters in positions listed in CHARACTER-LIST.  The
  310.      same as `-b' for now, but internationalization will change that.
  311.      Tabs and backspaces are treated like any other character; they
  312.      take up 1 character.
  313. `-f FIELD-LIST'
  314. `--fields=FIELD-LIST'
  315.      Print only the fields listed in FIELD-LIST.  Fields are separated
  316.      by a TAB by default.
  317. `-d DELIM'
  318. `--delimiter=DELIM'
  319.      For `-f', fields are separated by the first character in DELIM
  320.      (default is TAB).
  321.      Do not split multi-byte characters (no-op for now).
  322. `--only-delimited'
  323.      For `-f', do not print lines that do not contain the field
  324.      separator character.
  325. File: textutils.info,  Node: paste invocation,  Next: join invocation,  Prev: cut invocation,  Up: Operating on fields within a line
  326. `paste': Merge lines of files
  327. =============================
  328.    `paste' writes to standard output lines consisting of sequentially
  329. corresponding lines of each given file, separated by TAB.  Standard
  330. input is used for a file name of `-' or if no input files are given.
  331.    Synopsis:
  332.      paste [OPTION]... [FILE]...
  333.    The program accepts the following options.  Also see *Note Common
  334. options::.
  335. `--serial'
  336.      Paste the lines of one file at a time rather than one line from
  337.      each file.
  338. `-d DELIM-LIST'
  339. `--delimiters DELIM-LIST'
  340.      Consecutively use the characters in DELIM-LIST instead of TAB to
  341.      separate merged lines.  When DELIM-LIST is exhausted, start again
  342.      at its beginning.
  343. File: textutils.info,  Node: join invocation,  Prev: paste invocation,  Up: Operating on fields within a line
  344. `join': Join lines on a common field
  345. ====================================
  346.    `join' writes to standard output a line for each pair of input lines
  347. that have identical join fields.  Synopsis:
  348.      join [OPTION]... FILE1 FILE2
  349.    Either FILE1 or FILE2 (but not both) can be `-', meaning standard
  350. input.  FILE1 and FILE2 should be already sorted in increasing order
  351. (not numerically) on the join fields; unless the `-t' option is given,
  352. they should be sorted ignoring blanks at the start of the join field,
  353. as in `sort -b'.  If the `--ignore-case' option is given, lines should
  354. be sorted without regard to the case of characters in the join field,
  355. as in `sort -f'.
  356.    The defaults are: the join field is the first field in each line;
  357. fields in the input are separated by one or more blanks, with leading
  358. blanks on the line ignored; fields in the output are separated by a
  359. space; each output line consists of the join field, the remaining
  360. fields from FILE1, then the remaining fields from FILE2.
  361.    The program accepts the following options.  Also see *Note Common
  362. options::.
  363. `-a FILE-NUMBER'
  364.      Print a line for each unpairable line in file FILE-NUMBER (either
  365.      `1' or `2'), in addition to the normal output.
  366. `-e STRING'
  367.      Replace those output fields that are missing in the input with
  368.      STRING.
  369. `--ignore-case'
  370.      Ignore differences in case when comparing keys.  With this option,
  371.      the lines of the input files must be ordered in the same way.  Use
  372.      `sort -f' to produce this ordering.
  373. `-1 FIELD'
  374. `-j1 FIELD'
  375.      Join on field FIELD (a positive integer) of file 1.
  376. `-2 FIELD'
  377. `-j2 FIELD'
  378.      Join on field FIELD (a positive integer) of file 2.
  379. `-j FIELD'
  380.      Equivalent to `-1 FIELD -2 FIELD'.
  381. `-o FIELD-LIST...'
  382.      Construct each output line according to the format in FIELD-LIST.
  383.      Each element in FIELD-LIST is either the single character `0' or
  384.      has the form M.N where the file number, M, is `1' or `2' and N is
  385.      a positive field number.
  386.      A field specification of `0' denotes the join field.  In most
  387.      cases, the functionality of the `0' field spec may be reproduced
  388.      using the explicit M.N that corresponds to the join field.
  389.      However, when printing unpairable lines (using either of the `-a'
  390.      or `-v' options), there is no way to specify the join field using
  391.      M.N in FIELD-LIST if there are unpairable lines in both files.  To
  392.      give `join' that functionality, POSIX invented the `0' field
  393.      specification notation.
  394.      The elements in FIELD-LIST are separated by commas or blanks.
  395.      Multiple FIELD-LIST arguments can be given after a single `-o'
  396.      option; the values of all lists given with `-o' are concatenated
  397.      together.  All output lines - including those printed because of
  398.      any -a or -v option - are subject to the specified FIELD-LIST.
  399. `-t CHAR'
  400.      Use character CHAR as the input and output field separator.
  401. `-v FILE-NUMBER'
  402.      Print a line for each unpairable line in file FILE-NUMBER (either
  403.      `1' or `2'), instead of the normal output.
  404.    In addition, when GNU `join' is invoked with exactly one argument,
  405. options `--help' and `--version' are recognized.  *Note Common
  406. options::.
  407. File: textutils.info,  Node: Operating on characters,  Next: Opening the software toolbox,  Prev: Operating on fields within a line,  Up: Top
  408. Operating on characters
  409. ***********************
  410.    This commands operate on individual characters.
  411. * Menu:
  412. * tr invocation::               Translate, squeeze, and/or delete characters.
  413. * expand invocation::           Convert tabs to spaces.
  414. * unexpand invocation::         Convert spaces to tabs.
  415. File: textutils.info,  Node: tr invocation,  Next: expand invocation,  Up: Operating on characters
  416. `tr': Translate, squeeze, and/or delete characters
  417. ==================================================
  418.    Synopsis:
  419.      tr [OPTION]... SET1 [SET2]
  420.    `tr' copies standard input to standard output, performing one of the
  421. following operations:
  422.    * translate, and optionally squeeze repeated characters in the
  423.      result,
  424.    * squeeze repeated characters,
  425.    * delete characters,
  426.    * delete characters, then squeeze repeated characters from the
  427.      result.
  428.    The SET1 and (if given) SET2 arguments define ordered sets of
  429. characters, referred to below as SET1 and SET2.  These sets are the
  430. characters of the input that `tr' operates on.  The `--complement'
  431. (`-c') option replaces SET1 with its complement (all of the characters
  432. that are not in SET1).
  433. * Menu:
  434. * Character sets::              Specifying sets of characters.
  435. * Translating::                 Changing one characters to another.
  436. * Squeezing::                   Squeezing repeats and deleting.
  437. * Warnings in tr::              Warning messages.
  438. File: textutils.info,  Node: Character sets,  Next: Translating,  Up: tr invocation
  439. Specifying sets of characters
  440. -----------------------------
  441.    The format of the SET1 and SET2 arguments resembles the format of
  442. regular expressions; however, they are not regular expressions, only
  443. lists of characters.  Most characters simply represent themselves in
  444. these strings, but the strings can contain the shorthands listed below,
  445. for convenience.  Some of them can be used only in SET1 or SET2, as
  446. noted below.
  447. Backslash escapes.
  448.      A backslash followed by a character not listed below causes an
  449.      error message.
  450.     `\a'
  451.           Control-G,
  452.     `\b'
  453.           Control-H,
  454.     `\f'
  455.           Control-L,
  456.     `\n'
  457.           Control-J,
  458.     `\r'
  459.           Control-M,
  460.     `\t'
  461.           Control-I,
  462.     `\v'
  463.           Control-K,
  464.     `\OOO'
  465.           The character with the value given by OOO, which is 1 to 3
  466.           octal digits,
  467.     `\\'
  468.           A backslash.
  469. Ranges.
  470.      The notation `M-N' expands to all of the characters from M through
  471.      N, in ascending order.  M should collate before N; if it doesn't,
  472.      an error results.  As an example, `0-9' is the same as
  473.      `0123456789'.  Although GNU `tr' does not support the System V
  474.      syntax that uses square brackets to enclose ranges, translations
  475.      specified in that format will still work as long as the brackets
  476.      in STRING1 correspond to identical brackets in STRING2.
  477. Repeated characters.
  478.      The notation `[C*N]' in SET2 expands to N copies of character C.
  479.      Thus, `[y*6]' is the same as `yyyyyy'.  The notation `[C*]' in
  480.      STRING2 expands to as many copies of C as are needed to make SET2
  481.      as long as SET1.  If N begins with `0', it is interpreted in
  482.      octal, otherwise in decimal.
  483. Character classes.
  484.      The notation `[:CLASS:]' expands to all of the characters in the
  485.      (predefined) class CLASS.  The characters expand in no particular
  486.      order, except for the `upper' and `lower' classes, which expand in
  487.      ascending order.  When the `--delete' (`-d') and
  488.      `--squeeze-repeats' (`-s') options are both given, any character
  489.      class can be used in SET2.  Otherwise, only the character classes
  490.      `lower' and `upper' are accepted in SET2, and then only if the
  491.      corresponding character class (`upper' and `lower', respectively)
  492.      is specified in the same relative position in SET1.  Doing this
  493.      specifies case conversion.  The class names are given below; an
  494.      error results when an invalid class name is given.
  495.     `alnum'
  496.           Letters and digits.
  497.     `alpha'
  498.           Letters.
  499.     `blank'
  500.           Horizontal whitespace.
  501.     `cntrl'
  502.           Control characters.
  503.     `digit'
  504.           Digits.
  505.     `graph'
  506.           Printable characters, not including space.
  507.     `lower'
  508.           Lowercase letters.
  509.     `print'
  510.           Printable characters, including space.
  511.     `punct'
  512.           Punctuation characters.
  513.     `space'
  514.           Horizontal or vertical whitespace.
  515.     `upper'
  516.           Uppercase letters.
  517.     `xdigit'
  518.           Hexadecimal digits.
  519. Equivalence classes.
  520.      The syntax `[=C=]' expands to all of the characters that are
  521.      equivalent to C, in no particular order.  Equivalence classes are
  522.      a relatively recent invention intended to support non-English
  523.      alphabets.  But there seems to be no standard way to define them
  524.      or determine their contents.  Therefore, they are not fully
  525.      implemented in GNU `tr'; each character's equivalence class
  526.      consists only of that character, which is of no particular use.
  527. File: textutils.info,  Node: Translating,  Next: Squeezing,  Prev: Character sets,  Up: tr invocation
  528. Translating
  529. -----------
  530.    `tr' performs translation when SET1 and SET2 are both given and the
  531. `--delete' (`-d') option is not given.  `tr' translates each character
  532. of its input that is in SET1 to the corresponding character in SET2.
  533. Characters not in SET1 are passed through unchanged.  When a character
  534. appears more than once in SET1 and the corresponding characters in SET2
  535. are not all the same, only the final one is used.  For example, these
  536. two commands are equivalent:
  537.      tr aaa xyz
  538.      tr a z
  539.    A common use of `tr' is to convert lowercase characters to
  540. uppercase.  This can be done in many ways.  Here are three of them:
  541.      tr abcdefghijklmnopqrstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ
  542.      tr a-z A-Z
  543.      tr '[:lower:]' '[:upper:]'
  544.    When `tr' is performing translation, SET1 and SET2 typically have
  545. the same length.  If SET1 is shorter than SET2, the extra characters at
  546. the end of SET2 are ignored.
  547.    On the other hand, making SET1 longer than SET2 is not portable;
  548. POSIX.2 says that the result is undefined.  In this situation, BSD `tr'
  549. pads SET2 to the length of SET1 by repeating the last character of SET2
  550. as many times as necessary.  System V `tr' truncates SET1 to the length
  551. of SET2.
  552.    By default, GNU `tr' handles this case like BSD `tr'.  When the
  553. `--truncate-set1' (`-t') option is given, GNU `tr' handles this case
  554. like the System V `tr' instead.  This option is ignored for operations
  555. other than translation.
  556.    Acting like System V `tr' in this case breaks the relatively common
  557. BSD idiom:
  558.      tr -cs A-Za-z0-9 '\012'
  559. because it converts only zero bytes (the first element in the
  560. complement of SET1), rather than all non-alphanumerics, to newlines.
  561. File: textutils.info,  Node: Squeezing,  Next: Warnings in tr,  Prev: Translating,  Up: tr invocation
  562. Squeezing repeats and deleting
  563. ------------------------------
  564.    When given just the `--delete' (`-d') option, `tr' removes any input
  565. characters that are in SET1.
  566.    When given just the `--squeeze-repeats' (`-s') option, `tr' replaces
  567. each input sequence of a repeated character that is in SET1 with a
  568. single occurrence of that character.
  569.    When given both `--delete' and `--squeeze-repeats', `tr' first
  570. performs any deletions using SET1, then squeezes repeats from any
  571. remaining characters using SET2.
  572.    The `--squeeze-repeats' option may also be used when translating, in
  573. which case `tr' first performs translation, then squeezes repeats from
  574. any remaining characters using SET2.
  575.    Here are some examples to illustrate various combinations of options:
  576.    * Remove all zero bytes:
  577.           tr -d '\000'
  578.    * Put all words on lines by themselves.  This converts all
  579.      non-alphanumeric characters to newlines, then squeezes each string
  580.      of repeated newlines into a single newline:
  581.           tr -cs '[a-zA-Z0-9]' '[\n*]'
  582.    * Convert each sequence of repeated newlines to a single newline:
  583.           tr -s '\n'
  584. File: textutils.info,  Node: Warnings in tr,  Prev: Squeezing,  Up: tr invocation
  585. Warning messages
  586. ----------------
  587.    Setting the environment variable `POSIXLY_CORRECT' turns off the
  588. following warning and error messages, for strict compliance with
  589. POSIX.2.  Otherwise, the following diagnostics are issued:
  590.   1. When the `--delete' option is given but `--squeeze-repeats' is
  591.      not, and SET2 is given, GNU `tr' by default prints a usage message
  592.      and exits, because SET2 would not be used.  The POSIX
  593.      specification says that SET2 must be ignored in this case.
  594.      Silently ignoring arguments is a bad idea.
  595.   2. When an ambiguous octal escape is given.  For example, `\400' is
  596.      actually `\40' followed by the digit `0', because the value 400
  597.      octal does not fit into a single byte.
  598.    GNU `tr' does not provide complete BSD or System V compatibility.
  599. For example, it is impossible to disable interpretation of the POSIX
  600. constructs `[:alpha:]', `[=c=]', and `[c*10]'.  Also, GNU `tr' does not
  601. delete zero bytes automatically, unlike traditional Unix versions,
  602. which provide no way to preserve zero bytes.
  603. File: textutils.info,  Node: expand invocation,  Next: unexpand invocation,  Prev: tr invocation,  Up: Operating on characters
  604. `expand': Convert tabs to spaces
  605. ================================
  606.    `expand' writes the contents of each given FILE, or standard input
  607. if none are given or for a FILE of `-', to standard output, with tab
  608. characters converted to the appropriate number of spaces.  Synopsis:
  609.      expand [OPTION]... [FILE]...
  610.    By default, `expand' converts all tabs to spaces.  It preserves
  611. backspace characters in the output; they decrement the column count for
  612. tab calculations.  The default action is equivalent to `-8' (set tabs
  613. every 8 columns).
  614.    The program accepts the following options.  Also see *Note Common
  615. options::.
  616. `-TAB1[,TAB2]...'
  617. `-t TAB1[,TAB2]...'
  618. `--tabs=TAB1[,TAB2]...'
  619.      If only one tab stop is given, set the tabs TAB1 spaces apart
  620.      (default is 8).  Otherwise, set the tabs at columns TAB1, TAB2,
  621.      ... (numbered from 0), and replace any tabs beyond the last
  622.      tabstop given with single spaces.  If the tabstops are specified
  623.      with the `-t' or `--tabs' option, they can be separated by blanks
  624.      as well as by commas.
  625. `--initial'
  626.      Only convert initial tabs (those that precede all non-space or
  627.      non-tab characters) on each line to spaces.
  628. File: textutils.info,  Node: unexpand invocation,  Prev: expand invocation,  Up: Operating on characters
  629. `unexpand': Convert spaces to tabs
  630. ==================================
  631.    `unexpand' writes the contents of each given FILE, or standard input
  632. if none are given or for a FILE of `-', to standard output, with
  633. strings of two or more space or tab characters converted to as many
  634. tabs as possible followed by as many spaces as are needed.  Synopsis:
  635.      unexpand [OPTION]... [FILE]...
  636.    By default, `unexpand' converts only initial spaces and tabs (those
  637. that precede all non space or tab characters) on each line.  It
  638. preserves backspace characters in the output; they decrement the column
  639. count for tab calculations.  By default, tabs are set at every 8th
  640. column.
  641.    The program accepts the following options.  Also see *Note Common
  642. options::.
  643. `-TAB1[,TAB2]...'
  644. `-t TAB1[,TAB2]...'
  645. `--tabs=TAB1[,TAB2]...'
  646.      If only one tab stop is given, set the tabs TAB1 spaces apart
  647.      instead of the default 8.  Otherwise, set the tabs at columns
  648.      TAB1, TAB2, ... (numbered from 0), and leave spaces and tabs
  649.      beyond the tabstops given unchanged.  If the tabstops are specified
  650.      with the `-t' or `--tabs' option, they can be separated by blanks
  651.      as well as by commas.  This option implies the `-a' option.
  652. `--all'
  653.      Convert all strings of two or more spaces or tabs, not just initial
  654.      ones, to tabs.
  655. File: textutils.info,  Node: Opening the software toolbox,  Next: Index,  Prev: Operating on characters,  Up: Top
  656. Opening the software toolbox
  657. ****************************
  658.    This chapter originally appeared in `Linux Journal', volume 1,
  659. number 2, in the `What's GNU?' column. It was written by Arnold Robbins.
  660. * Menu:
  661. * Toolbox introduction::
  662. * I/O redirection::
  663. * The `who' command::
  664. * The `cut' command::
  665. * The `sort' command::
  666. * The `uniq' command::
  667. * Putting the tools together::
  668. File: textutils.info,  Node: Toolbox introduction,  Next: I/O redirection,  Up: Opening the software toolbox
  669. Toolbox introduction
  670. ====================
  671.    This month's column is only peripherally related to the GNU Project,
  672. in that it describes a number of the GNU tools on your Linux system and
  673. how they might be used.  What it's really about is the "Software Tools"
  674. philosophy of program development and usage.
  675.    The software tools philosophy was an important and integral concept
  676. in the initial design and development of Unix (of which Linux and GNU
  677. are essentially clones).  Unfortunately, in the modern day press of
  678. Internetworking and flashy GUIs, it seems to have fallen by the
  679. wayside.  This is a shame, since it provides a powerful mental model
  680. for solving many kinds of problems.
  681.    Many people carry a Swiss Army knife around in their pants pockets
  682. (or purse).  A Swiss Army knife is a handy tool to have: it has several
  683. knife blades, a screwdriver, tweezers, toothpick, nail file, corkscrew,
  684. and perhaps a number of other things on it.  For the everyday, small
  685. miscellaneous jobs where you need a simple, general purpose tool, it's
  686. just the thing.
  687.    On the other hand, an experienced carpenter doesn't build a house
  688. using a Swiss Army knife.  Instead, he has a toolbox chock full of
  689. specialized tools--a saw, a hammer, a screwdriver, a plane, and so on.
  690. And he knows exactly when and where to use each tool; you won't catch
  691. him hammering nails with the handle of his screwdriver.
  692.    The Unix developers at Bell Labs were all professional programmers
  693. and trained computer scientists.  They had found that while a
  694. one-size-fits-all program might appeal to a user because there's only
  695. one program to use, in practice such programs are
  696.   a. difficult to write,
  697.   b. difficult to maintain and debug, and
  698.   c. difficult to extend to meet new situations.
  699.    Instead, they felt that programs should be specialized tools.  In
  700. short, each program "should do one thing well."  No more and no less.
  701. Such programs are simpler to design, write, and get right--they only do
  702. one thing.
  703.    Furthermore, they found that with the right machinery for hooking
  704. programs together, that the whole was greater than the sum of the
  705. parts.  By combining several special purpose programs, you could
  706. accomplish a specific task that none of the programs was designed for,
  707. and accomplish it much more quickly and easily than if you had to write
  708. a special purpose program.  We will see some (classic) examples of this
  709. further on in the column.  (An important additional point was that, if
  710. necessary, take a detour and build any software tools you may need
  711. first, if you don't already have something appropriate in the toolbox.)
  712. File: textutils.info,  Node: I/O redirection,  Next: The `who' command,  Prev: Toolbox introduction,  Up: Opening the software toolbox
  713. I/O redirection
  714. ===============
  715.    Hopefully, you are familiar with the basics of I/O redirection in the
  716. shell, in particular the concepts of "standard input," "standard
  717. output," and "standard error".  Briefly, "standard input" is a data
  718. source, where data comes from.  A program should not need to either
  719. know or care if the data source is a disk file, a keyboard, a magnetic
  720. tape, or even a punched card reader.  Similarly, "standard output" is a
  721. data sink, where data goes to.  The program should neither know nor
  722. care where this might be.  Programs that only read their standard
  723. input, do something to the data, and then send it on, are called
  724. "filters", by analogy to filters in a water pipeline.
  725.    With the Unix shell, it's very easy to set up data pipelines:
  726.      program_to_create_data | filter1 | .... | filterN > final.pretty.data
  727.    We start out by creating the raw data; each filter applies some
  728. successive transformation to the data, until by the time it comes out
  729. of the pipeline, it is in the desired form.
  730.    This is fine and good for standard input and standard output.  Where
  731. does the standard error come in to play?  Well, think about `filter1' in
  732. the pipeline above.  What happens if it encounters an error in the data
  733. it sees?  If it writes an error message to standard output, it will just
  734. disappear down the pipeline into `filter2''s input, and the user will
  735. probably never see it.  So programs need a place where they can send
  736. error messages so that the user will notice them.  This is standard
  737. error, and it is usually connected to your console or window, even if
  738. you have redirected standard output of your program away from your
  739. screen.
  740.    For filter programs to work together, the format of the data has to
  741. be agreed upon.  The most straightforward and easiest format to use is
  742. simply lines of text.  Unix data files are generally just streams of
  743. bytes, with lines delimited by the ASCII LF (Line Feed) character,
  744. conventionally called a "newline" in the Unix literature. (This is
  745. `'\n'' if you're a C programmer.)  This is the format used by all the
  746. traditional filtering programs.  (Many earlier operating systems had
  747. elaborate facilities and special purpose programs for managing binary
  748. data.  Unix has always shied away from such things, under the
  749. philosophy that it's easiest to simply be able to view and edit your
  750. data with a text editor.)
  751.    OK, enough introduction. Let's take a look at some of the tools, and
  752. then we'll see how to hook them together in interesting ways.   In the
  753. following discussion, we will only present those command line options
  754. that interest us.  As you should always do, double check your system
  755. documentation for the full story.
  756. File: textutils.info,  Node: The `who' command,  Next: The `cut' command,  Prev: I/O redirection,  Up: Opening the software toolbox
  757. The `who' command
  758. =================
  759.    The first program is the `who' command.  By itself, it generates a
  760. list of the users who are currently logged in.  Although I'm writing
  761. this on a single-user system, we'll pretend that several people are
  762. logged in:
  763.      $ who
  764.      arnold   console Jan 22 19:57
  765.      miriam   ttyp0   Jan 23 14:19(:0.0)
  766.      bill     ttyp1   Jan 21 09:32(:0.0)
  767.      arnold   ttyp2   Jan 23 20:48(:0.0)
  768.    Here, the `$' is the usual shell prompt, at which I typed `who'.
  769. There are three people logged in, and I am logged in twice.  On
  770. traditional Unix systems, user names are never more than eight
  771. characters long.  This little bit of trivia will be useful later.  The
  772. output of `who' is nice, but the data is not all that exciting.
  773. File: textutils.info,  Node: The `cut' command,  Next: The `sort' command,  Prev: The `who' command,  Up: Opening the software toolbox
  774. The `cut' command
  775. =================
  776.    The next program we'll look at is the `cut' command.  This program
  777. cuts out columns or fields of input data.  For example, we can tell it
  778. to print just the login name and full name from the `/etc/passwd file'.
  779. The `/etc/passwd' file has seven fields, separated by colons:
  780.      arnold:xyzzy:2076:10:Arnold D. Robbins:/home/arnold:/bin/ksh
  781.    To get the first and fifth fields, we would use cut like this:
  782.      $ cut -d: -f1,5 /etc/passwd
  783.      root:Operator
  784.      ...
  785.      arnold:Arnold D. Robbins
  786.      miriam:Miriam A. Robbins
  787.      ...
  788.    With the `-c' option, `cut' will cut out specific characters (i.e.,
  789. columns) in the input lines.  This command looks like it might be
  790. useful for data filtering.
  791. File: textutils.info,  Node: The `sort' command,  Next: The `uniq' command,  Prev: The `cut' command,  Up: Opening the software toolbox
  792. The `sort' command
  793. ==================
  794.    Next we'll look at the `sort' command.  This is one of the most
  795. powerful commands on a Unix-style system; one that you will often find
  796. yourself using when setting up fancy data plumbing. The `sort' command
  797. reads and sorts each file named on the command line.  It then merges
  798. the sorted data and writes it to standard output.  It will read
  799. standard input if no files are given on the command line (thus making
  800. it into a filter).  The sort is based on the machine collating sequence
  801. (ASCII) or based on  user-supplied ordering criteria.
  802. File: textutils.info,  Node: The `uniq' command,  Next: Putting the tools together,  Prev: The `sort' command,  Up: Opening the software toolbox
  803. The `uniq' command
  804. ==================
  805.    Finally (at least for now), we'll look at the `uniq' program.  When
  806. sorting data, you will often end up with duplicate lines, lines that
  807. are identical.  Usually, all you need is one instance of each line.
  808. This is where `uniq' comes in. The `uniq' program reads its standard
  809. input, which it expects to be sorted.  It only prints out one copy of
  810. each duplicated line.  It does have several options.  Later on, we'll
  811. use the `-c' option, which prints each unique line, preceded by a count
  812. of the number of times that line occurred in the input.
  813.