diff options
Diffstat (limited to 'usr.bin/grep/grep.1')
| -rw-r--r-- | usr.bin/grep/grep.1 | 335 |
1 files changed, 209 insertions, 126 deletions
diff --git a/usr.bin/grep/grep.1 b/usr.bin/grep/grep.1 index e7523ebeda6..6e1b1f13890 100644 --- a/usr.bin/grep/grep.1 +++ b/usr.bin/grep/grep.1 @@ -1,4 +1,4 @@ -.\" $OpenBSD: grep.1,v 1.26 2004/04/17 20:10:55 jmc Exp $ +.\" $OpenBSD: grep.1,v 1.27 2004/09/28 20:51:15 jmc Exp $ .\" Copyright (c) 1980, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" @@ -32,58 +32,69 @@ .Dt GREP 1 .Os .Sh NAME -.Nm grep, egrep, fgrep, zgrep, zegrep, zfgrep +.Nm grep , egrep , fgrep , +.Nm zgrep , zegrep , zfgrep .Nd file pattern searcher .Sh SYNOPSIS .Nm grep -.Op Fl AB Ar num -.Op Fl CEFGHILPRSUVZabchilnoqsvwx -.Op Fl -context Ns Op = Ns Ar num -.Op Fl -binary-files Ns = Ns Ar value -.Op Fl -line-buffered +.Bk -words +.Op Fl abcEFGHhIiLlnoPqRSsUVvwxZ +.Op Fl A Ar num +.Op Fl B Ar num +.Op Fl C Ns Op Ar num .Op Fl e Ar pattern .Op Fl f Ar file +.Op Fl -binary-files Ns = Ns Ar value +.Op Fl -context Ns Op = Ns Ar num +.Op Fl -line-buffered .Op Ar pattern .Op Ar +.Ek .Sh DESCRIPTION The .Nm grep -utilities search the given input files selecting lines that match one -or more patterns. -By default, a pattern matches an input line if any regular expression -(RE) in the pattern matches the input line without its trailing -newline. +utility searches any given input files, +selecting lines that match one or more patterns. +By default, a pattern matches an input line if the regular expression +(RE) in the pattern matches the input line +without its trailing newline. An empty expression matches every line. Each input line that matches at least one of the patterns is written to the standard output. .Pp -The .Nm grep -utility is used for simple patterns and -.Xr ex 1 +is used for simple patterns and +.Xr ex 1 - or -.Xr ed 1 -style regular expressions. -The +.Xr ed 1 -style +regular expressions. .Nm egrep -utility can handle extended regular expressions and multi-line -patterns. -The +can handle extended regular expressions; +for a discussion of extended regular expressions, see +.Xr re_format 7 ; +for a list of extended regular expression special characters, see +.Sx EXTENDED REGULAR EXPRESSIONS , +below. .Nm fgrep -utility is quick but can handle only fixed patterns consisting of one -or more lines, allowing any of the pattern lines to match a portion of -the input. -The +is quicker than both +.Nm grep +and +.Nm egrep , +but can only handle fixed patterns +(i.e. it does not interpret regular expressions). +Patterns may consist of one or more lines, +allowing any of the pattern lines to match a portion of the input. +.Pp .Nm zgrep , .Nm zegrep , and .Nm zfgrep -utilities act like +act like .Nm grep , .Nm egrep , and -.Nm fgrep -respectively but accept input files compressed with the +.Nm fgrep , +respectively, but accept input files compressed with the .Xr compress 1 or .Xr gzip 1 @@ -95,89 +106,104 @@ The following options are available: Print .Ar num lines of trailing context after each match. +See also the +.Fl B +and +.Fl C +options. +.It Fl a +Treat all files as ASCII text. .It Fl B Ar num Print .Ar num lines of leading context before each match. -.It Fl C -Print 2 lines of leading and trailing context after each match. -Equivalent to +See also the +.Fl A +and +.Fl C +options. +.It Fl b +The offset in bytes of a matched pattern is +displayed in front of the respective matched line. +.It Fl C Ns Op Ar num +Print +.Ar num +lines of leading and trailing context surrounding each match. +The default is 2 and is equivalent to .Fl A .Ar 2 .Fl B .Ar 2 . +Note: +no whitespace may be given between the option and its argument. +.It Fl c +Only a count of selected lines is written to standard output. .It Fl E -Force +Interpret +.Ar pattern +as an extended regular expression +(i.e. force .Nm grep to behave as -.Nm egrep . +.Nm egrep ) . +.It Fl e Ar pattern +Specify a pattern used during the search of the input: +an input line is selected if it matches any of the specified patterns. +This option is most useful when multiple +.Fl e +options are used to specify multiple patterns, +or when a pattern begins with a dash +.Pq Sq - . .It Fl F -Force +Interpret +.Ar pattern +as a set of fixed strings +(i.e. force .Nm grep to behave as -.Nm fgrep . +.Nm fgrep ) . +.It Fl f Ar file +Read one or more newline separated patterns from +.Ar file . +Newlines are not considered part of a pattern. .It Fl G -Force +Interpret +.Ar pattern +as a basic regular expression +(i.e. force .Nm grep -to behave as -.Nm grep . +to behave as traditional +.Nm grep ) . .It Fl H If .Fl R is specified, follow symbolic links only if they were explicitly listed on the command line. +The default is not to follow symbolic links. +.It Fl h +Never print filename headers +.Pq i.e. filenames +with output lines. .It Fl I Ignore binary files. +.It Fl i +Perform case insensitive matching. +By default, +.Nm grep +is case sensitive. .It Fl L Only the names of files not containing selected lines are written to standard output. Pathnames are listed once per file searched. If the standard input is searched, the pathname -.Sq Fl +.Sq - is written. -.It Fl P -If -.Fl R -is specified, no symbolic links are followed. -.It Fl R -Recursively search subdirectories listed. -.It Fl S -If -.Fl R -is specified, all symbolic links are followed. -.It Fl U -Search binary files, but do not attempt to print them. -.It Fl V -Display version information. -.It Fl Z -Force -.Nm grep -to behave as -.Nm zgrep . -.It Fl a -Treat all files as text. -.It Fl b -The offset in bytes of a matched pattern is -displayed in front of the respective matched line. -.It Fl c -Only a count of selected lines is written to standard output. -.It Fl e Ar expression -Specify a pattern used during the search of the input. -Multiple -.Fl e -options can be used to specify multiple patterns; an input line is -selected if it matches any of the specified patterns. -.It Fl f Ar pattern_file -Read one or more newline separated patterns from -.Ar pattern_file . -Newlines are not considered part of a pattern. -.It Fl h -Never print filename headers with output lines. -.It Fl i -Perform case insensitive matching. .It Fl l Only the names of files containing selected lines are written to standard output. +.Nm grep +will only search a file until a match has been found, +making searches potentially less expensive. Pathnames are listed once per file searched. If the standard input is searched, the pathname .Sq - @@ -188,48 +214,78 @@ starting at line 1. The line number counter is reset for each file processed. This option is ignored if .Fl c , +.Fl L , .Fl l , +.Fl q , or -.Fl q +.Fl v is specified. .It Fl o Always print filename headers with output lines. +.It Fl P +If +.Fl R +is specified, no symbolic links are followed. +This is the default. .It Fl q -Suppress normal output. +Quiet mode: +suppress normal output. +.Nm grep +will only search a file until a match has been found, +making searches potentially less expensive. +.It Fl R +Recursively search subdirectories listed. +.It Fl S +If +.Fl R +is specified, all symbolic links are followed. +The default is not to follow symbolic links. .It Fl s Silent mode. -Nonexistent and unreadable files are ignored. +Nonexistent and unreadable files are ignored +(i.e. their error messages are suppressed). +.It Fl U +Search binary files, but do not attempt to print them. +.It Fl V +Display version information. +All other options are ignored. .It Fl v Selected lines are those .Em not matching any of the specified patterns. .It Fl w -The expression is searched for as a word (as if surrounded by `[[:<:]]' -and `[[:>:]]', see +The expression is searched for as a word (as if surrounded by +.Sq [[:<:]] +and +.Sq [[:>:]] ; +see .Xr re_format 7 ) . .It Fl x Only input lines selected against an entire fixed string or regular expression are considered to be matching lines. -.Sm off -.It Fl Fl context Op = Ar num -.Sm on -Print -.Ar num -lines of leading and trailing context. -Default is 2. -.Sm off -.It Fl Fl binary-files No = Ar value -.Sm on +.It Fl Z +Force +.Nm grep +to behave as +.Nm zgrep . +.It Fl Fl binary-files Ns = Ns Ar value Controls searching and printing of binary files. Options are .Ar binary , -the default, search binary files but do not print them; -.Ar without-match , +the default: search binary files but do not print them; +.Ar without-match : do not search binary files; and -.Ar text , +.Ar text : treat all files as text. +.Sm off +.It Fl Fl context Op = Ar num +.Sm on +Print +.Ar num +lines of leading and trailing context. +The default is 2. .It Fl Fl line-buffered Force output to be line buffered. By default, output is line buffered when standard output is a terminal @@ -247,7 +303,7 @@ utility exits with one of the following values: One or more lines were selected. .It Li 1 No lines were selected. -.It Li >1 +.It Li \*(Gt1 An error occurred. .El .Sh EXTENDED REGULAR EXPRESSIONS @@ -255,71 +311,98 @@ The following characters are interpreted by .Nm egrep : .Pp .Bl -tag -width flag -compact -.It Cm \&$ -Align the match from the end of the line. -.It Cm \&^ +.It Cm ^ Align the match from the beginning of the line. +.It Cm $ +Align the match from the end of the line. .It Cm \&| Add another pattern (see example below). +.It Cm \&. +Match any single character. .It Cm \&? Match 1 or less sequential repetitions of the pattern. -.It Cm \&+ +.It Cm + Match 1 or more sequential repetitions of the pattern. -.It Cm \&* +.It Cm * Match 0 or more sequential repetitions of the pattern. -.It Cm \&{} +.It Cm {} Match specified number of sequential repetitions of the pattern. -.It Cm \&[] -Match any single character or range of characters -enclosed in the brackets. -.It Cm \&\e +.It Cm [] +Match any characters enclosed in the brackets. +.It Cm () +Delimits a subexpression. +.It Cm \e Escape special characters which have meaning to -.Nm egrep , -the set of `$.^[]|?+*{}()\e'. +.Nm egrep . .El .Sh EXAMPLES -To find all occurrences of the word patricia in a file: +To find all occurrences of the word +.Sq patricia +in a file: .Pp -.Dl grep patricia myfile +.Dl $ grep 'patricia' myfile .Pp To find all occurrences of the pattern -.Ql \&.Pp +.Ql .Pp at the beginning of a line: .Pp -.Dl grep '^\e.Pp' +.Dl $ grep '^\e.Pp' myfile .Pp The apostrophes ensure the entire expression is evaluated by .Nm grep -instead of by the -user's shell. +instead of by the user's shell. The caret -.Ql \&^ +.Ql ^ matches the null string at the beginning of a line, and the -.Ql \&\e +.Ql \e escapes the -.Ql \&. +.Ql \&. , which would otherwise match any character. .Pp -To find all lines in a file which do not contain the words foo or bar: +To find all lines in a file which do not contain the words +.Sq foo +or +.Sq bar : .Pp -.Dl grep -v -e foo -e bar myfile +.Dl $ grep -v -e 'foo' -e 'bar' myfile .Pp A simple example of an extended regular expression: .Pp -.Dl egrep '19|20|25' calendar +.Dl $ egrep '19|20|25' calendar .Pp -Peruses the file calendar looking for either 19, 20 -or 25. +Peruses the file +.Sq calendar +looking for either 19, 20, or 25. .Sh SEE ALSO .Xr ed 1 , .Xr ex 1 , +.Xr gzip 1 , .Xr sed 1 , .Xr regex 3 , -.Xr regexp 3 , .Xr re_format 7 +.Sh STANDARDS +The +.Nm grep +utility is compliant with the +.St -p1003.1-2003 +specification. +.Pp +The flags +.Op Fl AaBbCGHhILoPRSUVwZ +are extensions to that specification. +.Pp +All long options are provided for compatibility with +GNU versions of this utility. +.Pp +Historic versions of the +.Nm grep +utility also supported the flags +.Op Fl ruy . +This implementation supports those options; +however, their use is strongly discouraged. .Sh HISTORY The .Nm grep -command appeared in +command first appeared in .At v6 . |