Virgin import of a trimmed down GNU Grep 2.3.

It is being re-imported here, to keep our long source change history with
this source continuous.
src/contrib/grep will be deleted some time in the very near future.

1 files changed, 449 insertions, 206 deletions

diff --git a/gnu/usr.bin/grep/grep.1 b/gnu/usr.bin/grep/grep.1
index 57093b6..3b957a0 100644
--- a/gnu/usr.bin/grep/grep.1
+++ b/gnu/usr.bin/grep/grep.1
@@ -1,234 +1,477 @@
-.TH GREP 1 "1988 December 13" "GNU Project" \" -*- nroff -*-
-.UC 4
+.\" grep man page
+.de Id
+.ds Dt \\$4
+..
+.Id $Id: grep.1,v 1.1 1998/11/22 06:45:20 alainm Exp $
+.TH GREP 1 \*(Dt "GNU Project"
 .SH NAME
-grep, egrep \- print lines matching a regular expression
+grep, egrep, fgrep \- print lines matching a pattern
 .SH SYNOPSIS
 .B grep
-[
-.B \-CVbchilnsvwx
-] [
-.BI \- num
-] [
-.B \-AB
-.I num
-] [ [
-.B \-e
-]
-.I expr
-|
-.B \-f
-.I file
-] [
-.I "files ..."
-]
+[-[AB] NUM] [-CEFGVabchiLlnqrsvwxyUu] [-e PATTERN | -f FILE]
+[-d ACTION] [--directories=ACTION]
+[--extended-regexp] [--fixed-strings] [--basic-regexp]
+[--regexp=PATTERN] [--file=FILE] [--ignore-case] [--word-regexp]
+[--line-regexp] [--line-regexp] [--no-messages] [--revert-match]
+[--version] [--help] [--byte-offset] [--line-number]
+[--with-filename] [--no-filename] [--quiet] [--silent] [--text]
+[--files-without-match] [--files-with-matcces] [--count]
+[--before-context=NUM] [--after-context=NUM] [--context]
+[--binary] [--unix-byte-offsets] [--recursive]
+.I files...
 .SH DESCRIPTION
-.I Grep
-searches the files listed in the arguments (or standard
-input if no files are given) for all lines that contain a match for
-the given
-.IR expr .
-If any lines match, they are printed.
-.PP
-Also, if any matches were found,
-.I grep
-exits with a status of 0, but if no matches were found it exits
-with a status of 1.  This is useful for building shell scripts that
-use
-.I grep
-as a condition for, for example, the
-.I if
-statement.
-.PP
-When invoked as
-.I egrep
-the syntax of the
-.I expr
-is slightly different; See below.
-.br
-.SH "REGULAR EXPRESSIONS"
-.RS 2.5i
-.ta 1i 2i
-.sp
-.ti -2.0i
-(grep)	(egrep)		(explanation)
-.sp
-.ti -2.0i
-\fIc\fP	\fIc\fP	a single (non-meta) character matches itself.
-.sp
-.ti -2.0i
-\&.	.	matches any single character except newline.
-.sp
-.ti -2.0i
-\\?	?	postfix operator; preceeding item is optional.
-.sp
-.ti -2.0i
-\(**	\(**	postfix operator; preceeding item 0 or
-more times.
-.sp
-.ti -2.0i
-\\+	+	postfix operator; preceeding item 1 or
-more times.
-.sp
-.ti -2.0i
-\\|	|	infix operator; matches either
-argument.
-.sp
-.ti -2.0i
-^	^	matches the empty string at the beginning of a line.
-.sp
-.ti -2.0i
-$	$	matches the empty string at the end of a line.
-.sp
-.ti -2.0i
-\\<	\\<	matches the empty string at the beginning of a word.
-.sp
-.ti -2.0i
-\\>	\\>	matches the empty string at the end of a word.
-.sp
-.ti -2.0i
-[\fIchars\fP]	[\fIchars\fP]	match any character in the given class; if the
-first character after [ is ^, match any character
-not in the given class; a range of characters may
-be specified by \fIfirst\-last\fP; for example, \\W
-(below) is equivalent to the class [^A\-Za\-z0\-9]
-.sp
-.ti -2.0i
-\\( \\)	( )	parentheses are used to override operator precedence.
-.sp
-.ti -2.0i
-\\\fIdigit\fP	\\\fIdigit\fP	\\\fIn\fP matches a repeat of the text
-matched earlier in the regexp by the subexpression inside the nth
-opening parenthesis.
-.sp
-.ti -2.0i
-\\	\\	any special character may be preceded
-by a backslash to match it literally.
-.sp
-.ti -2.0i
-(the following are for compatibility with GNU Emacs)
-.sp
-.ti -2.0i
-\\b	\\b	matches the empty string at the edge of a word.
-.sp
-.ti -2.0i
-\\B	\\B	matches the empty string if not at the edge of a word.
-.sp
-.ti -2.0i
-\\w	\\w	matches word-constituent characters (letters & digits).
-.sp
-.ti -2.0i
-\\W	\\W	matches characters that are not word-constituent.
-.RE
-.PP
-Operator precedence is (highest to lowest) ?, \(**, and +, concatenation,
-and finally |.  All other constructs are syntactically identical to
-normal characters.  For the truly interested, the file dfa.c describes
-(and implements) the exact grammar understood by the parser.
-.SH OPTIONS
-.TP
-.BI \-A " num"
-print <num> lines of context after every matching line
-.TP
-.BI \-B " num"
-print
-.I num
-lines of context before every matching line
-.TP
-.B \-C
-print 2 lines of context on each side of every match
-.TP
-.BI \- num
-print
-.I num
-lines of context on each side of every match
-.TP
-.B \-V
-print the version number on the diagnostic output
+.PP
+.B Grep
+searches the named input
+.I files
+(or standard input if no files are named, or
+the file name
+.B \-
+is given)
+for lines containing a match to the given
+.IR pattern .
+By default,
+.B grep
+prints the matching lines.
+.PP
+There are three major variants of
+.BR grep ,
+controlled by the following options.
+.PD 0
 .TP
-.B \-b
-print every match preceded by its byte offset
+.B \-G, --basic-regexp
+Interpret
+.I pattern
+as a basic regular expression (see below).  This is the default.
+.TP
+.B \-E, --extended-regexp
+Interpret
+.I pattern
+as an extended regular expression (see below).
+.TP
+.B \-F, --fixed-strings
+Interpret
+.I pattern
+as a list of fixed strings, separated by newlines,
+any of which is to be matched.
+.LP
+In addition, two variant programs
+.B egrep
+and
+.B fgrep
+are available.
+.B Egrep
+is similar (but not identical) to
+.BR "grep\ \-E" ,
+and is compatible with the historical Unix
+.BR egrep .
+.B Fgrep
+is the same as
+.BR "grep\ \-F" .
+.PD
+.LP
+All variants of
+.B grep
+understand the following options:
+.PD 0
+.TP
+.BI \-A " NUM" ", --after-context=" NUM
+Print
+.I NUM
+lines of trailing context after matching lines.
+.TP
+.BI \-B " NUM" ", --before-context=" NUM
+Print
+.I NUM
+lines of leading context before matching lines.
+.TP
+.BI \-C ,\  --context"[=NUM]"
+Print 
+.I NUM
+lines (default 2) of output context.
 .TP
-.B \-c
-print a total count of matching lines only
+.BI \- NUM \ 
+Same as --context=NUM lines of leading and trailing context.  However,
+.B grep
+will never print any given line more than once.
+.TP
+.B \-V, --version
+Print the version number of
+.B grep
+to standard error.  This version number should
+be included in all bug reports (see below).
 .TP
-.BI \-e " expr"
-search for
-.IR expr ;
-useful if
-.I expr
-begins with \-
+.B \-b, --byte-offset
+Print the byte offset within the input file before
+each line of output.
 .TP
-.BI \-f " file"
-search for the expression contained in
-.I file
+.B \-c, --count
+Suppress normal output; instead print a count of
+matching lines for each input file.
+With the
+.B \-v, --revert-match
+option (see below), count non-matching lines.
 .TP
-.B \-h
-don't display filenames on matches
+.BI \-d " ACTION" ", --directories=" ACTION
+If an input file is a directory, use
+.I ACTION
+to process it.  By default,
+.I ACTION
+is
+.BR read ,
+which means that directories are read just as if they were ordinary files.
+If
+.I ACTION
+is
+.BR skip ,
+directories are silently skipped.
+If
+.I ACTION
+is
+.BR recurse ,
+.B
+grep reads all files under each directory, recursively;
+this is equivalent to the
+.B \-r
+option.
 .TP
-.B \-i
-ignore case difference when comparing strings
+.BI \-e " PATTERN" ", --regexp=" PATTERN
+Use
+.I PATTERN
+as the pattern; useful to protect patterns beginning with
+.BR \- .
 .TP
-.B \-l
-list files containing matches only
+.BI \-f " FILE" ", --file=" FILE
+Obtain patterns from
+.IR FILE ,
+one per line.
+The empty file contains zero patterns, and therfore matches nothing.
 .TP
-.B \-n
-print each match preceded by its line number
+.B \-h, --no-filename
+Suppress the prefixing of filenames on output
+when multiple files are searched.
 .TP
+.B \-i, --ignore-case
+Ignore case distinctions in both the
+.I pattern
+and the input files.
+.TP
+.B \-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.
+.TP
+.B \-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.
+.TP
+.B \-n, --line-number
+Prefix each line of output with the line number
+within its input file.
+.TP
+.B \-q, --quiet, --silent
+Quiet; suppress normal output. The scanning will stop
+on the first match.
+Also see the
 .B \-s
-run silently producing no output except error messages
+or
+.B --no-messages
+option below.
 .TP
-.B \-v
-print only lines that contain no matches for the <expr>
+.B \-r, --recursive
+Read all files under each directory, recursively;
+this is equivalent to the
+.B "\-d recurse"
+option.
+.TP
+.B \-s, --no-messages
+Suppress error messages about nonexistent or unreadable files.
+Portability note: unlike GNU
+.BR grep ,
+BSD
+.B grep
+does not comply with POSIX.2, because BSD
+.B grep
+lacks a
+.B \-q
+option and its
+.B \-s
+option behaves like GNU
+.BR grep 's
+.B \-q
+option.
+Shell scripts intended to be portable to BSD
+.B grep
+should avoid both
+.B \-q
+and
+.B \-s
+and should redirect output to /dev/null instead.
+.TP
+.B \-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,
+.B grep
+outputs only a message saying that the file matches the pattern.
+This option causes
+.B grep
+to act as if the file is a text file,
+even if it would otherwise be treated as binary.
+.TP
+.B \-v, --revert-match
+Invert the sense of matching, to select non-matching lines.
+.TP
+.B \-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
+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.
+.TP
+.B \-x, --line-regexp
+Select only those matches that exactly match the whole line.
 .TP
-.B \-w
-print only lines where the match is a complete word
+.B \-y
+Obsolete synonym for
+.BR \-i .
 .TP
-.B \-x
-print only lines where the match is a whole line
-.SH "SEE ALSO"
-emacs(1), ed(1), sh(1),
-.I "GNU Emacs Manual"
-.SH INCOMPATIBILITIES
-The following incompatibilities with UNIX
-.I grep
-exist:
+.B \-U, --binary
+Treat the file(s) as binary.  By default, under MS-DOS and MS-Windows,
+.BR grep
+guesses the file type by looking at the contents of the first 32KB
+read from the file.  If
+.BR grep
+decides the file is a text file, it strips the CR characters from the
+original file contents (to make regular expressions with
+.B ^
+and
+.B $
+work correctly).  Specifying
+.B \-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.
+.TP
+.B \-u, --unix-byte-offsets
+Report Unix-style byte offsets.  This switch causes
+.B 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
+.B grep
+on a Unix machine.  This option has no effect unless
+.B \-b
+option is also used; it is only supported on MS-DOS and MS-Windows.
+.PD
+.SH "REGULAR EXPRESSIONS"
 .PP
-.RS 0.5i
-The context-dependent meaning of \(** is not quite the same (grep only).
+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.
 .PP
-.B \-b
-prints a byte offset instead of a block offset.
+.B Grep
+understands two different versions of regular expression syntax:
+``basic'' and ``extended.''  In
+.RB "GNU\ " 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.
 .PP
-The {\fIm,n\fP} construct of System V grep is not implemented.
+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.
 .PP
-.SH BUGS
-GNU \fIe?grep\fP has been thoroughly debugged and tested over a period
-of several years; we think it's a reliable beast or we wouldn't
-distribute it.  If by some fluke of the universe you discover a bug,
-send a detailed description (including options, regular expressions,
-and a copy of an input file that can reproduce it) to mike@ai.mit.edu.
+A list of characters enclosed by
+.B [
+and
+.B ]
+matches any single
+character in that list; if the first character of the list
+is the caret
+.B ^
+then it matches any character
+.I not
+in the list.
+For example, the regular expression
+.B [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
+.BR [:alnum:] ,
+.BR [:alpha:] ,
+.BR [:cntrl:] ,
+.BR [:digit:] ,
+.BR [:graph:] ,
+.BR [:lower:] ,
+.BR [:print:] ,
+.BR [:punct:] ,
+.BR [:space:] ,
+.BR [:upper:] ,
+and
+.BR [:xdigit:].
+For example,
+.B [[:alnum:]]
+means
+.BR [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 meaning
+inside lists.  To include a literal
+.B ]
+place it first in the list.  Similarly, to include a literal
+.B ^
+place it anywhere but first.  Finally, to include a literal
+.B \-
+place it last.
 .PP
-.SH AUTHORS
-Mike Haertel wrote the deterministic regexp code and the bulk
-of the program.
+The period
+.B .
+matches any single character.
+The symbol
+.B \ew
+is a synonym for
+.B [[:alnum:]]
+and
+.B \eW
+is a synonym for
+.BR [^[:alnum]] .
 .PP
-James A. Woods is responsible for the hybridized search strategy
-of using Boyer-Moore-Gosper fixed-string search as a filter
-before calling the general regexp matcher.
+The caret
+.B ^
+and the dollar sign
+.B $
+are metacharacters that respectively match the empty string at the
+beginning and end of a line.
+The symbols
+.B \e<
+and
+.B \e>
+respectively match the empty string at the beginning and end of a word.
+The symbol
+.B \eb
+matches the empty string at the edge of a word,
+and
+.B \eB
+matches the empty string provided it's
+.I not
+at the edge of a word.
 .PP
-Arthur David Olson contributed code that finds fixed strings for
-the aforementioned BMG search for a large class of regexps.
+A regular expression may be followed by one of several repetition operators:
+.PD 0
+.TP
+.B ?
+The preceding item is optional and matched at most once.
+.TP
+.B *
+The preceding item will be matched zero or more times.
+.TP
+.B +
+The preceding item will be matched one or more times.
+.TP
+.BI { n }
+The preceding item is matched exactly
+.I n
+times.
+.TP
+.BI { n ,}
+The preceding item is matched
+.I n
+or more times.
+.TP
+.BI {, m }
+The preceding item is optional and is matched at most
+.I m
+times.
+.TP
+.BI { n , m }
+The preceding item is matched at least
+.I n
+times, but not more than
+.I m
+times.
+.PD
+.PP
+Two regular expressions may be concatenated; the resulting
+regular expression matches any string formed by concatenating
+two substrings that respectively match the concatenated
+subexpressions.
+.PP
+Two regular expressions may be joined by the infix operator
+.BR | ;
+the resulting regular expression matches any string matching
+either subexpression.
+.PP
+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.
 .PP
-Richard Stallman wrote the backtracking regexp matcher that is used
-for \\\fIdigit\fP backreferences, as well as the GNU getopt.  The
-backtracking matcher was originally written for GNU Emacs.
+The backreference
+.BI \e n\c
+\&, where
+.I n
+is a single digit, matches the substring
+previously matched by the
+.IR n th
+parenthesized subexpression of the regular expression.
 .PP
-D. A. Gwyn wrote the C alloca emulation that is provided so
-System V machines can run this program.  (Alloca is used only
-by RMS' backtracking matcher, and then only rarely, so there
-is no loss if your machine doesn't have a "real" alloca.)
+In basic regular expressions the metacharacters
+.BR ? ,
+.BR + ,
+.BR { ,
+.BR | ,
+.BR ( ,
+and
+.BR )
+lose their special meaning; instead use the backslashed
+versions
+.BR \e? ,
+.BR \e+ ,
+.BR \e{ ,
+.BR \e| ,
+.BR \e( ,
+and
+.BR \e) .
 .PP
-Scott Anderson and Henry Spencer designed the regression tests
-used in the "regress" script.
+In
+.B egrep
+the metacharacter
+.B {
+loses its special meaning; instead use
+.BR \e{ .
+.SH DIAGNOSTICS
+.PP
+Normally, exit status is 0 if matches were found,
+and 1 if no matches were found.  (The
+.B \-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.
+.SH BUGS
+.PP
+Email bug reports to
+.BR bug-gnu-utils@gnu.org .
+Be sure to include the word ``grep'' somewhere in the ``Subject:'' field.
+.PP
+Large repetition counts in the
+.BI { 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
+.B grep
+to run out of memory.
 .PP
-Paul Placeway wrote the original version of this manual page.
+Backreferences are very slow, and may require exponential time.