Annotation of src/usr.bin/grep/grep.1, Revision 1.36
1.36 ! jmc 1: .\" $OpenBSD: grep.1,v 1.35 2007/05/31 19:20:10 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: .\"
1.36 ! jmc 31: .Dd $Mdocdate: May 31 2007 $
1.1 deraadt 32: .Dt GREP 1
33: .Os
34: .Sh NAME
1.27 jmc 35: .Nm grep , egrep , fgrep ,
36: .Nm zgrep , zegrep , zfgrep
1.6 deraadt 37: .Nd file pattern searcher
1.1 deraadt 38: .Sh SYNOPSIS
39: .Nm grep
1.27 jmc 40: .Bk -words
41: .Op Fl abcEFGHhIiLlnoPqRSsUVvwxZ
42: .Op Fl A Ar num
43: .Op Fl B Ar num
44: .Op Fl C Ns Op Ar num
45: .Op Fl e Ar pattern
46: .Op Fl f Ar file
47: .Op Fl -binary-files Ns = Ns Ar value
1.12 tedu 48: .Op Fl -context Ns Op = Ns Ar num
1.24 otto 49: .Op Fl -line-buffered
1.21 mcbride 50: .Op Ar pattern
1.6 deraadt 51: .Op Ar
1.27 jmc 52: .Ek
1.1 deraadt 53: .Sh DESCRIPTION
54: The
1.6 deraadt 55: .Nm grep
1.27 jmc 56: utility searches any given input files,
57: selecting lines that match one or more patterns.
58: By default, a pattern matches an input line if the regular expression
59: (RE) in the pattern matches the input line
60: without its trailing newline.
1.6 deraadt 61: An empty expression matches every line.
62: Each input line that matches at least one of the patterns is written
63: to the standard output.
1.1 deraadt 64: .Pp
1.6 deraadt 65: .Nm grep
1.27 jmc 66: is used for simple patterns and
1.29 jmc 67: basic regular expressions
68: .Pq BREs ;
1.1 deraadt 69: .Nm egrep
1.29 jmc 70: can handle extended regular expressions
71: .Pq EREs .
72: See
73: .Xr re_format 7
74: for more information on regular expressions.
1.1 deraadt 75: .Nm fgrep
1.27 jmc 76: is quicker than both
77: .Nm grep
78: and
79: .Nm egrep ,
80: but can only handle fixed patterns
81: (i.e. it does not interpret regular expressions).
82: Patterns may consist of one or more lines,
83: allowing any of the pattern lines to match a portion of the input.
84: .Pp
1.7 deraadt 85: .Nm zgrep ,
86: .Nm zegrep ,
87: and
88: .Nm zfgrep
1.27 jmc 89: act like
1.7 deraadt 90: .Nm grep ,
91: .Nm egrep ,
92: and
1.27 jmc 93: .Nm fgrep ,
94: respectively, but accept input files compressed with the
1.6 deraadt 95: .Xr compress 1
96: or
97: .Xr gzip 1
98: compression utilities.
1.1 deraadt 99: .Pp
1.6 deraadt 100: The following options are available:
101: .Bl -tag -width indent
102: .It Fl A Ar num
1.7 deraadt 103: Print
1.6 deraadt 104: .Ar num
105: lines of trailing context after each match.
1.27 jmc 106: See also the
107: .Fl B
108: and
109: .Fl C
110: options.
111: .It Fl a
112: Treat all files as ASCII text.
1.30 jmc 113: Normally
114: .Nm
115: will simply print
116: .Dq Binary file ... matches
117: if files contain binary characters.
118: Use of this option forces
119: .Nm
120: to output lines matching the specified pattern.
1.6 deraadt 121: .It Fl B Ar num
1.7 deraadt 122: Print
123: .Ar num
1.6 deraadt 124: lines of leading context before each match.
1.27 jmc 125: See also the
126: .Fl A
127: and
128: .Fl C
129: options.
130: .It Fl b
131: The offset in bytes of a matched pattern is
132: displayed in front of the respective matched line.
133: .It Fl C Ns Op Ar num
134: Print
135: .Ar num
136: lines of leading and trailing context surrounding each match.
137: The default is 2 and is equivalent to
1.6 deraadt 138: .Fl A
139: .Ar 2
140: .Fl B
141: .Ar 2 .
1.27 jmc 142: Note:
143: no whitespace may be given between the option and its argument.
144: .It Fl c
145: Only a count of selected lines is written to standard output.
1.1 deraadt 146: .It Fl E
1.27 jmc 147: Interpret
148: .Ar pattern
149: as an extended regular expression
150: (i.e. force
1.7 deraadt 151: .Nm grep
152: to behave as
1.27 jmc 153: .Nm egrep ) .
154: .It Fl e Ar pattern
155: Specify a pattern used during the search of the input:
156: an input line is selected if it matches any of the specified patterns.
157: This option is most useful when multiple
158: .Fl e
159: options are used to specify multiple patterns,
160: or when a pattern begins with a dash
161: .Pq Sq - .
1.1 deraadt 162: .It Fl F
1.27 jmc 163: Interpret
164: .Ar pattern
165: as a set of fixed strings
166: (i.e. force
1.6 deraadt 167: .Nm grep
1.7 deraadt 168: to behave as
1.27 jmc 169: .Nm fgrep ) .
170: .It Fl f Ar file
171: Read one or more newline separated patterns from
172: .Ar file .
1.33 kili 173: Empty pattern lines match every input line.
1.27 jmc 174: Newlines are not considered part of a pattern.
1.33 kili 175: If
176: .Ar file
177: is empty, nothing is matched.
1.6 deraadt 178: .It Fl G
1.27 jmc 179: Interpret
180: .Ar pattern
181: as a basic regular expression
182: (i.e. force
1.6 deraadt 183: .Nm grep
1.27 jmc 184: to behave as traditional
185: .Nm grep ) .
1.6 deraadt 186: .It Fl H
1.7 deraadt 187: If
1.6 deraadt 188: .Fl R
1.20 jmc 189: is specified, follow symbolic links only if they were explicitly listed
1.6 deraadt 190: on the command line.
1.27 jmc 191: The default is not to follow symbolic links.
192: .It Fl h
193: Never print filename headers
194: .Pq i.e. filenames
195: with output lines.
1.10 tedu 196: .It Fl I
197: Ignore binary files.
1.27 jmc 198: .It Fl i
199: Perform case insensitive matching.
200: By default,
201: .Nm grep
202: is case sensitive.
1.6 deraadt 203: .It Fl L
204: Only the names of files not containing selected lines are written to
205: standard output.
206: Pathnames are listed once per file searched.
1.28 jmc 207: If the standard input is searched, the string
208: .Dq (standard input)
1.6 deraadt 209: is written.
1.1 deraadt 210: .It Fl l
1.6 deraadt 211: Only the names of files containing selected lines are written to
1.7 deraadt 212: standard output.
1.27 jmc 213: .Nm grep
214: will only search a file until a match has been found,
215: making searches potentially less expensive.
1.7 deraadt 216: Pathnames are listed once per file searched.
1.28 jmc 217: If the standard input is searched, the string
218: .Dq (standard input)
1.6 deraadt 219: is written.
1.1 deraadt 220: .It Fl n
1.6 deraadt 221: Each output line is preceded by its relative line number in the file,
222: starting at line 1.
223: The line number counter is reset for each file processed.
224: This option is ignored if
225: .Fl c ,
1.27 jmc 226: .Fl L ,
1.6 deraadt 227: .Fl l ,
228: or
1.32 jmc 229: .Fl q
1.6 deraadt 230: is
231: specified.
232: .It Fl o
233: Always print filename headers with output lines.
1.27 jmc 234: .It Fl P
235: If
236: .Fl R
237: is specified, no symbolic links are followed.
238: This is the default.
1.1 deraadt 239: .It Fl q
1.27 jmc 240: Quiet mode:
241: suppress normal output.
242: .Nm grep
243: will only search a file until a match has been found,
244: making searches potentially less expensive.
245: .It Fl R
246: Recursively search subdirectories listed.
247: .It Fl S
248: If
249: .Fl R
250: is specified, all symbolic links are followed.
251: The default is not to follow symbolic links.
1.1 deraadt 252: .It Fl s
1.7 deraadt 253: Silent mode.
1.27 jmc 254: Nonexistent and unreadable files are ignored
255: (i.e. their error messages are suppressed).
256: .It Fl U
257: Search binary files, but do not attempt to print them.
258: .It Fl V
259: Display version information.
260: All other options are ignored.
1.1 deraadt 261: .It Fl v
1.6 deraadt 262: Selected lines are those
263: .Em not
1.14 dhartmei 264: matching any of the specified patterns.
1.1 deraadt 265: .It Fl w
1.27 jmc 266: The expression is searched for as a word (as if surrounded by
267: .Sq [[:<:]]
268: and
269: .Sq [[:>:]] ;
270: see
1.26 jmc 271: .Xr re_format 7 ) .
1.1 deraadt 272: .It Fl x
1.6 deraadt 273: Only input lines selected against an entire fixed string or regular
274: expression are considered to be matching lines.
1.27 jmc 275: .It Fl Z
276: Force
277: .Nm grep
278: to behave as
279: .Nm zgrep .
280: .It Fl Fl binary-files Ns = Ns Ar value
281: Controls searching and printing of binary files.
282: Options are
283: .Ar binary ,
284: the default: search binary files but do not print them;
285: .Ar without-match :
286: do not search binary files;
287: and
288: .Ar text :
289: treat all files as text.
1.12 tedu 290: .Sm off
291: .It Fl Fl context Op = Ar num
292: .Sm on
293: Print
294: .Ar num
295: lines of leading and trailing context.
1.27 jmc 296: The default is 2.
1.24 otto 297: .It Fl Fl line-buffered
298: Force output to be line buffered.
299: By default, output is line buffered when standard output is a terminal
300: and block buffered otherwise.
1.6 deraadt 301: .Pp
1.1 deraadt 302: .El
1.6 deraadt 303: If no file arguments are specified, the standard input is used.
1.7 deraadt 304: .Sh RETURN VALUES
1.1 deraadt 305: The
1.6 deraadt 306: .Nm grep
1.1 deraadt 307: utility exits with one of the following values:
308: .Pp
309: .Bl -tag -width flag -compact
1.6 deraadt 310: .It Li 0
311: One or more lines were selected.
312: .It Li 1
313: No lines were selected.
1.27 jmc 314: .It Li \*(Gt1
1.6 deraadt 315: An error occurred.
1.4 jmc 316: .El
1.6 deraadt 317: .Sh EXAMPLES
1.27 jmc 318: To find all occurrences of the word
319: .Sq patricia
320: in a file:
1.6 deraadt 321: .Pp
1.27 jmc 322: .Dl $ grep 'patricia' myfile
1.6 deraadt 323: .Pp
324: To find all occurrences of the pattern
1.27 jmc 325: .Ql .Pp
1.6 deraadt 326: at the beginning of a line:
327: .Pp
1.27 jmc 328: .Dl $ grep '^\e.Pp' myfile
1.6 deraadt 329: .Pp
1.7 deraadt 330: The apostrophes ensure the entire expression is evaluated by
1.6 deraadt 331: .Nm grep
1.27 jmc 332: instead of by the user's shell.
1.6 deraadt 333: The caret
1.27 jmc 334: .Ql ^
1.6 deraadt 335: matches the null string at the beginning of a line,
336: and the
1.27 jmc 337: .Ql \e
1.6 deraadt 338: escapes the
1.27 jmc 339: .Ql \&. ,
1.6 deraadt 340: which would otherwise match any character.
1.21 mcbride 341: .Pp
1.27 jmc 342: To find all lines in a file which do not contain the words
343: .Sq foo
344: or
345: .Sq bar :
1.21 mcbride 346: .Pp
1.27 jmc 347: .Dl $ grep -v -e 'foo' -e 'bar' myfile
1.6 deraadt 348: .Pp
349: A simple example of an extended regular expression:
350: .Pp
1.27 jmc 351: .Dl $ egrep '19|20|25' calendar
1.6 deraadt 352: .Pp
1.27 jmc 353: Peruses the file
354: .Sq calendar
355: looking for either 19, 20, or 25.
1.1 deraadt 356: .Sh SEE ALSO
1.6 deraadt 357: .Xr ed 1 ,
358: .Xr ex 1 ,
1.27 jmc 359: .Xr gzip 1 ,
1.6 deraadt 360: .Xr sed 1 ,
1.7 deraadt 361: .Xr re_format 7
1.27 jmc 362: .Sh STANDARDS
363: The
1.34 jmc 364: .Nm
1.27 jmc 365: utility is compliant with the
1.36 ! jmc 366: .St -p1003.1-2008
1.27 jmc 367: specification.
368: .Pp
369: The flags
370: .Op Fl AaBbCGHhILoPRSUVwZ
1.33 kili 371: are extensions to that specification, and the behaviour of the
372: .Fl f
373: flag when used with an empty pattern file is left undefined.
1.27 jmc 374: .Pp
375: All long options are provided for compatibility with
376: GNU versions of this utility.
377: .Pp
378: Historic versions of the
379: .Nm grep
380: utility also supported the flags
381: .Op Fl ruy .
382: This implementation supports those options;
383: however, their use is strongly discouraged.
1.1 deraadt 384: .Sh HISTORY
1.6 deraadt 385: The
1.1 deraadt 386: .Nm grep
1.27 jmc 387: command first appeared in
1.1 deraadt 388: .At v6 .