Virgin import of a trimmed down GNU Grep 2.3.

2 files changed, 675 insertions, 0 deletions

diff --git a/gnu/usr.bin/grep/doc/grep.texi b/gnu/usr.bin/grep/doc/grep.texi
new file mode 100644
index 0000000..23b0553
--- /dev/null
+++ b/gnu/usr.bin/grep/doc/grep.texi
@@ -0,0 +1,672 @@
+\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
diff --git a/gnu/usr.bin/grep/doc/version.texi b/gnu/usr.bin/grep/doc/version.texi
new file mode 100644
index 0000000..ace0491
--- /dev/null
+++ b/gnu/usr.bin/grep/doc/version.texi
@@ -0,0 +1,3 @@
+@set UPDATED 10 February 1999
+@set EDITION 2.3
+@set VERSION 2.3