diff options
Diffstat (limited to 'gnu/usr.bin/grep')
-rw-r--r-- | gnu/usr.bin/grep/doc/grep.texi | 672 | ||||
-rw-r--r-- | gnu/usr.bin/grep/doc/version.texi | 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 |