xref: /freebsd/usr.bin/grep/grep.1 (revision 640235e2c2ba32947f7c59d168437ffa1280f1e6)
1.\"	$NetBSD: grep.1,v 1.2 2011/02/16 01:31:33 joerg Exp $
2.\"	$FreeBSD$
3.\"	$OpenBSD: grep.1,v 1.38 2010/04/05 06:30:59 jmc Exp $
4.\" Copyright (c) 1980, 1990, 1993
5.\"	The Regents of the University of California.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\"	@(#)grep.1	8.3 (Berkeley) 4/18/94
32.\"
33.Dd July 28, 2010
34.Dt GREP 1
35.Os
36.Sh NAME
37.Nm grep , egrep , fgrep ,
38.Nm zgrep , zegrep , zfgrep
39.Nd file pattern searcher
40.Sh SYNOPSIS
41.Nm grep
42.Bk -words
43.Op Fl abcdDEFGHhIiJLlmnOopqRSsUVvwxZ
44.Op Fl A Ar num
45.Op Fl B Ar num
46.Op Fl C Ns Op Ar num
47.Op Fl e Ar pattern
48.Op Fl f Ar file
49.Op Fl Fl binary-files Ns = Ns Ar value
50.Op Fl Fl color Ns Op = Ns Ar when
51.Op Fl Fl colour Ns Op = Ns Ar when
52.Op Fl Fl context Ns Op = Ns Ar num
53.Op Fl Fl label
54.Op Fl Fl line-buffered
55.Op Fl Fl null
56.Op Ar pattern
57.Op Ar
58.Ek
59.Sh DESCRIPTION
60The
61.Nm grep
62utility searches any given input files,
63selecting lines that match one or more patterns.
64By default, a pattern matches an input line if the regular expression
65(RE) in the pattern matches the input line
66without its trailing newline.
67An empty expression matches every line.
68Each input line that matches at least one of the patterns is written
69to the standard output.
70.Pp
71.Nm grep
72is used for simple patterns and
73basic regular expressions
74.Pq BREs ;
75.Nm egrep
76can handle extended regular expressions
77.Pq EREs .
78See
79.Xr re_format 7
80for more information on regular expressions.
81.Nm fgrep
82is quicker than both
83.Nm grep
84and
85.Nm egrep ,
86but can only handle fixed patterns
87(i.e. it does not interpret regular expressions).
88Patterns may consist of one or more lines,
89allowing any of the pattern lines to match a portion of the input.
90.Pp
91.Nm zgrep ,
92.Nm zegrep ,
93and
94.Nm zfgrep
95act like
96.Nm grep ,
97.Nm egrep ,
98and
99.Nm fgrep ,
100respectively, but accept input files compressed with the
101.Xr compress 1
102or
103.Xr gzip 1
104compression utilities.
105.Pp
106The following options are available:
107.Bl -tag -width indent
108.It Fl A Ar num , Fl Fl after-context Ns = Ns Ar num
109Print
110.Ar num
111lines of trailing context after each match.
112See also the
113.Fl B
114and
115.Fl C
116options.
117.It Fl a , Fl Fl text
118Treat all files as ASCII text.
119Normally
120.Nm
121will simply print
122.Dq Binary file ... matches
123if files contain binary characters.
124Use of this option forces
125.Nm
126to output lines matching the specified pattern.
127.It Fl B Ar num , Fl Fl before-context Ns = Ns Ar num
128Print
129.Ar num
130lines of leading context before each match.
131See also the
132.Fl A
133and
134.Fl C
135options.
136.It Fl b , Fl Fl byte-offset
137The offset in bytes of a matched pattern is
138displayed in front of the respective matched line.
139.It Fl C Ns Op Ar num , Fl Fl context Ns = Ns Ar num
140Print
141.Ar num
142lines of leading and trailing context surrounding each match.
143The default is 2 and is equivalent to
144.Fl A
145.Ar 2
146.Fl B
147.Ar 2 .
148Note:
149no whitespace may be given between the option and its argument.
150.It Fl c , Fl Fl count
151Only a count of selected lines is written to standard output.
152.It Fl Fl colour Ns = Ns Op Ar when , Fl Fl color Ns = Ns Op Ar when
153Mark up the matching text with the expression stored in
154.Ev GREP_COLOR
155environment variable.
156The possible values of when can be `never', `always' or `auto'.
157.It Fl D Ar action , Fl Fl devices Ns = Ns Ar action
158Specify the demanded action for devices, FIFOs and sockets.
159The default action is `read', which means, that they are read
160as if they were normal files.
161If the action is set to `skip', devices will be silently skipped.
162.It Fl d Ar action , Fl Fl directories Ns = Ns Ar action
163Specify the demanded action for directories.
164It is `read' by default, which means that the directories
165are read in the same manner as normal files.
166Other possible values are `skip' to silently ignore the
167directories, and `recurse' to read them recursively, which
168has the same effect as the
169.Fl R
170and
171.Fl r
172option.
173.It Fl E , Fl Fl extended-regexp
174Interpret
175.Ar pattern
176as an extended regular expression
177(i.e. force
178.Nm grep
179to behave as
180.Nm egrep ) .
181.It Fl e Ar pattern , Fl Fl regexp Ns = Ns Ar pattern
182Specify a pattern used during the search of the input:
183an input line is selected if it matches any of the specified patterns.
184This option is most useful when multiple
185.Fl e
186options are used to specify multiple patterns,
187or when a pattern begins with a dash
188.Pq Sq - .
189.It Fl Fl exclude
190If specified, it excludes files matching the given
191filename pattern from the search.
192Note that
193.Fl Fl exclude
194patterns take priority over
195.Fl Fl include
196patterns, and if no
197.Fl Fl include
198pattern is specified, all files are searched that are
199not excluded.
200Patterns are matched to the full path specified,
201not only to the filename component.
202.It Fl Fl exclude-dir
203If
204.Fl R
205is specified, it excludes directories matching the
206given filename pattern from the search.
207Note that
208.Fl Fl exclude-dir
209patterns take priority over
210.Fl Fl include-dir
211patterns, and if no
212.Fl Fl include-dir
213pattern is specified, all directories are searched that are
214not excluded.
215.It Fl F , Fl Fl fixed-strings
216Interpret
217.Ar pattern
218as a set of fixed strings
219(i.e. force
220.Nm grep
221to behave as
222.Nm fgrep ) .
223.It Fl f Ar file , Fl Fl file Ns = Ns Ar file
224Read one or more newline separated patterns from
225.Ar file .
226Empty pattern lines match every input line.
227Newlines are not considered part of a pattern.
228If
229.Ar file
230is empty, nothing is matched.
231.It Fl G , Fl Fl basic-regexp
232Interpret
233.Ar pattern
234as a basic regular expression
235(i.e. force
236.Nm grep
237to behave as traditional
238.Nm grep ) .
239.It Fl H
240Always print filename headers with output lines.
241.It Fl h , Fl Fl no-filename
242Never print filename headers
243.Pq i.e. filenames
244with output lines.
245.It Fl Fl help
246Print a brief help message.
247.It Fl I
248Ignore binary files.
249This option is equivalent to
250.Fl Fl binary-file Ns = Ns Ar without-match
251option.
252.It Fl i , Fl Fl ignore-case
253Perform case insensitive matching.
254By default,
255.Nm grep
256is case sensitive.
257.It Fl Fl include
258If specified, only files matching the
259given filename pattern are searched.
260Note that
261.Fl Fl exclude
262patterns take priority over
263.Fl Fl include
264patterns.
265Patterns are matched to the full path specified,
266not only to the filename component.
267.It Fl Fl include-dir
268If
269.Fl R
270is specified, only directories matching the
271given filename pattern are searched.
272Note that
273.Fl Fl exclude-dir
274patterns take priority over
275.Fl Fl include-dir
276patterns.
277.It Fl J, Fl Fl bz2decompress
278Decompress the
279.Xr bzip2 1
280compressed file before looking for the text.
281.It Fl L , Fl Fl files-without-match
282Only the names of files not containing selected lines are written to
283standard output.
284Pathnames are listed once per file searched.
285If the standard input is searched, the string
286.Dq (standard input)
287is written.
288.It Fl l , Fl Fl files-with-matches
289Only the names of files containing selected lines are written to
290standard output.
291.Nm grep
292will only search a file until a match has been found,
293making searches potentially less expensive.
294Pathnames are listed once per file searched.
295If the standard input is searched, the string
296.Dq (standard input)
297is written.
298.It Fl Fl mmap
299Use
300.Xr mmap 2
301instead of
302.Xr read 2
303to read input, which can result in better performance under some
304circumstances but can cause undefined behaviour.
305.It Fl m Ar num, Fl Fl max-count Ns = Ns Ar num
306Stop reading the file after
307.Ar num
308matches.
309.It Fl n , Fl Fl line-number
310Each output line is preceded by its relative line number in the file,
311starting at line 1.
312The line number counter is reset for each file processed.
313This option is ignored if
314.Fl c ,
315.Fl L ,
316.Fl l ,
317or
318.Fl q
319is
320specified.
321.It Fl Fl null
322Prints a zero-byte after the file name.
323.It Fl O
324If
325.Fl R
326is specified, follow symbolic links only if they were explicitly listed
327on the command line.
328The default is not to follow symbolic links.
329.It Fl o, Fl Fl only-matching
330Prints only the matching part of the lines.
331.It Fl p
332If
333.Fl R
334is specified, no symbolic links are followed.
335This is the default.
336.It Fl q , Fl Fl quiet , Fl Fl silent
337Quiet mode:
338suppress normal output.
339.Nm grep
340will only search a file until a match has been found,
341making searches potentially less expensive.
342.It Fl R , Fl r , Fl Fl recursive
343Recursively search subdirectories listed.
344.It Fl S
345If
346.Fl R
347is specified, all symbolic links are followed.
348The default is not to follow symbolic links.
349.It Fl s , Fl Fl no-messages
350Silent mode.
351Nonexistent and unreadable files are ignored
352(i.e. their error messages are suppressed).
353.It Fl U , Fl Fl binary
354Search binary files, but do not attempt to print them.
355.It Fl V , Fl Fl version
356Display version information and exit.
357.It Fl v , Fl Fl invert-match
358Selected lines are those
359.Em not
360matching any of the specified patterns.
361.It Fl w , Fl Fl word-regexp
362The expression is searched for as a word (as if surrounded by
363.Sq [[:<:]]
364and
365.Sq [[:>:]] ;
366see
367.Xr re_format 7 ) .
368.It Fl x , Fl Fl line-regexp
369Only input lines selected against an entire fixed string or regular
370expression are considered to be matching lines.
371.It Fl y
372Equivalent to
373.Fl i .
374Obsoleted.
375.It Fl Z , Fl z , Fl Fl decompress
376Force
377.Nm grep
378to behave as
379.Nm zgrep .
380.It Fl Fl binary-files Ns = Ns Ar value
381Controls searching and printing of binary files.
382Options are
383.Ar binary ,
384the default: search binary files but do not print them;
385.Ar without-match :
386do not search binary files;
387and
388.Ar text :
389treat all files as text.
390.Sm off
391.It Fl Fl context Op = Ar num
392.Sm on
393Print
394.Ar num
395lines of leading and trailing context.
396The default is 2.
397.It Fl Fl line-buffered
398Force output to be line buffered.
399By default, output is line buffered when standard output is a terminal
400and block buffered otherwise.
401.El
402.Pp
403If no file arguments are specified, the standard input is used.
404.Sh EXIT STATUS
405The
406.Nm grep
407utility exits with one of the following values:
408.Pp
409.Bl -tag -width flag -compact
410.It Li 0
411One or more lines were selected.
412.It Li 1
413No lines were selected.
414.It Li \*(Gt1
415An error occurred.
416.El
417.Sh EXAMPLES
418To find all occurrences of the word
419.Sq patricia
420in a file:
421.Pp
422.Dl $ grep 'patricia' myfile
423.Pp
424To find all occurrences of the pattern
425.Ql .Pp
426at the beginning of a line:
427.Pp
428.Dl $ grep '^\e.Pp' myfile
429.Pp
430The apostrophes ensure the entire expression is evaluated by
431.Nm grep
432instead of by the user's shell.
433The caret
434.Ql ^
435matches the null string at the beginning of a line,
436and the
437.Ql \e
438escapes the
439.Ql \&. ,
440which would otherwise match any character.
441.Pp
442To find all lines in a file which do not contain the words
443.Sq foo
444or
445.Sq bar :
446.Pp
447.Dl $ grep -v -e 'foo' -e 'bar' myfile
448.Pp
449A simple example of an extended regular expression:
450.Pp
451.Dl $ egrep '19|20|25' calendar
452.Pp
453Peruses the file
454.Sq calendar
455looking for either 19, 20, or 25.
456.Sh SEE ALSO
457.Xr ed 1 ,
458.Xr ex 1 ,
459.Xr gzip 1 ,
460.Xr sed 1 ,
461.Xr re_format 7
462.Sh STANDARDS
463The
464.Nm
465utility is compliant with the
466.St -p1003.1-2008
467specification.
468.Pp
469The flags
470.Op Fl AaBbCDdGHhIJLmoPRSUVwZ
471are extensions to that specification, and the behaviour of the
472.Fl f
473flag when used with an empty pattern file is left undefined.
474.Pp
475All long options are provided for compatibility with
476GNU versions of this utility.
477.Pp
478Historic versions of the
479.Nm grep
480utility also supported the flags
481.Op Fl ruy .
482This implementation supports those options;
483however, their use is strongly discouraged.
484.Sh HISTORY
485The
486.Nm grep
487command first appeared in
488.At v6 .
489