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