home *** CD-ROM | disk | FTP | other *** search
/ PC Online 1997 October / PCO1097.ISO / FilesBBS / FREI / UTLOS2.ARJ / UTLOS2.ZIP / Doc / grep.doc < prev    next >
Encoding:
Text File  |  1997-07-14  |  10.6 KB  |  274 lines
  1. $Id: grep.doc 1.5 1997/07/15 01:27:21 brian Exp $
  2.  
  3.                      grep.doc : The 'grep' command
  4.                            By: Brian E. Yoder
  5.  
  6.         (c) Copyright International Business Machines Corporation 1997
  7.         All rights reserved.
  8.  
  9. The grep (get regular expression and print) command is an adaptation of
  10. the Unix grep command. It searches one or more files for a pattern.
  11.  
  12. ========================================================================
  13. Usage
  14. ========================================================================
  15.  
  16.         grep [ -flags ] "pattern" [ fspec ... ]
  17.  
  18. The grep command searches for the specified pattern.  It writes each
  19. line that contains the pattern to standard output.  The pattern is a
  20. regular expression as described later in this document.
  21.  
  22. One or more file specifications may be present on the command line.  If
  23. no file specifications are present, then grep reads lines from standard
  24. input.
  25.  
  26. A file specification consists of an optional drive, optional path
  27. information, and a filename. The filename may consist of AIX shell
  28. pattern-matching characters. See pattern.doc for more details.
  29.  
  30. Binary files (such as *.obj and *.exe) can be searched in addition to
  31. text files.
  32.  
  33. The flags that are supported are a subset of those supported by the
  34. standard Unix or GNU grep:
  35.  
  36.     -c  Display only a count of matching lines.
  37.  
  38.     -i  Ignore case when making comparisons (same as -y).
  39.  
  40.     -l  List just the names of files (once) with matching lines.  Each
  41.         file name is separated by a new-line character.
  42.  
  43.     -n  Preceed each line with the file name and line number, in the
  44.         following default form:  fname(line)
  45.  
  46.     -0 through -9
  47.         If -n is also specified, then a specifying a digit will select a
  48.         pattern to use when showing the file name, line number, and
  49.         starting column. If no digit is specified, then 0 is assumed.
  50.  
  51.     -s  Descend subdirectories, also.
  52.  
  53.     -v  Display lines that don't contain the pattern.
  54.  
  55.     -y  Ignore case when making comparisons (compatible with RS/6000).
  56.  
  57. ========================================================================
  58. Showing the filename, line number, and column number
  59. ========================================================================
  60.  
  61. If the -n flag is specified, then a format pattern number may also be
  62. specified. If no pattern number is specified, then -0 is used as the
  63. default.
  64.  
  65. The grep program looks in the GREPn environment variable, where n is the
  66. pattern number. If there is no GREPn variable in the environment (for
  67. instance, if -n5 is specified but there is no GREP5 environment variable
  68. defined), then the "$n($l) : " pattern is assumed.
  69.  
  70. The characters from the formatting pattern defined by the environment
  71. variable are copied to the output and then the text from the line is
  72. added. If a dollar sign '$' meta character is encountered, then it and
  73. the next character are interpreted as follows:
  74.  
  75.         $n specifies the name of the file.
  76.         $l (letter el) specifies the line number within the file.
  77.         $c specifies the starting column within the line.
  78.         $$ specifies the dollar sign itself.
  79.         $" specifies a double quote character.
  80.  
  81. With the exception of $", double quotes within or surrounding a
  82. format pattern are ignored.
  83.  
  84. If no format pattern is found, the "$n($l) : " pattern is assumed. This
  85. causes the following information to be shown:
  86.  
  87.         filename(line_number) : text from line
  88.  
  89. Some useful format patterns that may be specified are:
  90.  
  91.         set GREP0="$n($l) : "
  92.         set GREP2="$n($l:$c) : "
  93.         set GREP1="$n:$l:"
  94.         set GREP3="$n/$l/$c "
  95.         set GREP4="$n,$l,$c "
  96.  
  97. When specified with the -n flag, they are used as follows:
  98.  
  99.         -n0 is the default that this package's grep has shown from the
  100.         beginning. It mimics the format of error messages from
  101.         many PC compilers: filename(linenumber). The GREP0 environment
  102.         variable can be changed to another pattern so that -n by itself
  103.         uses a different pattern.
  104.  
  105.         -n1 mimics the format of error messages from some modern C/C++
  106.         compilers that also include the column number:
  107.  
  108.                 filename(line:column)
  109.  
  110.         -n2 is the Unix and GNU grep's style: filename:linenumber:text
  111.  
  112.         -n3 and -n4 mimic the format that the UltraEdit32 editor uses to
  113.         allow you to select a filename, open it, and put the cursor at
  114.         the specified line and column within the file. UltraEdit is a
  115.         very capable shareware editor available from the www.idmcomp.com
  116.         Web site. It's a spectacular bargain with a shareware price of
  117.         only U.S. $30 but with capabilities, ease-of-use, and company
  118.         responsiveness far beyond that of most other editors at any
  119.         price.
  120.  
  121. ========================================================================
  122. Notes
  123. ========================================================================
  124.  
  125. Lines are limited to a length of 512 characters.  Longer lines are split
  126. in pieces of 512 characters or less.
  127.  
  128. A dot within a filename is treated as just another character and not
  129. assumed to be the beginning of a file extension. Therefore, you should
  130. specify * instead of *.* when searching all files in a specific
  131. directory. Again, see pattern.doc or the AIX shell documentation for
  132. more information.
  133.  
  134. Errors are listed on standard error.
  135.  
  136. Lines from the input file are written to standard output as follows:
  137.  
  138.         filename : text from line
  139.  
  140. If the -n flag is specified, then lines from the input file are written
  141. according to the pattern number specified. The default is as follows:
  142.  
  143.         filename(line_number) : text from line
  144.  
  145. ========================================================================
  146. Regular Expressions
  147. ========================================================================
  148.  
  149. The following expressions match a single character:
  150.  
  151.         c          Any ordinary character, other than one of the special
  152.                    pattern-matching characters, matches itself.
  153.  
  154.         .          A . (period) matches any single character.
  155.  
  156.         [string]   A string enclosed in square brackets matches any one
  157.                    character in the string.
  158.  
  159.         [.-.]      A range is two characters separated by a dash and
  160.                    enclosed in square brackets.  It matches any
  161.                    character that is within the range.
  162.  
  163.         [^string]  A string (or range) enclosed in square brackets and
  164.                    preceeded by a ^ (circumflex) matches any character
  165.                    except for the characters in the string (or range).
  166.  
  167.                    Strings and ranges may be combined as needed, as in:
  168.                    [a-m0-9xyz], which matches a thru m, 0 thru 9, x, y,
  169.                    or z.
  170.  
  171.         \c         The \ (backslash) followed by any character matches
  172.                    that character.  This is useful for matching the
  173.                    following special characters:  . * [ ] { } ^ $ \
  174.  
  175. The single-character expressions can be combined into regular
  176. expressions as follows:
  177.  
  178.         *          Match zero or more occurences of the previous
  179.                    character.
  180.  
  181.         {m}        Matches exactly m occurrences of the previous
  182.                    character.
  183.  
  184.         {m,}       Matches at least m occurrences of the previous
  185.                    character.
  186.  
  187.         {m,n}      Matches at least m but no more than n occurrences of
  188.                    the previous character.
  189.  
  190.                    m and n must be integers from 0 to 255, inclusive.
  191.  
  192. A regular expression can be restricted to match a string that begins on
  193. the first character of the line, ends on the last character of the line,
  194. or both, as follows:
  195.  
  196.         ^pattern   The pattern matches a string that begins on the first
  197.                    character of a line.
  198.  
  199.         pattern$   The pattern matches a string that ends on the last
  200.                    character of a line.
  201.  
  202.         ^pattern$  The pattern matches an entire line.
  203.  
  204.  
  205. ========================================================================
  206. Examples
  207. ========================================================================
  208.  
  209. grep "the cat" *.txt \*.bat
  210.  
  211.         This command searches the files in the current directory that
  212.         end in .txt and the .bat files in the root directory for the
  213.         string "the cat".  Only exact case matches are listed on
  214.         standard output:  occurrences of "The cat" and "the Cat" are not
  215.         listed.
  216.  
  217.  
  218. grep -i "the cat" *.txt \*.bat
  219.  
  220.         This command is similar to the previous one except that it
  221.         performs a case-insensitive search.  Occurrences of "The cat"
  222.         and "the CAT" would be listed in addition to any occurrences of
  223.         "the cat".
  224.  
  225.  
  226. grep -sn "the {1,}cat" *.txt
  227.  
  228.         This command searches all .txt files in the current directory
  229.         and in all subdirectories (recursively) for the pattern.  The
  230.         pattern consists of the word "the", followed by one or more
  231.         spaces, and followed by the word "cat".  Therefore, it would
  232.         match lines that contain "the   cat" or "the        cat".  The
  233.         filename(line number) string is prepended to each line of each
  234.         file in which the pattern is found.
  235.  
  236.  
  237. grep -i "[a-z][a-z0-9_]{0,}(" *.c
  238.  
  239.         This command searches all .c files in the current directory for
  240.         function prototypes and function declarations.  The pattern
  241.         matches any string that begins with a letter, is followed by
  242.         zero or more letters, numbers, or underscores, and ends with an
  243.         open parenthesis.
  244.  
  245.  
  246. t2bm -i <myfile.txt | grep "&cont\."
  247.  
  248.         This command searches the output of t2bm for the "&cont."
  249.         string.  Note that the period in the pattern was escaped with a
  250.         backslash.  The grep command would interpret the "&cont."
  251.         pattern as meaning the "&cont" string followed by any character.
  252.  
  253.  
  254. grep "^Usage$" *.doc
  255.  
  256.         This command searches all .doc files in the current directory
  257.         for lines that consist of nothing but the string "Usage".
  258.  
  259.  
  260. grep "streams\[" *.c
  261.  
  262.         This command searches all C files in the current directory for
  263.         lines that contain the "streams[" string.  Note that the "["
  264.         character has to be escaped in the pattern so that it is
  265.         interpreted by grep as a bracket and not as the beginning of a
  266.         set or range.
  267.  
  268.  
  269. grep -v "^$" *.doc
  270.  
  271.         This command searches all .doc files in the current directory
  272.         and lists all lines that are not blank.  Note that the ^$
  273.         pattern matches any blank line.
  274.