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