From b3e9799eb02ff6def7d3757351bf2e2e7dd848be Mon Sep 17 00:00:00 2001 From: obrien Date: Sun, 21 Nov 1999 01:50:08 +0000 Subject: 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. --- gnu/usr.bin/grep/grep.1 | 655 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 449 insertions(+), 206 deletions(-) (limited to 'gnu/usr.bin/grep') 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 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 +.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. -- cgit v1.1 From fac3cf264f5ad722ebdc3390aa6a6497b6b000e5 Mon Sep 17 00:00:00 2001 From: obrien Date: Mon, 22 Nov 1999 08:53:32 +0000 Subject: Virgin import of a trimmed down GNU Grep 2.3. --- gnu/usr.bin/grep/doc/grep.texi | 672 ++++++++++++++++++++++++++++++++++++++ gnu/usr.bin/grep/doc/version.texi | 3 + 2 files changed, 675 insertions(+) create mode 100644 gnu/usr.bin/grep/doc/grep.texi create mode 100644 gnu/usr.bin/grep/doc/version.texi (limited to 'gnu/usr.bin/grep') 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 -- cgit v1.1