GREP(1)                                                   GREP(1)



NAME

       grep, egrep, fgrep - print lines matching a pattern


SYNOPSIS

       grep  [-[ABC] NUM] [-EFGHLUVZabchilnqrsuvwxyz] [-e PATTERN
       | -f FILE] [-d ACTION] [--directories=ACTION] [--extended-
       regexp]  [--fixed-strings] [--basic-regexp] [--regexp=PAT­
       TERN]   [--file=FILE]   [--ignore-case]    [--word-regexp]
       [--line-regexp] [--line-regexp] [--no-messages] [--invert-
       match] [--version] [--help]  [--byte-offset]  [--line-num­
       ber]     [--with-filename]    [--no-filename]    [--quiet]
       [--silent] [--text] [--files-without-match] [--files-with-
       matches]  [--count]  [--before-context=NUM]  [--after-con­
       text=NUM] [--context[=NUM]]  [--binary]  [--unix-byte-off­
       sets] [--mmap] [--null] [--recursive] [file...]


DESCRIPTION

       Grep  searches the named input files (or standard input if
       no files are named, or the file name - is given) for lines
       containing a match to the given pattern.  By default, grep
       prints the matching lines.

       There are three major variants of grep, controlled by  the
       following options.
       -G, --basic-regexp
              Interpret  pattern  as  a  basic regular expression
              (see below).  This is the default.
       -E, --extended-regexp
              Interpret pattern as an extended regular expression
              (see below).
       -F, --fixed-strings
              Interpret pattern as a list of fixed strings, sepa­
              rated by newlines, any of which is to be matched.
       In addition, two variant  programs  egrep  and  fgrep  are
       available.   Egrep  is  the same as grep -E.  Fgrep is the
       same as grep -F.

       All variants of grep understand the following options:
       -A NUM, --after-context=NUM
              Print NUM lines of trailing context after  matching
              lines.
       -B NUM, --before-context=NUM
              Print  NUM lines of leading context before matching
              lines.
       -C [NUM], --context[=NUM]
              Print NUM lines (default 2) of output context.
       -NUM   Same as --context=NUM lines of leading and trailing
              context.   However, grep will never print any given
              line more than once.
       -V, --version
              Print the version number of grep to standard error.
              This  version  number should be included in all bug
              reports (see below).




GNU Project                 1999/10/12                          1





GREP(1)                                                   GREP(1)


       -b, --byte-offset
              Print the byte offset within the input file  before
              each line of output.
       -c, --count
              Suppress  normal  output;  instead print a count of
              matching lines for each input file.  With  the  -v,
              --invert-match option (see below), count non-match­
              ing lines.
       -d ACTION, --directories=ACTION
              If an input file is a directory, use ACTION to pro­
              cess  it.   By default, ACTION is read, which means
              that directories are read  just  as  if  they  were
              ordinary files.  If ACTION is skip, directories are
              silently skipped.  If ACTION is recurse, grep reads
              all  files  under each directory, recursively; this
              is equivalent to the -r option.
       -e PATTERN, --regexp=PATTERN
              Use PATTERN as the pattern; useful to protect  pat­
              terns beginning with -.
       -f FILE, --file=FILE
              Obtain patterns from FILE, one per line.  The empty
              file contains zero patterns, and  therfore  matches
              nothing.
       -H, --with-filename
              Print the filename for each match.
       -h, --no-filename
              Suppress  the prefixing of filenames on output when
              multiple files are searched.
       -i, --ignore-case
              Ignore case distinctions in both  the  pattern  and
              the input files.
       -L, --files-without-match
              Suppress  normal  output; instead print the name of
              each input file from which no output would normally
              have  been  printed.  The scanning will stop on the
              first match.
       -l, --files-with-matches
              Suppress normal output; instead print the  name  of
              each  input  file  from which output would normally
              have been printed.  The scanning will stop  on  the
              first match.
       -n, --line-number
              Prefix  each  line  of  output with the line number
              within its input file.
       -q, --quiet, --silent
              Quiet; suppress normal output.  The  scanning  will
              stop  on the first match.  Also see the -s or --no-
              messages option below.
       -r, --recursive
              Read all files under each  directory,  recursively;
              this is equivalent to the -d recurse option.
       -s, --no-messages
              Suppress   error   messages  about  nonexistent  or
              unreadable files.   Portability  note:  unlike  GNU



GNU Project                 1999/10/12                          2





GREP(1)                                                   GREP(1)


              grep,  traditional grep did not conform to POSIX.2,
              because traditional grep lacked a -q option and its
              -s option behaved like GNU grep's -q option.  Shell
              scripts intended to be portable to traditional grep
              should  avoid  both  -q  and -s and should redirect
              output to /dev/null instead.
       -a, --text
              Do not suppress output lines  that  contain  binary
              data.   Normally,  if the first few bytes of a file
              indicate that the file contains binary  data,  grep
              outputs only a message saying that the file matches
              the pattern.  This option causes grep to act as  if
              the file is a text file, even if it would otherwise
              be treated as binary.
       -v, --invert-match
              Invert the sense of matching, to select  non-match­
              ing lines.
       -w, --word-regexp
              Select  only  those  lines  containing matches that
              form whole words.  The test is  that  the  matching
              substring  must  either  be at the beginning of the
              line, or preceded by a non-word constituent charac­
              ter.   Similarly,  it  must be either at the end of
              the line or  followed  by  a  non-word  constituent
              character.   Word-constituent  characters  are let­
              ters, digits, and the underscore.
       -x, --line-regexp
              Select only those matches that  exactly  match  the
              whole line.
       -y     Obsolete synonym for -i.
       -U, --binary
              Treat the file(s) as binary.  By default, under MS-
              DOS and MS-Windows, grep guesses the file  type  by
              looking at the contents of the first 32KB read from
              the file.  If grep decides the file is a text file,
              it  strips the CR characters from the original file
              contents (to make regular expressions with ^ and  $
              work  correctly).   Specifying  -U  overrules  this
              guesswork, causing all files to be read and  passed
              to  the matching mechanism verbatim; if the file is
              a text file with CR/LF pairs at  the  end  of  each
              line,  this  will cause some regular expressions to
              fail.  This option has no effect on platforms other
              than MS-DOS and MS-Windows.
       -u, --unix-byte-offsets
              Report Unix-style byte offsets.  This switch causes
              grep to report byte offsets as  if  the  file  were
              Unix-style  text  file,  i.e.  with  CR  characters
              stripped off.  This will produce results  identical
              to running grep on a Unix machine.  This option has
              no effect unless -b option is also used; it has  no
              effect  on  platforms other than MS-DOS and MS-Win­
              dows.
       --mmap If possible, use the mmap(2) system  call  to  read



GNU Project                 1999/10/12                          3





GREP(1)                                                   GREP(1)


              input,  instead of the default read(2) system call.
              In some situations, --mmap  yields  better  perfor­
              mance.   However, --mmap can cause undefined behav­
              ior (including core dumps) if an input file shrinks
              while grep is operating, or if an I/O error occurs.
       -Z, --null
              Output  a  zero  byte  (the  ASCII  NUL  character)
              instead  of  the  character that normally follows a
              file name.  For example, grep -lZ  outputs  a  zero
              byte after each file name instead of the usual new­
              line.  This option makes  the  output  unambiguous,
              even  in  the  presence  of  file  names containing
              unusual characters like newlines.  This option  can
              be  used  with commands like find -print0, perl -0,
              sort -z, and xargs -0  to  process  arbitrary  file
              names,  even those that contain newline characters.


REGULAR EXPRESSIONS

       A regular expression is a pattern that describes a set  of
       strings.   Regular expressions are constructed analogously
       to arithmetic expressions, by using various  operators  to
       combine smaller expressions.

       Grep understands two different versions of regular expres­
       sion syntax: "basic" and "extended."  In  GNU grep,  there
       is  no  difference in available functionality using either
       syntax.  In other implementations, basic  regular  expres­
       sions   are  less  powerful.   The  following  description
       applies to extended regular expressions;  differences  for
       basic regular expressions are summarized afterwards.

       The  fundamental  building  blocks are the regular expres­
       sions that match a  single  character.   Most  characters,
       including  all letters and digits, are regular expressions
       that match themselves.   Any  metacharacter  with  special
       meaning may be quoted by preceding it with a backslash.

       A  list of characters enclosed by [ and ] matches any sin­
       gle character in that list; if the first character of  the
       list  is  the caret ^ then it matches any character not in
       the   list.    For   example,   the   regular   expression
       [0123456789]  matches  any single digit.  A range of ASCII
       characters may be specified by giving the first  and  last
       characters, separated by a hyphen.  Finally, certain named
       classes of characters are  predefined.   Their  names  are
       self  explanatory,  and  they  are  [:alnum:],  [:alpha:],
       [:cntrl:],  [:digit:],  [:graph:],  [:lower:],  [:print:],
       [:punct:],  [:space:],  [:upper:],  and  [:xdigit:].   For
       example, [[:alnum:]] means [0-9A-Za-z], except the  latter
       form  is  dependent  upon  the  ASCII  character encoding,
       whereas the former is portable.  (Note that  the  brackets
       in  these  class names are part of the symbolic names, and
       must be included in addition to  the  brackets  delimiting
       the bracket list.)  Most metacharacters lose their special



GNU Project                 1999/10/12                          4





GREP(1)                                                   GREP(1)


       meaning inside lists.  To include a  literal  ]  place  it
       first  in  the  list.   Similarly,  to include a literal ^
       place it anywhere but first.  Finally, to include  a  lit­
       eral - place it last.

       The period .  matches any single character.  The symbol \w
       is a synonym for [[:alnum:]]  and  \W  is  a  synonym  for
       [^[:alnum]].

       The  caret ^ and the dollar sign $ are metacharacters that
       respectively match the empty string at the  beginning  and
       end  of  a line.  The symbols \< and \> respectively match
       the empty string at the beginning and end of a word.   The
       symbol  \b matches the empty string at the edge of a word,
       and \B matches the empty string provided it's not  at  the
       edge of a word.

       A  regular  expression  may  be followed by one of several
       repetition operators:
       ?      The preceding item is optional and matched at  most
              once.
       *      The  preceding  item  will  be matched zero or more
              times.
       +      The preceding item will  be  matched  one  or  more
              times.
       {n}    The preceding item is matched exactly n times.
       {n,}   The preceding item is matched n or more times.
       {n,m}  The preceding item is matched at least n times, but
              not more than m times.

       Two regular expressions may be concatenated; the resulting
       regular  expression  matches any string formed by concate­
       nating two substrings that respectively match the concate­
       nated subexpressions.

       Two  regular expressions may be joined by the infix opera­
       tor |; the resulting regular expression matches any string
       matching either subexpression.

       Repetition  takes  precedence over concatenation, which in
       turn takes precedence over alternation.   A  whole  subex­
       pression  may be enclosed in parentheses to override these
       precedence rules.

       The backreference \n, where n is a single  digit,  matches
       the  substring previously matched by the nth parenthesized
       subexpression of the regular expression.

       In basic regular expressions the metacharacters ?,  +,  {,
       |,  (,  and  ) lose their special meaning; instead use the
       backslashed versions \?, \+, \{, \|, \(, and \).

       Traditional egrep did not support the { metacharacter, and
       some egrep implementations support \{ instead, so portable



GNU Project                 1999/10/12                          5





GREP(1)                                                   GREP(1)


       scripts should avoid { in egrep patterns  and  should  use
       [{] to match a literal {.

       GNU  egrep attempts to support traditional usage by assum­
       ing that { is not special if it would be the start  of  an
       invalid  interval  specification.   For example, the shell
       command egrep '{1' searches for the  two-character  string
       {1  instead  of  reporting  a  syntax error in the regular
       expression.  POSIX.2 allows this behavior as an extension,
       but portable scripts should avoid it.


DIAGNOSTICS

       Normally, exit status is 0 if matches were found, and 1 if
       no matches were found.  (The -v option inverts  the  sense
       of  the exit status.)  Exit status is 2 if there were syn­
       tax errors in the pattern, inaccessible  input  files,  or
       other system errors.


BUGS

       Email  bug  reports  to bug-gnu-utils@gnu.org.  Be sure to
       include the word "grep" somewhere in the "Subject:" field.

       Large  repetition  counts in the {m,n} construct may cause
       grep to use lots of memory.  In  addition,  certain  other
       obscure  regular  expressions require exponential time and
       space, and may cause grep to run out of memory.

       Backreferences are very slow, and may require  exponential
       time.




























GNU Project                 1999/10/12                          6



Man(1) output converted with man2html