Annotation of src/usr.bin/grep/grep.1, Revision 1.22
1.22 ! otto 1: .\" $OpenBSD: grep.1,v 1.21 2003/12/11 20:48:06 mcbride Exp $
1.6 deraadt 2: .\" Copyright (c) 1980, 1990, 1993
3: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 4: .\"
5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\" 1. Redistributions of source code must retain the above copyright
9: .\" notice, this list of conditions and the following disclaimer.
10: .\" 2. Redistributions in binary form must reproduce the above copyright
11: .\" notice, this list of conditions and the following disclaimer in the
12: .\" documentation and/or other materials provided with the distribution.
1.9 millert 13: .\" 3. Neither the name of the University nor the names of its contributors
1.6 deraadt 14: .\" may be used to endorse or promote products derived from this software
15: .\" without specific prior written permission.
1.1 deraadt 16: .\"
1.6 deraadt 17: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
1.1 deraadt 18: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
1.6 deraadt 20: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
1.1 deraadt 21: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27: .\" SUCH DAMAGE.
28: .\"
1.6 deraadt 29: .\" @(#)grep.1 8.3 (Berkeley) 4/18/94
30: .\"
31: .Dd July 3, 1999
1.1 deraadt 32: .Dt GREP 1
33: .Os
34: .Sh NAME
1.7 deraadt 35: .Nm grep, egrep, fgrep, zgrep, zegrep, zfgrep
1.6 deraadt 36: .Nd file pattern searcher
1.1 deraadt 37: .Sh SYNOPSIS
38: .Nm grep
1.6 deraadt 39: .Op Fl AB Ar num
1.10 tedu 40: .Op Fl CEFGHILPRSUVZabchilnoqsvwx
1.12 tedu 41: .Op Fl -context Ns Op = Ns Ar num
42: .Op Fl -binary-files Ns = Ns Ar value
1.6 deraadt 43: .Op Fl e Ar pattern
44: .Op Fl f Ar file
1.21 mcbride 45: .Op Ar pattern
1.6 deraadt 46: .Op Ar
1.1 deraadt 47: .Sh DESCRIPTION
48: The
1.6 deraadt 49: .Nm grep
50: utilities search the given input files selecting lines that match one
51: or more patterns.
52: By default, a pattern matches an input line if any regular expression
53: (RE) in the pattern matches the input line without its trailing
54: newline.
55: An empty expression matches every line.
56: Each input line that matches at least one of the patterns is written
57: to the standard output.
1.1 deraadt 58: .Pp
1.6 deraadt 59: The
60: .Nm grep
61: utility is used for simple patterns and
62: .Xr ex 1
63: or
64: .Xr ed 1
65: style regular expressions.
66: The
1.1 deraadt 67: .Nm egrep
1.6 deraadt 68: utility can handle extended regular expressions and multi-line
69: patterns.
70: The
1.1 deraadt 71: .Nm fgrep
1.6 deraadt 72: utility is quick but can handle only fixed patterns consisting of one
73: or more lines, allowing any of the pattern lines to match a portion of
74: the input.
75: The
1.7 deraadt 76: .Nm zgrep ,
77: .Nm zegrep ,
78: and
79: .Nm zfgrep
1.11 tedu 80: utilities act like
1.7 deraadt 81: .Nm grep ,
82: .Nm egrep ,
83: and
84: .Nm fgrep
1.11 tedu 85: respectively but accept input files compressed with the
1.6 deraadt 86: .Xr compress 1
87: or
88: .Xr gzip 1
89: compression utilities.
1.1 deraadt 90: .Pp
1.6 deraadt 91: The following options are available:
92: .Bl -tag -width indent
93: .It Fl A Ar num
1.7 deraadt 94: Print
1.6 deraadt 95: .Ar num
96: lines of trailing context after each match.
97: .It Fl B Ar num
1.7 deraadt 98: Print
99: .Ar num
1.6 deraadt 100: lines of leading context before each match.
101: .It Fl C
1.19 mcbride 102: Print 2 lines of leading and trailing context after each match.
1.7 deraadt 103: Equivalent to
1.6 deraadt 104: .Fl A
105: .Ar 2
106: .Fl B
107: .Ar 2 .
1.1 deraadt 108: .It Fl E
1.7 deraadt 109: Force
110: .Nm grep
111: to behave as
112: .Nm egrep .
1.1 deraadt 113: .It Fl F
1.7 deraadt 114: Force
1.6 deraadt 115: .Nm grep
1.7 deraadt 116: to behave as
117: .Nm fgrep .
1.6 deraadt 118: .It Fl G
1.7 deraadt 119: Force
1.6 deraadt 120: .Nm grep
1.7 deraadt 121: to behave as
122: .Nm grep .
1.6 deraadt 123: .It Fl H
1.7 deraadt 124: If
1.6 deraadt 125: .Fl R
1.20 jmc 126: is specified, follow symbolic links only if they were explicitly listed
1.6 deraadt 127: on the command line.
1.10 tedu 128: .It Fl I
129: Ignore binary files.
1.6 deraadt 130: .It Fl L
131: Only the names of files not containing selected lines are written to
132: standard output.
133: Pathnames are listed once per file searched.
134: If the standard input is searched, the pathname
135: .Sq Fl
136: is written.
137: .It Fl P
1.7 deraadt 138: If
1.6 deraadt 139: .Fl R
140: is specified, no symbolic links are followed.
141: .It Fl R
142: Recursively search subdirectories listed.
143: .It Fl S
1.7 deraadt 144: If
1.6 deraadt 145: .Fl R
146: is specified, all symbolic links are followed.
1.10 tedu 147: .It Fl U
148: Search binary files, but do not attempt to print them.
1.6 deraadt 149: .It Fl V
150: Display version information.
151: .It Fl Z
152: Force
153: .Nm grep
154: to behave as
155: .Nm zgrep .
1.1 deraadt 156: .It Fl a
1.10 tedu 157: Treat all files as text.
1.1 deraadt 158: .It Fl b
1.22 ! otto 159: The offset in bytes of a matched pattern is
1.6 deraadt 160: displayed in front of the respective matched line.
1.1 deraadt 161: .It Fl c
1.6 deraadt 162: Only a count of selected lines is written to standard output.
1.7 deraadt 163: .It Fl e Ar expression
164: Specify a pattern used during the search of the input.
165: Multiple
1.1 deraadt 166: .Fl e
1.6 deraadt 167: options can be used to specify multiple patterns; an input line is
168: selected if it matches any of the specified patterns.
1.7 deraadt 169: .It Fl f Ar pattern_file
1.13 tedu 170: Read one or more newline separated patterns from
171: .Ar pattern_file .
172: Newlines are not considered part of a pattern.
1.1 deraadt 173: .It Fl h
1.6 deraadt 174: Never print filename headers with output lines.
1.1 deraadt 175: .It Fl i
1.6 deraadt 176: Perform case insensitive matching.
1.1 deraadt 177: .It Fl l
1.6 deraadt 178: Only the names of files containing selected lines are written to
1.7 deraadt 179: standard output.
180: Pathnames are listed once per file searched.
181: If the standard input is searched, the pathname
1.6 deraadt 182: .Sq -
183: is written.
1.1 deraadt 184: .It Fl n
1.6 deraadt 185: Each output line is preceded by its relative line number in the file,
186: starting at line 1.
187: The line number counter is reset for each file processed.
188: This option is ignored if
189: .Fl c ,
190: .Fl l ,
191: or
1.17 tedu 192: .Fl q
1.6 deraadt 193: is
194: specified.
195: .It Fl o
196: Always print filename headers with output lines.
1.1 deraadt 197: .It Fl q
1.6 deraadt 198: Suppress normal output.
1.1 deraadt 199: .It Fl s
1.7 deraadt 200: Silent mode.
201: Nonexistent and unreadable files are ignored.
1.1 deraadt 202: .It Fl v
1.6 deraadt 203: Selected lines are those
204: .Em not
1.14 dhartmei 205: matching any of the specified patterns.
1.1 deraadt 206: .It Fl w
1.6 deraadt 207: The expression is searched for as a word (as if surrounded by `\e<'
208: and `\e>', see
209: .Xr ex 1 ) .
1.1 deraadt 210: .It Fl x
1.6 deraadt 211: Only input lines selected against an entire fixed string or regular
212: expression are considered to be matching lines.
1.12 tedu 213: .Sm off
214: .It Fl Fl context Op = Ar num
215: .Sm on
216: Print
217: .Ar num
218: lines of leading and trailing context.
219: Default is 2.
220: .Sm off
221: .It Fl Fl binary-files No = Ar value
222: .Sm on
223: Controls searching and printing of binary files.
224: Options are
225: .Ar binary ,
226: the default, search binary files but do not print them;
227: .Ar without-match ,
228: do not search binary files;
229: and
230: .Ar text ,
231: treat all files as text.
1.6 deraadt 232: .Pp
1.1 deraadt 233: .El
1.6 deraadt 234: If no file arguments are specified, the standard input is used.
1.7 deraadt 235: .Sh RETURN VALUES
1.1 deraadt 236: The
1.6 deraadt 237: .Nm grep
1.1 deraadt 238: utility exits with one of the following values:
239: .Pp
240: .Bl -tag -width flag -compact
1.6 deraadt 241: .It Li 0
242: One or more lines were selected.
243: .It Li 1
244: No lines were selected.
245: .It Li >1
246: An error occurred.
1.4 jmc 247: .El
1.6 deraadt 248: .Sh EXTENDED REGULAR EXPRESSIONS
249: The following characters are interpreted by
250: .Nm egrep :
1.1 deraadt 251: .Pp
1.6 deraadt 252: .Bl -tag -width flag -compact
253: .It Cm \&$
254: Align the match from the end of the line.
255: .It Cm \&^
256: Align the match from the beginning of the line.
257: .It Cm \&|
258: Add another pattern (see example below).
259: .It Cm \&?
260: Match 1 or less sequential repetitions of the pattern.
261: .It Cm \&+
262: Match 1 or more sequential repetitions of the pattern.
263: .It Cm \&*
264: Match 0 or more sequential repetitions of the pattern.
1.18 millert 265: .It Cm \&{}
266: Match specified number of sequential repetitions of the pattern.
1.6 deraadt 267: .It Cm \&[]
268: Match any single character or range of characters
269: enclosed in the brackets.
270: .It Cm \&\e
271: Escape special characters which have meaning to
272: .Nm egrep ,
1.18 millert 273: the set of {$,.,^,[,],|,?,+,*,{,},(,)}.
1.6 deraadt 274: .El
275: .Sh EXAMPLES
276: To find all occurrences of the word patricia in a file:
277: .Pp
278: .Dl grep patricia myfile
279: .Pp
280: To find all occurrences of the pattern
281: .Ql \&.Pp
282: at the beginning of a line:
283: .Pp
284: .Dl grep '^\e.Pp'
285: .Pp
1.7 deraadt 286: The apostrophes ensure the entire expression is evaluated by
1.6 deraadt 287: .Nm grep
288: instead of by the
289: user's shell.
290: The caret
1.15 jmc 291: .Ql \&^
1.6 deraadt 292: matches the null string at the beginning of a line,
293: and the
1.15 jmc 294: .Ql \&\e
1.6 deraadt 295: escapes the
1.15 jmc 296: .Ql \&.
1.6 deraadt 297: which would otherwise match any character.
1.21 mcbride 298: .Pp
299: To find all lines in a file which do not contain the words foo or bar:
300: .Pp
301: .Dl grep -v -e foo -e bar myfile
1.6 deraadt 302: .Pp
303: A simple example of an extended regular expression:
304: .Pp
305: .Dl egrep '19|20|25' calendar
306: .Pp
307: Peruses the file calendar looking for either 19, 20
308: or 25.
1.1 deraadt 309: .Sh SEE ALSO
1.6 deraadt 310: .Xr ed 1 ,
311: .Xr ex 1 ,
312: .Xr sed 1 ,
1.1 deraadt 313: .Xr regex 3 ,
1.7 deraadt 314: .Xr regexp 3 ,
315: .Xr re_format 7
1.1 deraadt 316: .Sh HISTORY
1.6 deraadt 317: The
1.1 deraadt 318: .Nm grep
319: command appeared in
320: .At v6 .