home *** CD-ROM | disk | FTP | other *** search
/ The Developer Connection…ice Driver Kit for OS/2 3 / DEV3-D1.ISO / prodtool / util2 / grep.doc < prev    next >
Encoding:
Text File  |  1993-11-17  |  8.3 KB  |  213 lines
  1.                      grep.doc : The 'grep' command
  2.                            By: Brian E. Yoder
  3.                                 11/11/91
  4.                                 11/17/93
  5.  
  6. The grep (get regular expression and print) command is an adaptation of
  7. the AIX grep command.  It searches one or more files for a pattern.
  8.  
  9. ========================================================================
  10. Usage
  11. ========================================================================
  12.  
  13.         grep [-flags] "pattern" [fspec ...]
  14.  
  15. The grep command searches for the specified pattern.  It writes each
  16. line that contains the pattern to standard output.  The pattern is a
  17. regular expression as described later in this document.
  18.  
  19. One or more file specifications may be present on the command line.  If
  20. no file specifications are present, then grep reads lines from standard
  21. input.
  22.  
  23. A file specification consists of an optional drive, optional path
  24. information, and a filename.  The filename may consist of AIX shell
  25. pattern-matching characters.  See pattern.doc for more details.
  26.  
  27. The flags that are supported are a subset of those supported by AIX:
  28.  
  29.      c  Display only a count of matching lines.
  30.  
  31.      i  Ignore case when making comparisons.
  32.  
  33.      l  List just the names of files (once) with matching lines.  Each
  34.         file name is separated by a new-line character.
  35.  
  36.      n  Preceed each line with the file name and line number, in the
  37.         following form:  fname(line)
  38.  
  39.      s  Descend subdirectories, also.
  40.  
  41.      v  Display lines that don't contain the pattern.
  42.  
  43.      y  Ignore case when making comparisons (compatible with RS/6000).
  44.  
  45. ========================================================================
  46. Notes
  47. ========================================================================
  48.  
  49. Lines are limited to a length of 512 characters. Longer lines are split
  50. in pieces of 512 characters or less.
  51.  
  52. Binary files can be searched; nulls, end-of-text (0x1a) characters, and
  53. non-ASCII characters are treated as newlines. When searching binary
  54. files, the line number won't mean much but strings less than 512
  55. characters long will tend to be kept together.
  56.  
  57. A dot within a filename is treated as just another character and not
  58. assumed to be the beginning of a file extension.  Therefore, you should
  59. specify * instead of *.* when searching all files in a specific
  60. directory.  Again, see pattern.doc or the AIX shell documentation for
  61. more information.
  62.  
  63. Errors are listed on standard error.
  64.  
  65. Lines from the input file are written to standard output as follows:
  66.  
  67.         filename : text from line
  68.  
  69. If the -n flag is specified, then lines from the input file are written:
  70.  
  71.         filename(line_number) : text from line
  72.  
  73. For the DOS and OS/2 versions of grep, the flags are case-insensitive.
  74.  
  75. The grep program can search binary files as well as text files. To help
  76. keep strings together, grep treats nulls and some ASCII control
  77. characters (that aren't normally present in flat text files) as newline
  78. characters. For binary files, the -n flag won't yield a meaningful line
  79. count. For text files that contain nulls and these control characters,
  80. the -n flag won't yield the correct line count. But then again, fgets()
  81. would not have been able to read past a null character anyway. It's a
  82. compromise. See the lgets() function in lbuf.c for more details.
  83.  
  84. ========================================================================
  85. Regular Expressions
  86. ========================================================================
  87.  
  88. The following expressions match a single character:
  89.  
  90.         c          Any ordinary character, other than one of the special
  91.                    pattern-matching characters, matches itself.
  92.  
  93.         .          A . (period) matches any single character.
  94.  
  95.         [string]   A string enclosed in square brackets matches any one
  96.                    character in the string.
  97.  
  98.         [.-.]      A range is two characters separated by a dash and
  99.                    enclosed in square brackets.  It matches any
  100.                    character that is within the range.
  101.  
  102.         [^string]  A string (or range) enclosed in square brackets and
  103.                    preceeded by a ^ (circumflex) matches any character
  104.                    except for the characters in the string (or range).
  105.  
  106.                    Strings and ranges may be combined as needed, as in:
  107.                    [a-m0-9xyz], which matches a thru m, 0 thru 9, x, y,
  108.                    or z.
  109.  
  110.         \c         The \ (backslash) followed by any character matches
  111.                    that character.  This is useful for matching the
  112.                    following special characters:  . * [ ] { } ^ $ \
  113.  
  114. The single-character expressions can be combined into regular
  115. expressions as follows:
  116.  
  117.         *          Match zero or more occurences of the previous
  118.                    character.
  119.  
  120.         {m}        Matches exactly m occurrences of the previous
  121.                    character.
  122.  
  123.         {m,}       Matches at least m occurrences of the previous
  124.                    character.
  125.  
  126.         {m,n}      Matches at least m but no more than n occurrences of
  127.                    the previous character.
  128.  
  129.                    m and n must be integers from 0 to 255, inclusive.
  130.  
  131. A regular expression can be restricted to match a string that begins on
  132. the first character of the line, ends on the last character of the line,
  133. or both, as follows:
  134.  
  135.         ^pattern   The pattern matches a string that begins on the first
  136.                    character of a line.
  137.  
  138.         pattern$   The pattern matches a string that ends on the last
  139.                    character of a line.
  140.  
  141.         ^pattern$  The pattern matches an entire line.
  142.  
  143.  
  144. ========================================================================
  145. Examples
  146. ========================================================================
  147.  
  148. grep "the cat" *.txt \*.bat
  149.  
  150.         This command searches the files in the current directory that
  151.         end in .txt and the .bat files in the root directory for the
  152.         string "the cat".  Only exact case matches are listed on
  153.         standard output:  occurrences of "The cat" and "the Cat" are not
  154.         listed.
  155.  
  156.  
  157. grep -i "the cat" *.txt \*.bat
  158.  
  159.         This command is similar to the previous one except that it
  160.         performs a case-insensitive search.  Occurrences of "The cat"
  161.         and "the CAT" would be listed in addition to any occurrences of
  162.         "the cat".
  163.  
  164.  
  165. grep -sn "the {1,}cat" *.txt
  166.  
  167.         This command searches all .txt files in the current directory
  168.         and in all subdirectories (recursively) for the pattern.  The
  169.         pattern consists of the word "the", followed by one or more
  170.         spaces, and followed by the word "cat".  Therefore, it would
  171.         match lines that contain "the   cat" or "the        cat".  The
  172.         filename(line number) string is prepended to each line of each
  173.         file in which the pattern is found.
  174.  
  175.  
  176. grep -i "[a-z][a-z0-9_]{0,}(" *.c
  177.  
  178.         This command searches all .c files in the current directory for
  179.         function prototypes and function declarations.  The pattern
  180.         matches any string that begins with a letter, is followed by
  181.         zero or more letters, numbers, or underscores, and ends with an
  182.         open parenthesis.
  183.  
  184.  
  185. t2bm -i <myfile.txt | grep "&cont\."
  186.  
  187.         This command searches the output of t2bm for the "&cont."
  188.         string.  Note that the period in the pattern was escaped with a
  189.         backslash.  The grep command would interpret the "&cont."
  190.         pattern as meaning the "&cont" string followed by any character.
  191.  
  192.  
  193. grep "^Usage$" *.doc
  194.  
  195.         This command searches all .doc files in the current directory
  196.         for lines that consist of nothing but the string "Usage".
  197.  
  198.  
  199. grep "streams\[" *.c
  200.  
  201.         This command searches all C files in the current directory for
  202.         lines that contain the "streams[" string.  Note that the "["
  203.         character has to be escaped in the pattern so that it is
  204.         interpreted by grep as a bracket and not as the beginning of a
  205.         set or range.
  206.  
  207.  
  208. grep -v "^$" *.doc
  209.  
  210.         This command searches all .doc files in the current directory
  211.         and lists all lines that are not blank.  Note that the ^$
  212.         pattern matches any blank line.
  213.