Annotation of src/usr.bin/grep/grep.1, Revision 1.10
1.10 ! tedu 1: .\" $OpenBSD: grep.1,v 1.9 2003/06/22 22:42:00 millert 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.6 deraadt 41: .Op Fl e Ar pattern
42: .Op Fl f Ar file
43: .Op Ar
1.1 deraadt 44: .Sh DESCRIPTION
45: The
1.6 deraadt 46: .Nm grep
47: utilities search the given input files selecting lines that match one
48: or more patterns.
49: By default, a pattern matches an input line if any regular expression
50: (RE) in the pattern matches the input line without its trailing
51: newline.
52: An empty expression matches every line.
53: Each input line that matches at least one of the patterns is written
54: to the standard output.
1.1 deraadt 55: .Pp
1.6 deraadt 56: The
57: .Nm grep
58: utility is used for simple patterns and
59: .Xr ex 1
60: or
61: .Xr ed 1
62: style regular expressions.
63: The
1.1 deraadt 64: .Nm egrep
1.6 deraadt 65: utility can handle extended regular expressions and multi-line
66: patterns.
67: The
1.1 deraadt 68: .Nm fgrep
1.6 deraadt 69: utility is quick but can handle only fixed patterns consisting of one
70: or more lines, allowing any of the pattern lines to match a portion of
71: the input.
72: The
1.7 deraadt 73: .Nm zgrep ,
74: .Nm zegrep ,
75: and
76: .Nm zfgrep
77: utilities acts like
78: .Nm grep ,
79: .Nm egrep ,
80: and
81: .Nm fgrep
82: respectively but accepts input files compressed with the
1.6 deraadt 83: .Xr compress 1
84: or
85: .Xr gzip 1
86: compression utilities.
1.1 deraadt 87: .Pp
1.6 deraadt 88: The following options are available:
1.5 jmc 89: .Pp
1.6 deraadt 90: .Bl -tag -width indent
91: .It Fl A Ar num
1.7 deraadt 92: Print
1.6 deraadt 93: .Ar num
94: lines of trailing context after each match.
95: .It Fl B Ar num
1.7 deraadt 96: Print
97: .Ar num
1.6 deraadt 98: lines of leading context before each match.
99: .It Fl C
1.7 deraadt 100: Equivalent to
1.6 deraadt 101: .Fl A
102: .Ar 2
103: .Fl B
104: .Ar 2 .
1.1 deraadt 105: .It Fl E
1.7 deraadt 106: Force
107: .Nm grep
108: to behave as
109: .Nm egrep .
1.1 deraadt 110: .It Fl F
1.7 deraadt 111: Force
1.6 deraadt 112: .Nm grep
1.7 deraadt 113: to behave as
114: .Nm fgrep .
1.6 deraadt 115: .It Fl G
1.7 deraadt 116: Force
1.6 deraadt 117: .Nm grep
1.7 deraadt 118: to behave as
119: .Nm grep .
1.6 deraadt 120: .It Fl H
1.7 deraadt 121: If
1.6 deraadt 122: .Fl R
123: is specified, follow symbolic links only if they were explictly listed
124: on the command line.
1.10 ! tedu 125: .It Fl I
! 126: Ignore binary files.
1.6 deraadt 127: .It Fl L
128: Only the names of files not containing selected lines are written to
129: standard output.
130: Pathnames are listed once per file searched.
131: If the standard input is searched, the pathname
132: .Sq Fl
133: is written.
134: .It Fl P
1.7 deraadt 135: If
1.6 deraadt 136: .Fl R
137: is specified, no symbolic links are followed.
138: .It Fl R
139: Recursively search subdirectories listed.
140: .It Fl S
1.7 deraadt 141: If
1.6 deraadt 142: .Fl R
143: is specified, all symbolic links are followed.
1.10 ! tedu 144: .It Fl U
! 145: Search binary files, but do not attempt to print them.
1.6 deraadt 146: .It Fl V
147: Display version information.
148: .It Fl Z
149: Force
150: .Nm grep
151: to behave as
152: .Nm zgrep .
1.1 deraadt 153: .It Fl a
1.10 ! tedu 154: Treat all files as text.
1.1 deraadt 155: .It Fl b
1.6 deraadt 156: The block number on the disk in which a matched pattern is located is
157: displayed in front of the respective matched line.
1.1 deraadt 158: .It Fl c
1.6 deraadt 159: Only a count of selected lines is written to standard output.
1.7 deraadt 160: .It Fl e Ar expression
161: Specify a pattern used during the search of the input.
162: Multiple
1.1 deraadt 163: .Fl e
1.6 deraadt 164: options can be used to specify multiple patterns; an input line is
165: selected if it matches any of the specified patterns.
1.7 deraadt 166: .It Fl f Ar pattern_file
167: The pattern is read from the specified file.
168: Trailing newlines in the pattern file are ignored.
1.6 deraadt 169: .Pf ( Nm Egrep
170: and
171: .Nm fgrep
172: only).
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
192: .Fl s
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
205: matching the specified
206: patterns.
1.1 deraadt 207: .It Fl w
1.6 deraadt 208: The expression is searched for as a word (as if surrounded by `\e<'
209: and `\e>', see
210: .Xr ex 1 ) .
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.
214: .Pp
1.1 deraadt 215: .El
1.6 deraadt 216: If no file arguments are specified, the standard input is used.
1.7 deraadt 217: .Sh RETURN VALUES
1.1 deraadt 218: The
1.6 deraadt 219: .Nm grep
1.1 deraadt 220: utility exits with one of the following values:
221: .Pp
222: .Bl -tag -width flag -compact
1.6 deraadt 223: .It Li 0
224: One or more lines were selected.
225: .It Li 1
226: No lines were selected.
227: .It Li >1
228: An error occurred.
1.4 jmc 229: .El
1.6 deraadt 230: .Sh EXTENDED REGULAR EXPRESSIONS
231: The following characters are interpreted by
232: .Nm egrep :
1.1 deraadt 233: .Pp
1.6 deraadt 234: .Bl -tag -width flag -compact
235: .It Cm \&$
236: Align the match from the end of the line.
237: .It Cm \&^
238: Align the match from the beginning of the line.
239: .It Cm \&|
240: Add another pattern (see example below).
241: .It Cm \&?
242: Match 1 or less sequential repetitions of the pattern.
243: .It Cm \&+
244: Match 1 or more sequential repetitions of the pattern.
245: .It Cm \&*
246: Match 0 or more sequential repetitions of the pattern.
247: .It Cm \&[]
248: Match any single character or range of characters
249: enclosed in the brackets.
250: .It Cm \&\e
251: Escape special characters which have meaning to
252: .Nm egrep ,
253: the set of {$,.,^,[,],|,?,+,*,(,)}.
254: .El
255: .Sh EXAMPLES
256: To find all occurrences of the word patricia in a file:
257: .Pp
258: .Dl grep patricia myfile
259: .Pp
260: To find all occurrences of the pattern
261: .Ql \&.Pp
262: at the beginning of a line:
263: .Pp
264: .Dl grep '^\e.Pp'
265: .Pp
1.7 deraadt 266: The apostrophes ensure the entire expression is evaluated by
1.6 deraadt 267: .Nm grep
268: instead of by the
269: user's shell.
270: The caret
271: .Ql Li \&^
272: matches the null string at the beginning of a line,
273: and the
274: .Ql Li \&\e
275: escapes the
276: .Ql Li \&.
277: which would otherwise match any character.
278: .Pp
279: A simple example of an extended regular expression:
280: .Pp
281: .Dl egrep '19|20|25' calendar
282: .Pp
283: Peruses the file calendar looking for either 19, 20
284: or 25.
1.1 deraadt 285: .Sh SEE ALSO
1.6 deraadt 286: .Xr ed 1 ,
287: .Xr ex 1 ,
288: .Xr sed 1 ,
1.1 deraadt 289: .Xr regex 3 ,
1.7 deraadt 290: .Xr regexp 3 ,
291: .Xr re_format 7
1.1 deraadt 292: .Sh HISTORY
1.6 deraadt 293: The
1.1 deraadt 294: .Nm grep
295: command appeared in
296: .At v6 .