Annotation of src/usr.bin/grep/grep.1, Revision 1.3
1.3 ! jmc 1: .\" $OpenBSD: grep.1,v 1.2 2002/11/09 02:22:33 fgsch Exp $
1.1 deraadt 2: .\"
3: .\" Copyright (c) 2000 Carson Harding. All rights reserved.
4: .\" This code was written and contributed to OpenBSD by Carson Harding.
5: .\"
6: .\" Redistribution and use in source and binary forms, with or without
7: .\" modification, are permitted provided that the following conditions
8: .\" are met:
9: .\" 1. Redistributions of source code must retain the above copyright
10: .\" notice, this list of conditions and the following disclaimer.
11: .\" 2. Redistributions in binary form must reproduce the above copyright
12: .\" notice, this list of conditions and the following disclaimer in the
13: .\" documentation and/or other materials provided with the distribution.
14: .\" 3. Neither the name of the author, or the names of contributors may be
15: .\" used to endorse or promote products derived from this software without
16: .\" specific prior written permission.
17: .\"
18: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28: .\" SUCH DAMAGE.
29: .\"
30: .Dd May 10, 2001
31: .Dt GREP 1
32: .Os
33: .Sh NAME
34: .Nm grep , egrep , fgrep
35: .Nd print lines matching a pattern
36: .Sh SYNOPSIS
37: .Nm grep
38: .Op Fl E | Fl F
39: .Op Fl bchilnqsvwxz
40: .Oo
41: .Fl RXH
42: .Op Fl L | Fl P
43: .Oc
44: .Op Fl e Ar pattern_list
45: .Op Fl f Ar pattern_file
46: .Op Ar pattern
47: .Op Ar file
48: .Ar ...
49: .Sh DESCRIPTION
50: The
51: .Nm
52: utility searches for lines that contain the specified pattern
53: or patterns. By default
54: .Nm
55: prints lines containing matches to the standard output. If no input files
56: are specified,
57: .Nm
58: expects to read its input from the standard input.
59: .Pp
60: .Nm egrep
61: is equivalent to
62: .Nm grep
63: .Fl E ;
64: .Nm fgrep
65: is equivalent to
66: .Nm grep
67: .Fl F .
68: .Pp
69: The patterns are regular expressions, or in the case of
70: .Nm fgrep ,
71: fixed strings. More than one pattern may be specified on the
72: command-line, either by repeated use of the
73: .Fl e
74: flag, or by separating patterns with newlines:
75:
76: .Nm grep
77: \'Ishmael
78: Ahab' mobydick.txt
79:
80: is the same as:
81:
82: .Nm
83: -e Ishmael -e Ahab mobydick.txt
84:
85: Note that many regular expression special characters also have special
86: meaning to the shell. It is best to enclose the regular expression
87: in quotation marks. Note also that a null pattern ("" or a newline alone)
88: matches all input.
89: .Sh OPTIONS
90: .Pp
91: The options available are:
92: .Bl -tag -width file Ds
93: .It Fl E
94: Use extended regular expressions, as if the program was invoked as
95: .Nm egrep.
96: .It Fl F
97: Patterns are fixed strings, not regular expressions, as if the
98: program was invoked as
99: .Nm fgrep.
100: .It Fl a
101: Does nothing. In other greps this flag tells grep to treat the input
1.3 ! jmc 102: as ASCII and turns off attempts to determine whether the input file is a
1.1 deraadt 103: binary file. This
104: .Nm grep
105: does not (yet) do that check, so behaves as if
106: .Fl a
107: is always specified.
108: .It Fl b
109: Prepend the byte-offset of the beginning of the line containing the match.
110: .It Fl c
111: Print only a count of the matches found.
112: .It Fl e Ar pattern_list
113: The argument to
114: .Fl e
115: is a list of patterns to search for.
116: .Fl e
117: may be used multiple times, each instance of which may have
118: one or more patterns separated by new-lines.
119: .It Fl f Ar pattern_file
120: The argument to
121: .Fl f
122: is the name of a file from which to read patterns.
123: .Fl f
124: may be more than once.
125: .It Fl h
126: Suppress the prefixing of file names to matching lines when multiple
127: files are searched.
128: .It Fl i
129: Ignore case in comparisons.
130: .It Fl l
131: Print only a list of the names of files in which matches were found.
132: If the input is the standard input,
133: .Nm
134: prints "(standard input)".
135: .It Fl n
136: Prefix matching lines with their line number in the file in which
137: they occur.
138: .It Fl q
139: Be quiet about errors accessing files, only return program status.
140: The status returned is 0 if there was a match, 1 if there were no
141: matches, even if there were errors accessing files. (Without the
142: .Fl q
143: flag, if there was an error
144: accessing a file
145: .Nm
146: would return a status of 2 even
147: if it found matches.)
148: .It Fl s
149: Suppress errors about accessing files. Note that unlike
150: .Fl q
151: the program is not quiet: matches are still output.
152: .It Fl v
153: Invert the sense of the match: return all lines that do not
154: contain the pattern.
155: .It Fl w
156: The pattern is considered a word. A matching pattern in a line must not
157: be immediately bordered by a letter, a number, or an underscore ('_').
158: .It Fl x
159: Match the line exactly. If a regular expression (invoked as
160: .Nm grep ,
161: or
162: .Nm egrep )
163: the pattern must match the whole line (as if
164: the pattern was enclosed in ^ and $). If invoked as
165: .Nm fgrep,
166: the string must match the entire line.
167: .It Fl z
168: When the
169: .Fl l
170: flag is also specified, print an ASCII NUL character (0) following
171: the file name, rather than a newline. Like the
172: .Fl print0
173: option to
174: .Nm find ,
175: this may be used to pass file names containing unusual characters
176: to programs such as
177: .Nm xargs
178: with the
179: .Fl 0
180: flag.
181: .El
182: .Sh FILESYSTEM TRAVERSAL OPTIONS
183: .Pp
184: The following options control recursive searchs:
185: .Bl -tag -width file Ds
186: .It Fl R
187: Recursively descend through any specified directory arguments.
188: .It Fl H
189: If the
190: .Fl R
191: option is also specified, symbolic links on the command
192: line are followed. (Symbolic links encountered in the tree
193: traversal are not followed.)
194: .It Fl L
195: If the
196: .Fl R
197: option is also specified, all symbolic links are followed.
198: .It Fl P
199: If the
200: .Fl R
201: option is also specified, no symbolic links are followed.
202: .It Fl X
203: If the
204: .Fl R
205: option is also specified, searches are confined to the device on
206: which the search started (file system mount points are not crossed).
207: .El
208: .Sh EXAMPLES
209: .Pp
210: To print all occurrences of the word Ishmael in mobydick.txt:
211: .Dl grep Ishmael mobydick.txt
212: .Pp
213: To merely count all the lines in which the word Ishmael occurs:
214: .Dl grep -c Ishmael mobydick.txt
215: .Pp
216: To print all occurrences of either of the words Ishmael or Ahab in
217: mobydick.txt:
218: .Dl grep 'Ishmael|Ahab' mobydick.txt
219: .Pp
220: To print all occurrences of the word whale in mobydick.txt, whether
221: or not it is capitalised, and where it appears alone and not as part
222: of a compound:
223: .Dl grep -iw whale mobydick.txt
224: .Pp
225: To find all the empty lines and print the line numbers for where they occur:
226: .Dl grep -nv \&. mobydick.txt
227: .Sh DIAGNOSTICS
228: .Pp
229: The
230: .Nm
231: utility exits with one of the following values:
232: .Pp
233: .Bl -tag -width flag -compact
234: .It 0
235: One or more matching lines was found.
236: .It 1
237: No matches were found.
238: .It 2
239: An error occurred (whether or not matches were found).
240: .Pp
241: Note that when the
242: .Fl q
243: flag is used, file access errors do not cause an exit value of 2,
244: and in the absence of other errors (a bad regular expression)
245: the exit value is determined only by whether or not matches
246: were found. (XX Should -s do the same??)
247: .Sh SEE ALSO
248: .Xr regex 3 ,
1.2 fgsch 249: .Xr re_format 7
1.1 deraadt 250: .Sh HISTORY
251: A
252: .Nm grep
253: command appeared in
254: .At v6 .
255: This version is a re-implementation from the POSIX specification and
256: inspection of the operation of several implementations of
257: .Nm grep .
258: .Sh NOTES
259: .Nm grep
260: has no limits on input line length (other than imposed by available
261: memory).
![[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