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