Annotation of src/usr.bin/grep/grep.1, Revision 1.12
1.12 ! tedu 1: .\" $OpenBSD: grep.1,v 1.11 2003/06/23 02:02:41 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: .\"
31: .Dd July 3, 1999
1.1 deraadt 32: .Dt GREP 1
33: .Os
34: .Sh NAME
1.7 deraadt 35: .Nm grep, egrep, fgrep, zgrep, zegrep, zfgrep
1.6 deraadt 36: .Nd file pattern searcher
1.1 deraadt 37: .Sh SYNOPSIS
38: .Nm grep
1.6 deraadt 39: .Op Fl AB Ar num
1.10 tedu 40: .Op Fl CEFGHILPRSUVZabchilnoqsvwx
1.12 ! tedu 41: .Op Fl -context Ns Op = Ns Ar num
! 42: .Op Fl -binary-files Ns = Ns Ar value
1.6 deraadt 43: .Op Fl e Ar pattern
44: .Op Fl f Ar file
45: .Op Ar
1.1 deraadt 46: .Sh DESCRIPTION
47: The
1.6 deraadt 48: .Nm grep
49: utilities search the given input files selecting lines that match one
50: or more patterns.
51: By default, a pattern matches an input line if any regular expression
52: (RE) in the pattern matches the input line without its trailing
53: newline.
54: An empty expression matches every line.
55: Each input line that matches at least one of the patterns is written
56: to the standard output.
1.1 deraadt 57: .Pp
1.6 deraadt 58: The
59: .Nm grep
60: utility is used for simple patterns and
61: .Xr ex 1
62: or
63: .Xr ed 1
64: style regular expressions.
65: The
1.1 deraadt 66: .Nm egrep
1.6 deraadt 67: utility can handle extended regular expressions and multi-line
68: patterns.
69: The
1.1 deraadt 70: .Nm fgrep
1.6 deraadt 71: utility is quick but can handle only fixed patterns consisting of one
72: or more lines, allowing any of the pattern lines to match a portion of
73: the input.
74: The
1.7 deraadt 75: .Nm zgrep ,
76: .Nm zegrep ,
77: and
78: .Nm zfgrep
1.11 tedu 79: utilities act like
1.7 deraadt 80: .Nm grep ,
81: .Nm egrep ,
82: and
83: .Nm fgrep
1.11 tedu 84: respectively but accept input files compressed with the
1.6 deraadt 85: .Xr compress 1
86: or
87: .Xr gzip 1
88: compression utilities.
1.1 deraadt 89: .Pp
1.6 deraadt 90: The following options are available:
1.5 jmc 91: .Pp
1.6 deraadt 92: .Bl -tag -width indent
93: .It Fl A Ar num
1.7 deraadt 94: Print
1.6 deraadt 95: .Ar num
96: lines of trailing context after each match.
97: .It Fl B Ar num
1.7 deraadt 98: Print
99: .Ar num
1.6 deraadt 100: lines of leading context before each match.
101: .It Fl C
1.7 deraadt 102: Equivalent to
1.6 deraadt 103: .Fl A
104: .Ar 2
105: .Fl B
106: .Ar 2 .
1.1 deraadt 107: .It Fl E
1.7 deraadt 108: Force
109: .Nm grep
110: to behave as
111: .Nm egrep .
1.1 deraadt 112: .It Fl F
1.7 deraadt 113: Force
1.6 deraadt 114: .Nm grep
1.7 deraadt 115: to behave as
116: .Nm fgrep .
1.6 deraadt 117: .It Fl G
1.7 deraadt 118: Force
1.6 deraadt 119: .Nm grep
1.7 deraadt 120: to behave as
121: .Nm grep .
1.6 deraadt 122: .It Fl H
1.7 deraadt 123: If
1.6 deraadt 124: .Fl R
125: is specified, follow symbolic links only if they were explictly listed
126: on the command line.
1.10 tedu 127: .It Fl I
128: Ignore binary files.
1.6 deraadt 129: .It Fl L
130: Only the names of files not containing selected lines are written to
131: standard output.
132: Pathnames are listed once per file searched.
133: If the standard input is searched, the pathname
134: .Sq Fl
135: is written.
136: .It Fl P
1.7 deraadt 137: If
1.6 deraadt 138: .Fl R
139: is specified, no symbolic links are followed.
140: .It Fl R
141: Recursively search subdirectories listed.
142: .It Fl S
1.7 deraadt 143: If
1.6 deraadt 144: .Fl R
145: is specified, all symbolic links are followed.
1.10 tedu 146: .It Fl U
147: Search binary files, but do not attempt to print them.
1.6 deraadt 148: .It Fl V
149: Display version information.
150: .It Fl Z
151: Force
152: .Nm grep
153: to behave as
154: .Nm zgrep .
1.1 deraadt 155: .It Fl a
1.10 tedu 156: Treat all files as text.
1.1 deraadt 157: .It Fl b
1.6 deraadt 158: The block number on the disk in which a matched pattern is located is
159: displayed in front of the respective matched line.
1.1 deraadt 160: .It Fl c
1.6 deraadt 161: Only a count of selected lines is written to standard output.
1.7 deraadt 162: .It Fl e Ar expression
163: Specify a pattern used during the search of the input.
164: Multiple
1.1 deraadt 165: .Fl e
1.6 deraadt 166: options can be used to specify multiple patterns; an input line is
167: selected if it matches any of the specified patterns.
1.7 deraadt 168: .It Fl f Ar pattern_file
169: The pattern is read from the specified file.
170: Trailing newlines in the pattern file are ignored.
1.6 deraadt 171: .Pf ( Nm Egrep
172: and
173: .Nm fgrep
174: only).
1.1 deraadt 175: .It Fl h
1.6 deraadt 176: Never print filename headers with output lines.
1.1 deraadt 177: .It Fl i
1.6 deraadt 178: Perform case insensitive matching.
1.1 deraadt 179: .It Fl l
1.6 deraadt 180: Only the names of files containing selected lines are written to
1.7 deraadt 181: standard output.
182: Pathnames are listed once per file searched.
183: If the standard input is searched, the pathname
1.6 deraadt 184: .Sq -
185: is written.
1.1 deraadt 186: .It Fl n
1.6 deraadt 187: Each output line is preceded by its relative line number in the file,
188: starting at line 1.
189: The line number counter is reset for each file processed.
190: This option is ignored if
191: .Fl c ,
192: .Fl l ,
193: or
194: .Fl s
195: is
196: specified.
197: .It Fl o
198: Always print filename headers with output lines.
1.1 deraadt 199: .It Fl q
1.6 deraadt 200: Suppress normal output.
1.1 deraadt 201: .It Fl s
1.7 deraadt 202: Silent mode.
203: Nonexistent and unreadable files are ignored.
1.1 deraadt 204: .It Fl v
1.6 deraadt 205: Selected lines are those
206: .Em not
207: matching the specified
208: patterns.
1.1 deraadt 209: .It Fl w
1.6 deraadt 210: The expression is searched for as a word (as if surrounded by `\e<'
211: and `\e>', see
212: .Xr ex 1 ) .
1.1 deraadt 213: .It Fl x
1.6 deraadt 214: Only input lines selected against an entire fixed string or regular
215: expression are considered to be matching lines.
1.12 ! tedu 216: .Sm off
! 217: .It Fl Fl context Op = Ar num
! 218: .Sm on
! 219: Print
! 220: .Ar num
! 221: lines of leading and trailing context.
! 222: Default is 2.
! 223: .Sm off
! 224: .It Fl Fl binary-files No = Ar value
! 225: .Sm on
! 226: Controls searching and printing of binary files.
! 227: Options are
! 228: .Ar binary ,
! 229: the default, search binary files but do not print them;
! 230: .Ar without-match ,
! 231: do not search binary files;
! 232: and
! 233: .Ar text ,
! 234: treat all files as text.
1.6 deraadt 235: .Pp
1.1 deraadt 236: .El
1.6 deraadt 237: If no file arguments are specified, the standard input is used.
1.7 deraadt 238: .Sh RETURN VALUES
1.1 deraadt 239: The
1.6 deraadt 240: .Nm grep
1.1 deraadt 241: utility exits with one of the following values:
242: .Pp
243: .Bl -tag -width flag -compact
1.6 deraadt 244: .It Li 0
245: One or more lines were selected.
246: .It Li 1
247: No lines were selected.
248: .It Li >1
249: An error occurred.
1.4 jmc 250: .El
1.6 deraadt 251: .Sh EXTENDED REGULAR EXPRESSIONS
252: The following characters are interpreted by
253: .Nm egrep :
1.1 deraadt 254: .Pp
1.6 deraadt 255: .Bl -tag -width flag -compact
256: .It Cm \&$
257: Align the match from the end of the line.
258: .It Cm \&^
259: Align the match from the beginning of the line.
260: .It Cm \&|
261: Add another pattern (see example below).
262: .It Cm \&?
263: Match 1 or less sequential repetitions of the pattern.
264: .It Cm \&+
265: Match 1 or more sequential repetitions of the pattern.
266: .It Cm \&*
267: Match 0 or more sequential repetitions of the pattern.
268: .It Cm \&[]
269: Match any single character or range of characters
270: enclosed in the brackets.
271: .It Cm \&\e
272: Escape special characters which have meaning to
273: .Nm egrep ,
274: the set of {$,.,^,[,],|,?,+,*,(,)}.
275: .El
276: .Sh EXAMPLES
277: To find all occurrences of the word patricia in a file:
278: .Pp
279: .Dl grep patricia myfile
280: .Pp
281: To find all occurrences of the pattern
282: .Ql \&.Pp
283: at the beginning of a line:
284: .Pp
285: .Dl grep '^\e.Pp'
286: .Pp
1.7 deraadt 287: The apostrophes ensure the entire expression is evaluated by
1.6 deraadt 288: .Nm grep
289: instead of by the
290: user's shell.
291: The caret
292: .Ql Li \&^
293: matches the null string at the beginning of a line,
294: and the
295: .Ql Li \&\e
296: escapes the
297: .Ql Li \&.
298: which would otherwise match any character.
299: .Pp
300: A simple example of an extended regular expression:
301: .Pp
302: .Dl egrep '19|20|25' calendar
303: .Pp
304: Peruses the file calendar looking for either 19, 20
305: or 25.
1.1 deraadt 306: .Sh SEE ALSO
1.6 deraadt 307: .Xr ed 1 ,
308: .Xr ex 1 ,
309: .Xr sed 1 ,
1.1 deraadt 310: .Xr regex 3 ,
1.7 deraadt 311: .Xr regexp 3 ,
312: .Xr re_format 7
1.1 deraadt 313: .Sh HISTORY
1.6 deraadt 314: The
1.1 deraadt 315: .Nm grep
316: command appeared in
317: .At v6 .