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