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