path: root/gnu/usr.bin/grep/doc/grep.texi

\input texinfo  @c -*-texinfo-*-
@c %**start of header
@setfilename grep.info
@settitle grep, print lines matching a pattern
@c %**end of header

@c This file has the new style title page commands.
@c Run `makeinfo' rather than `texinfo-format-buffer'.

@c smallbook

@c tex
@c \overfullrule=0pt
@c end tex

@include version.texi

@c Combine indices.
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex tp cp

@defcodeindex op
@syncodeindex op fn

@ifinfo
@direntry
* grep: (grep).                   print lines matching a pattern.
@end direntry
This file documents @sc{grep}, a pattern matching engine.


Published by the Free Software Foundation,
59 Temple Place - Suite 330
Boston, MA 02111-1307, USA

Copyright (C) 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.
@end ifinfo

@setchapternewpage off

@titlepage
@title grep, searching for a pattern
@subtitle version @value{VERSION}, @value{UPDATED}
@author Alain Magloire et al.

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998 Free Software Foundation, Inc.

@sp 2
Published by the Free Software Foundation, @*
59 Temple Place - Suite 330, @*
Boston, MA 02111-1307, USA

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation approved
by the Foundation.

@end titlepage
@page


@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up

@ifinfo
This document was produced for version @value{VERSION} of @sc{GNU} @sc{grep}.
@end ifinfo

@menu
* Introduction::                Introduction.
* Invoking::                    Invoking @sc{grep}; description of options.
* Diagnostics::                 Exit status returned by @sc{grep}.
* Grep Programs::               @sc{grep} programs.
* Regular Expressions::         Regular Expressions.
* Reporting Bugs::              Reporting Bugs.
* Concept Index::               A menu with all the topics in this manual.
* Index::                       A menu with all @sc{grep} commands
                                 and command-line options.
@end menu


@node Introduction,  Invoking, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

@cindex Searching for a pattern.
@sc{grep} searches the input files for lines containing a match to a given
pattern list.  When it finds a match in a line, it copies the line to standard
output (by default), or does whatever other sort of output you have requested
with options.  @sc{grep} expects to do the matching on text.
Since newline is also a separator for the list of patterns, there
is no way to match newline characters in a text.

@node Invoking, Diagnostics, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Invoking @sc{grep}

@sc{grep} comes with a rich set of options from POSIX.2 and GNU extensions.

@table @samp

@item -c
@itemx --count
@opindex -c
@opindex -count
@cindex counting lines
Suppress normal output; instead print a count of matching
lines for each input file.  With the @samp{-v}, @samp{--revert-match} option,
count non-matching lines.

@item -e @var{pattern}
@itemx --regexp=@var{pattern}
@opindex -e
@opindex --regexp=@var{pattern}
@cindex pattern list
Use @var{pattern} as the pattern; useful to protect  patterns
beginning with a @samp{-}.

@item  -f @var{file}
@itemx --file=@var{file}
@opindex  -f
@opindex  --file 
@cindex pattern from file
Obtain patterns from @var{file}, one  per  line.   The  empty
file contains zero patterns, and therefore matches nothing.

@item -i
@itemx --ignore-case
@opindex -i
@opindex --ignore-case
@cindex case insensitive search
Ignore case distinctions in both the  pattern  and  the input files.

@item -l
@itemx --files-with-matches
@opindex -l
@opindex --files-with-matches
@cindex names of matching files
Suppress normal output; instead print the name of  each input
file  from which output would normally have been printed.
The scanning of every file will stop on the first match.

@item -n
@itemx --line-number
@opindex -n
@opindex --line-number
@cindex line numbering
Prefix each line of output with the line number  within its input file.

@item -q
@itemx --quiet
@itemx --silent
@opindex -q
@opindex --quiet
@opindex --silent
@cindex quiet, silent
Quiet; suppress normal output.  The scanning of every file will  stop on
the first match.  Also see the @samp{-s} or @samp{--no-messages} option.

@item -s
@itemx --no-messages
@opindex -s
@opindex --no-messages
@cindex suppress error messages
Suppress error messages about nonexistent or unreadable files.
Portability  note:  unlike  GNU @sc{grep}, BSD @sc{grep} does not comply
with POSIX.2, because BSD @sc{grep} lacks a @samp{-q}  option and its
@samp{-s} option behaves like GNU @sc{grep}'s @samp{-q} option.  Shell
scripts intended to be portable to BSD @sc{grep} should avoid both
@samp{-q} and @samp{-s} and should redirect
output to @file{/dev/null} instead.

@item -v
@itemx --revert-match
@opindex -v
@opindex --revert-match
@cindex revert matching
@cindex print non-matching lines
Invert the sense of matching,  to  select  non-matching lines.

@item -x
@itemx --line-regexp
@opindex -x
@opindex --line-regexp
@cindex match the whole line
Select only those matches that exactly match the  whole line.

@end table

@section GNU Extensions

@table @samp

@item -A @var{num}
@itemx --after-context=@var{num}
@opindex -A
@opindex --after-context
@cindex after context
@cindex context lines, after match
Print @var{num} lines of trailing context after matching lines.

@item -B @var{num}
@itemx --before-context=@var{num}
@opindex -B
@opindex --before-context
@cindex before context
@cindex context lines, before match
Print @var{num} lines of leading context before matching lines.

@item -C
@itemx --context@var{[=num]}
@opindex -C
@opindex --context
@cindex context
Print @var{num} lines (default 2) of output context.


@item -NUM
@opindex -NUM
Same as @samp{--context=@var{num}} lines  of  leading  and  trailing
context.  However, grep will never print any given line more than once.


@item -V
@itemx --version
@opindex -V
@opindex --version
@cindex Version, printing
Print the version number of @sc{grep} to the standard output stream.
This  version  number  should  be  included  in all bug reports.

@item --help
@opindex --help
@cindex Usage summary, printing
Print a usage message briefly summarizing these command-line options
and the bug-reporting address, then exit.

@item -b
@itemx --byte-offset
@opindex -b
@opindex --byte-offset
@cindex byte offset
Print the byte offset within the input file before each line of output.
When @sc{grep} runs on MS-DOS or MS-Windows, the printed byte offsets
depend on whether the @samp{-u} (@samp{--unix-byte-offsets}) option is
used; see below.

@item -d @var{action}
@itemx --directories=@var{action}
@opindex -d 
@opindex --directories
@cindex directory search
If an input file is a directory, use @var{action} to  process it.
By  default, @var{action} is @samp{read}, which means that directories are
read just  as  if  they  were  ordinary files (some operating systems
and filesystems disallow this, and will cause @sc{grep} to print error
messages for every directory).  If @var{action} is @samp{skip},
directories are silently skipped.  If @var{action} is @samp{recurse},
@sc{grep} reads all files under each directory, recursively; this is
equivalent to the @samp{-r} option.

@item -h
@itemx --no-filename
@opindex -h
@opindex --no-filename
@cindex no filename prefix
Suppress the prefixing of filenames on output when multiple files are searched.

@item -L
@itemx --files-without-match
@opindex -L
@opindex --files-without-match
@cindex files which don't match
Suppress normal output; instead print the name of  each input
file  from  which  no output would normally have been printed.
The  scanning of every file will  stop  on  the  first match.

@item -a
@itemx --text
@opindex -a
@opindex --text
@cindex suppress binary data
@cindex binary files
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.
@emph{Warning:}  the  result  might  be  binary garbage
printed  to  the  terminal,  which  can  have  nasty
side-effects if the terminal driver interprets some of
it as commands.

@item -w
@itemx --word-regexp
@opindex -w
@opindex --word-regexp
@cindex matching whole words
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 character.  Similarly,
it must be either at the end of the line or followed by
a  non-word  constituent  character.   Word-constituent
characters are letters, digits, and the underscore.

@item -r
@itemx --recursive
@opindex -r
@opindex --recursive
@cindex recursive search
@cindex searching directory trees
For each directory mentioned in the command line, read and process all
files in that directory, recursively.  This is the same as the @samp{-d
recurse} option.

@item -y
@opindex -y
@cindex case insensitive search, obsolete option
Obsolete synonym for @samp{-i}.

@item -U
@itemx --binary
@opindex -U
@opindex --binary
@cindex DOS/Windows binary files
@cindex binary files, DOS/Windows
Treat the file(s) as binary.  By default, under  MS-DOS
and  MS-Windows, @sc{grep} guesses the file type by looking
at the contents of the first 32KB read from  the  file.
If @sc{grep} decides the file is a text file, it strips the
CR characters from the original file contents (to  make
regular  expressions  with  @code{^} and @code{$} work correctly).
Specifying @samp{-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 is only supported  on
MS-DOS and MS-Windows.

@item -u
@itemx --unix-byte-offsets
@opindex -u
@opindex --unix-byte-offsets
@cindex DOS byte offsets
@cindex byte offsets, on DOS/Windows
Report Unix-style byte  offsets.   This  switch  causes
@sc{grep} to report byte offsets as if the file were Unix style
text file, i.e. the byte offsets ignore the CR characters which were
stripped  off.  This  will produce results identical to running @sc{grep} on
a Unix machine.  This option has no  effect  unless  @samp{-b}
option is also used; it is only supported on MS-DOS and
MS-Windows.

@end table

Several additional options control which variant of the @sc{grep}
matching engine is used.  @xref{Grep Programs}.

@sc{grep} uses the environment variable @var{LANG} to
provide internationalization support, if compiled with this feature.

@node Diagnostics, Grep Programs, Invoking, Top
@comment  node-name,  next,  previous,  up
@chapter Diagnostics
Normally, exit status is 0 if matches were found, and 1 if no matches
were found (the @samp{-v} option inverts the sense of the exit status).
Exit status is 2  if  there  were  syntax errors  in  the  pattern,
inaccessible input files, or other system errors.

@node Grep Programs, Regular Expressions, Diagnostics, Top
@comment  node-name,  next,  previous,  up
@chapter @sc{grep} programs

@sc{grep} searches the named input files (or standard input if no
files are named, or the file name @file{-} is given) for lines containing
a match to the given pattern.  By default, @sc{grep} prints the matching lines.
There are three major variants of @sc{grep}, controlled by the following options.

@table @samp

@item -G
@itemx --basic-regexp
@opindex -G
@opindex --basic-regexp
@cindex matching basic regular expressions
Interpret pattern as a basic  regular  expression.  This is the default.

@item -E
@item --extended-regexp
@opindex -E
@opindex --extended-regexp
@cindex matching extended regular expressions
Interpret pattern as  an  extended  regular  expression.


@item -F
@itemx --fixed-strings
@opindex -F
@opindex --fixed-strings
@cindex matching fixed strings
Interpret pattern as a list of fixed strings, separated
by newlines, any of which is to be matched.

@end table

In addition, two variant programs @sc{egrep} and @sc{fgrep} are available.
@sc{egrep} is similar (but not identical) to @samp{grep -E}, and
is compatible with the historical Unix @sc{egrep}.  @sc{fgrep} is  the
same as @samp{grep -F}.

@node Regular Expressions, Reporting Bugs, Grep Programs, Top
@comment  node-name,  next,  previous,  up
@chapter Regular Expressions
@cindex regular expressions

A @dfn{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.
@sc{grep} understands two different versions of  regular  expression
syntax:   ``basic''  and  ``extended''.  In GNU @sc{grep}, there is no
difference  in  available  functionality  using either  syntax.
In  other  implementations,  basic regular expressions 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  expressions 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 @samp{[} and @samp{]} matches any
single character in that list; if the first character of the list is the
caret @samp{^}, then it 
matches any character @strong{not} in the list.  For example, the regular
expression @samp{[0123456789]} matches any single digit.
A range of @sc{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 :

@cindex classes of characters
@cindex character classes
@table @samp

@item [:alnum:]
@opindex alnum 
@cindex  alphanumeric characters
Any of [:digit:] or [:alpha:]

@item [:alpha:]
@opindex alpha
@cindex alphabetic characters
Any local-specific or one of the @sc{ascii} letters:@*
@code{a b c d e f g h i j k l m n o p q r s t u v w x y z},@*
@code{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}.

@item [:cntrl:]
@opindex cntrl
@cindex control characters
Any of @code{BEL}, @code{BS}, @code{CR}, @code{FF}, @code{HT},
@code{NL}, or @code{VT}.

@item [:digit:]
@opindex digit
@cindex digit characters
@cindex numeric characters
Any one of @code{0 1 2 3 4 5 6 7 8 9}.

@item [:graph:]
@opindex graph
@cindex graphic characters
Anything that is not a @samp{[:alphanum:]} or @samp{[:punct:]}.

@item [:lower:]
@opindex lower
@cindex lower-case alphabetic characters
Any one of @code{a b c d e f g h i j k l m n o p q r s t u v w x y z}.

@item [:print:]
@opindex print
@cindex printable characters
Any character from the @samp{[:space:]} class, and any character that is
@strong{not} in the @samp{[:isgraph:]} class.

@item [:punct:]
@opindex punct
@cindex punctuation characters
Any one of @code{!@: " #% & ' ( ) ; < = > ?@: [ \ ] * + , - .@: / : ^ _ @{ | @}}.


@item [:space:]
@opindex space
@cindex space characters
@cindex whitespace characters
Any one of @code{CR FF HT NL VT SPACE}.

@item [:upper:]
@opindex upper
@cindex upper-case alphabetic characters
Any one of @code{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}.

@item [:xdigit:]
@opindex xdigit
@cindex xdigit class
@cindex hexadecimal digits
Any one of @code{a b c d e f A B C D E F 0 1 2 3 4 5 6 7 8 9}.

@end table
For example, @samp{[[:alnum:]]} means @samp{[0-9A-Za-z]}, except the latter
form is dependent upon the @sc{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 meaning inside lists.  To include a literal @samp{]}, place it
first in the list.  Similarly, to include a literal @samp{^}, place it anywhere
but  first.  Finally, to include a literal @samp{-}, place it last.

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

The caret @samp{^} and the dollar sign @samp{$} are metacharacters that
respectively match the empty string at the beginning and end
of a line.  The symbols @samp{\<} and  @samp{\>} respectively match the
empty string at the beginning and end of a word.  The symbol
@samp{\b} matches the empty string at the edge of a  word,  and  @samp{\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:


@table @samp

@item ?
@opindex ?
@cindex question mark
@cindex match sub-expression at most once
The preceding item is optional and will be matched at most once.

@item *
@opindex *
@cindex asterisk
@cindex match sub-expression zero or more times
The preceding item will be matched zero or more times.

@item +
@opindex +
@cindex plus sign 
The preceding item will be matched one or more times.

@item @{@var{n}@}
@opindex @{n@}
@cindex braces, one argument
@cindex match sub-expression n times
The preceding item is matched exactly @var{n} times.

@item @{@var{n},@}
@opindex @{n,@}
@cindex braces, second argument omitted
@cindex match sub-expression n or more times
The preceding item is matched n or more times.

@item @{,@var{m}@}
@opindex @{,m@}
@cindex braces, first argument omitted
@cindex match sub-expression at most m times
The preceding item is optional and is matched at most @var{m} times.

@item @{@var{n},@var{m}@}
@opindex @{n,m@}
@cindex braces, two arguments
The preceding item is matched at least @var{n} times, but not more than
@var{m} times.

@end table

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

Two regular expressions may be joined by the infix  operator @samp{|}; the
resulting  regular  expression  matches  any string matching either
subexpression.

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

The backreference @samp{\@var{n}}, where @var{n} is a single digit, matches the
substring previously matched by the @var{n}th parenthesized subexpression
of the regular expression.

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

In @sc{egrep} the metacharacter  @samp{@{}  loses  its  special  meaning;
instead use @samp{\@{}.  This not true for @samp{grep -E}.


@node Reporting Bugs, Concept Index, Regular Expressions, Top
@comment  node-name,  next,  previous,  up
@chapter Reporting bugs

@cindex Bugs, reporting
Email bug reports to @email{bug-gnu-utils@@gnu.org}.
Be sure to include the word ``grep'' somewhere in the ``Subject:'' field.

Large repetition counts in the  @samp{@{m,n@}}  construct  may  cause
@sc{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.

@page
@node Concept Index , Index, Reporting Bugs, Top
@comment node-name,  next,  previous,  up
@unnumbered Concept Index

This is a general index of all issues discussed in this manual, with the
exception of the @sc{grep} commands and command-line options.

@printindex cp

@page
@node Index, , Concept Index, Top
@unnumbered Index

This is an alphabetical list of all @sc{grep} commands and command-line
options.

@printindex fn

@contents
@bye