Annotation of src/usr.bin/grep/grep.1, Revision 1.20
1.20 ! jmc 1: .\" $OpenBSD: grep.1,v 1.19 2003/09/27 14:14:40 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
45: .Op Ar
1.1 deraadt 46: .Sh DESCRIPTION
47: The
1.6 deraadt 48: .Nm grep
49: utilities search the given input files selecting lines that match one
50: or more patterns.
51: By default, a pattern matches an input line if any regular expression
52: (RE) in the pattern matches the input line without its trailing
53: newline.
54: An empty expression matches every line.
55: Each input line that matches at least one of the patterns is written
56: to the standard output.
1.1 deraadt 57: .Pp
1.6 deraadt 58: The
59: .Nm grep
60: utility is used for simple patterns and
61: .Xr ex 1
62: or
63: .Xr ed 1
64: style regular expressions.
65: The
1.1 deraadt 66: .Nm egrep
1.6 deraadt 67: utility can handle extended regular expressions and multi-line
68: patterns.
69: The
1.1 deraadt 70: .Nm fgrep
1.6 deraadt 71: utility is quick but can handle only fixed patterns consisting of one
72: or more lines, allowing any of the pattern lines to match a portion of
73: the input.
74: The
1.7 deraadt 75: .Nm zgrep ,
76: .Nm zegrep ,
77: and
78: .Nm zfgrep
1.11 tedu 79: utilities act like
1.7 deraadt 80: .Nm grep ,
81: .Nm egrep ,
82: and
83: .Nm fgrep
1.11 tedu 84: respectively but accept input files compressed with the
1.6 deraadt 85: .Xr compress 1
86: or
87: .Xr gzip 1
88: compression utilities.
1.1 deraadt 89: .Pp
1.6 deraadt 90: The following options are available:
91: .Bl -tag -width indent
92: .It Fl A Ar num
1.7 deraadt 93: Print
1.6 deraadt 94: .Ar num
95: lines of trailing context after each match.
96: .It Fl B Ar num
1.7 deraadt 97: Print
98: .Ar num
1.6 deraadt 99: lines of leading context before each match.
100: .It Fl C
1.19 mcbride 101: Print 2 lines of leading and trailing context after each match.
1.7 deraadt 102: Equivalent to
1.6 deraadt 103: .Fl A
104: .Ar 2
105: .Fl B
106: .Ar 2 .
1.1 deraadt 107: .It Fl E
1.7 deraadt 108: Force
109: .Nm grep
110: to behave as
111: .Nm egrep .
1.1 deraadt 112: .It Fl F
1.7 deraadt 113: Force
1.6 deraadt 114: .Nm grep
1.7 deraadt 115: to behave as
116: .Nm fgrep .
1.6 deraadt 117: .It Fl G
1.7 deraadt 118: Force
1.6 deraadt 119: .Nm grep
1.7 deraadt 120: to behave as
121: .Nm grep .
1.6 deraadt 122: .It Fl H
1.7 deraadt 123: If
1.6 deraadt 124: .Fl R
1.20 ! jmc 125: is specified, follow symbolic links only if they were explicitly listed
1.6 deraadt 126: on the command line.
1.10 tedu 127: .It Fl I
128: Ignore binary files.
1.6 deraadt 129: .It Fl L
130: Only the names of files not containing selected lines are written to
131: standard output.
132: Pathnames are listed once per file searched.
133: If the standard input is searched, the pathname
134: .Sq Fl
135: is written.
136: .It Fl P
1.7 deraadt 137: If
1.6 deraadt 138: .Fl R
139: is specified, no symbolic links are followed.
140: .It Fl R
141: Recursively search subdirectories listed.
142: .It Fl S
1.7 deraadt 143: If
1.6 deraadt 144: .Fl R
145: is specified, all symbolic links are followed.
1.10 tedu 146: .It Fl U
147: Search binary files, but do not attempt to print them.
1.6 deraadt 148: .It Fl V
149: Display version information.
150: .It Fl Z
151: Force
152: .Nm grep
153: to behave as
154: .Nm zgrep .
1.1 deraadt 155: .It Fl a
1.10 tedu 156: Treat all files as text.
1.1 deraadt 157: .It Fl b
1.6 deraadt 158: The block number on the disk in which a matched pattern is located is
159: displayed in front of the respective matched line.
1.1 deraadt 160: .It Fl c
1.6 deraadt 161: Only a count of selected lines is written to standard output.
1.7 deraadt 162: .It Fl e Ar expression
163: Specify a pattern used during the search of the input.
164: Multiple
1.1 deraadt 165: .Fl e
1.6 deraadt 166: options can be used to specify multiple patterns; an input line is
167: selected if it matches any of the specified patterns.
1.7 deraadt 168: .It Fl f Ar pattern_file
1.13 tedu 169: Read one or more newline separated patterns from
170: .Ar pattern_file .
171: Newlines are not considered part of a pattern.
1.1 deraadt 172: .It Fl h
1.6 deraadt 173: Never print filename headers with output lines.
1.1 deraadt 174: .It Fl i
1.6 deraadt 175: Perform case insensitive matching.
1.1 deraadt 176: .It Fl l
1.6 deraadt 177: Only the names of files containing selected lines are written to
1.7 deraadt 178: standard output.
179: Pathnames are listed once per file searched.
180: If the standard input is searched, the pathname
1.6 deraadt 181: .Sq -
182: is written.
1.1 deraadt 183: .It Fl n
1.6 deraadt 184: Each output line is preceded by its relative line number in the file,
185: starting at line 1.
186: The line number counter is reset for each file processed.
187: This option is ignored if
188: .Fl c ,
189: .Fl l ,
190: or
1.17 tedu 191: .Fl q
1.6 deraadt 192: is
193: specified.
194: .It Fl o
195: Always print filename headers with output lines.
1.1 deraadt 196: .It Fl q
1.6 deraadt 197: Suppress normal output.
1.1 deraadt 198: .It Fl s
1.7 deraadt 199: Silent mode.
200: Nonexistent and unreadable files are ignored.
1.1 deraadt 201: .It Fl v
1.6 deraadt 202: Selected lines are those
203: .Em not
1.14 dhartmei 204: matching any of the specified patterns.
1.1 deraadt 205: .It Fl w
1.6 deraadt 206: The expression is searched for as a word (as if surrounded by `\e<'
207: and `\e>', see
208: .Xr ex 1 ) .
1.1 deraadt 209: .It Fl x
1.6 deraadt 210: Only input lines selected against an entire fixed string or regular
211: expression are considered to be matching lines.
1.12 tedu 212: .Sm off
213: .It Fl Fl context Op = Ar num
214: .Sm on
215: Print
216: .Ar num
217: lines of leading and trailing context.
218: Default is 2.
219: .Sm off
220: .It Fl Fl binary-files No = Ar value
221: .Sm on
222: Controls searching and printing of binary files.
223: Options are
224: .Ar binary ,
225: the default, search binary files but do not print them;
226: .Ar without-match ,
227: do not search binary files;
228: and
229: .Ar text ,
230: treat all files as text.
1.6 deraadt 231: .Pp
1.1 deraadt 232: .El
1.6 deraadt 233: If no file arguments are specified, the standard input is used.
1.7 deraadt 234: .Sh RETURN VALUES
1.1 deraadt 235: The
1.6 deraadt 236: .Nm grep
1.1 deraadt 237: utility exits with one of the following values:
238: .Pp
239: .Bl -tag -width flag -compact
1.6 deraadt 240: .It Li 0
241: One or more lines were selected.
242: .It Li 1
243: No lines were selected.
244: .It Li >1
245: An error occurred.
1.4 jmc 246: .El
1.6 deraadt 247: .Sh EXTENDED REGULAR EXPRESSIONS
248: The following characters are interpreted by
249: .Nm egrep :
1.1 deraadt 250: .Pp
1.6 deraadt 251: .Bl -tag -width flag -compact
252: .It Cm \&$
253: Align the match from the end of the line.
254: .It Cm \&^
255: Align the match from the beginning of the line.
256: .It Cm \&|
257: Add another pattern (see example below).
258: .It Cm \&?
259: Match 1 or less sequential repetitions of the pattern.
260: .It Cm \&+
261: Match 1 or more sequential repetitions of the pattern.
262: .It Cm \&*
263: Match 0 or more sequential repetitions of the pattern.
1.18 millert 264: .It Cm \&{}
265: Match specified number of sequential repetitions of the pattern.
1.6 deraadt 266: .It Cm \&[]
267: Match any single character or range of characters
268: enclosed in the brackets.
269: .It Cm \&\e
270: Escape special characters which have meaning to
271: .Nm egrep ,
1.18 millert 272: the set of {$,.,^,[,],|,?,+,*,{,},(,)}.
1.6 deraadt 273: .El
274: .Sh EXAMPLES
275: To find all occurrences of the word patricia in a file:
276: .Pp
277: .Dl grep patricia myfile
278: .Pp
279: To find all occurrences of the pattern
280: .Ql \&.Pp
281: at the beginning of a line:
282: .Pp
283: .Dl grep '^\e.Pp'
284: .Pp
1.7 deraadt 285: The apostrophes ensure the entire expression is evaluated by
1.6 deraadt 286: .Nm grep
287: instead of by the
288: user's shell.
289: The caret
1.15 jmc 290: .Ql \&^
1.6 deraadt 291: matches the null string at the beginning of a line,
292: and the
1.15 jmc 293: .Ql \&\e
1.6 deraadt 294: escapes the
1.15 jmc 295: .Ql \&.
1.6 deraadt 296: which would otherwise match any character.
297: .Pp
298: A simple example of an extended regular expression:
299: .Pp
300: .Dl egrep '19|20|25' calendar
301: .Pp
302: Peruses the file calendar looking for either 19, 20
303: or 25.
1.1 deraadt 304: .Sh SEE ALSO
1.6 deraadt 305: .Xr ed 1 ,
306: .Xr ex 1 ,
307: .Xr sed 1 ,
1.1 deraadt 308: .Xr regex 3 ,
1.7 deraadt 309: .Xr regexp 3 ,
310: .Xr re_format 7
1.1 deraadt 311: .Sh HISTORY
1.6 deraadt 312: The
1.1 deraadt 313: .Nm grep
314: command appeared in
315: .At v6 .