FGREP.DOC

                                  fgrep 1.30
                                  ----------

        "|" denotes items that are new/changed in the current version.
        Note that previous versions were simply called "grep".

        Purpose
        -------

        Fgrep (Fast GREP) is a small utility that can be used to find
        specific strings of characters in ASCII text files.  String
        search capabilities are not extensive (no regular expressions),
        but fgrep is small and quite fast (on a standard PC equipped with
        a fairly slow fixed disk, fgrep can perform a case and spacing
        insensitive search of 24 files totalling over 1/4 megabyte
        of text in about 30 seconds).

        Use
        ---

        Fgrep's syntax is

   |            fgrep [-cfwse01] "string" [file]  ...

        The -switches are discussed below.

        The string must be delimited by a pair of characters.  Any pair
        is OK.  For example:

                /string/
                'string'
                $string$
                fred derf       [parsed as 'red der']

        The string may include one or more "?" wildcards.  The ? will
        match any single non-null character in the file.  E.g., "[?i]"
        will match "[si]", "[di]", etc., but not "[i]".

        The list of files may include wild cards.  Here are some
        examples of fgrep use:

                fgrep  -c  "include foo.c"  *.c
                fgrep /abcd?/ filea.ext fileb.ext filec.ext
                fgrep -1f 'call fido' a:\masm\*.asm  b:*.asm

   |    If no file is specified, input will be taken from standard
   |    input, allowing redirection and piping:
   |
   |            arc p somefile foo.txt | fgrep "string"
   |
   |    will display occurrences of "string" in the file archived as
   |    foo.txt in somefile.arc.


        Output
        ------

        Fgrep's screen output looks like this:

                **File <filename>
                [text of lines containing string]
                **File <filename>
                [text of lines containing string]

        All useful output is sent to the standard output device, so it
        may be piped to other programs or redirected to file:

                fgrep /string/ filea | yourprog
                fgrep /string/ filea > test.txt

        Error messages and the program logo will appear always appear on
        the console device, and will never appear in redirected or piped
        output.

   |    Fgrep always returns an errorlevel to the operating system.  It
   |    will be one of:
   |
   |        0:   String not found in any file
   |        1:   String found in at least one file
   |        255: Error (file read error, or bad parameter)


        Switches
        --------

        The -c switch makes the search case sensitive ("String" will not
        match "string" or "STRING").

        The -f switch causes the "**File" header lines to be displayed
        only for those files that contain the search string.

   |    The -w switch indicates that white space (blanks and tabs)
   |    is not significant.  White space in both the search string
   |    and the input file will be ignored.  If -w is specified, the
   |    wildcard character (?) will match any nonblank character.

        The -s switch suppresses the "**File" header lines in the
        output.

   |    The -0 switch ("0" text lines) suppresses the display of lines
   |    of text containing the specified string.  fgrep will skip
   |    immediately to the next file when the string is found.
   |
   |    The -1 switch ("1" text line) specifies that only the first line
   |    containing containing the specified string in each file will be
   |    displayed. fgrep will then skip immediately to the next file.
   |
   |    The -e switch specifies that ONLY an errorlevel is to be
   |    returned.  There will be no display at all.  This is equivalent
   |    to the combination -s0.


        Notes
        -----

        1. The -f and -s switches are mutually exclusive.  If both are
        specified, the last one will be effective.

   |    2. If you specify the -e switch, fgrep will stop processing as
   |    soon as a nonzero errorlevel is determined.  The -e switch is
   |    really designed to enable other programs to determine whether or
   |    not a specific file contains a specific string in as little time
   |    as possible.  For example, here's an algorithm that will quickly
   |    'touch' all files that do NOT contain a specified string:
   |
   |            for file in (*.*) do
   |                fgrep -e "string" file
   |                if errorlevel < 1 then touch file
   |            end
   |
   |    3. The -s switch is automatically set when input is taken from
   |    standard input.
   |
   |    4. fgrep optimizes the combination -s0 (suppress headers, no
   |    text) to a -e.
   |
   |    5. If you just want to know which files contain a string, use -0;
   |    it saves time because the rest of the file (after the first hit)
   |    is skipped.  The combination -0f is particularly efficient
   |    for this as it will simply display a list of files that contain
   |    the string.
   |
   |    6. The "listing" options have been removed as of version 1.3.  They
   |    had a negative effect on efficiency, and didn't seem to be
   |    enormously useful.


        Comments to Chris Dunford [CIS 76703,2002].  For personal use
        only.  Not for sale.