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