xref: /freebsd/usr.bin/grep/grep.1 (revision d93a896ef95946b0bf1219866fcb324b78543444)
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 April 17, 2017
34.Dt GREP 1
35.Os
36.Sh NAME
37.Nm grep , egrep , fgrep , rgrep ,
38.Nm zgrep , zegrep , zfgrep
39.Nd file pattern searcher
40.Sh SYNOPSIS
41.Nm grep
42.Bk -words
43.Op Fl abcdDEFGHhIiJLlmnOopqRSsUVvwxZz
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(i.e. force
345.Nm grep
346to behave as
347.Nm rgrep ) .
348.It Fl S
349If
350.Fl R
351is specified, all symbolic links are followed.
352The default is not to follow symbolic links.
353.It Fl s , Fl Fl no-messages
354Silent mode.
355Nonexistent and unreadable files are ignored
356(i.e. their error messages are suppressed).
357.It Fl U , Fl Fl binary
358Search binary files, but do not attempt to print them.
359.It Fl u
360This option has no effect and is provided only for compatibility with GNU grep.
361.It Fl V , Fl Fl version
362Display version information and exit.
363.It Fl v , Fl Fl invert-match
364Selected lines are those
365.Em not
366matching any of the specified patterns.
367.It Fl w , Fl Fl word-regexp
368The expression is searched for as a word (as if surrounded by
369.Sq [[:<:]]
370and
371.Sq [[:>:]] ;
372see
373.Xr re_format 7 ) .
374.It Fl x , Fl Fl line-regexp
375Only input lines selected against an entire fixed string or regular
376expression are considered to be matching lines.
377.It Fl y
378Equivalent to
379.Fl i .
380Obsoleted.
381.It Fl z , Fl Fl null-data
382Treat input and output data as sequences of lines terminated by a
383zero-byte instead of a newline.
384.It Fl Z , Fl Fl decompress
385Force
386.Nm grep
387to behave as
388.Nm zgrep .
389.It Fl Fl binary-files Ns = Ns Ar value
390Controls searching and printing of binary files.
391Options are
392.Ar binary ,
393the default: search binary files but do not print them;
394.Ar without-match :
395do not search binary files;
396and
397.Ar text :
398treat all files as text.
399.Sm off
400.It Fl Fl context Op = Ar num
401.Sm on
402Print
403.Ar num
404lines of leading and trailing context.
405The default is 2.
406.It Fl Fl line-buffered
407Force output to be line buffered.
408By default, output is line buffered when standard output is a terminal
409and block buffered otherwise.
410.El
411.Pp
412If no file arguments are specified, the standard input is used.
413.Sh EXIT STATUS
414The
415.Nm grep
416utility exits with one of the following values:
417.Pp
418.Bl -tag -width flag -compact
419.It Li 0
420One or more lines were selected.
421.It Li 1
422No lines were selected.
423.It Li \*(Gt1
424An error occurred.
425.El
426.Sh EXAMPLES
427To find all occurrences of the word
428.Sq patricia
429in a file:
430.Pp
431.Dl $ grep 'patricia' myfile
432.Pp
433To find all occurrences of the pattern
434.Ql .Pp
435at the beginning of a line:
436.Pp
437.Dl $ grep '^\e.Pp' myfile
438.Pp
439The apostrophes ensure the entire expression is evaluated by
440.Nm grep
441instead of by the user's shell.
442The caret
443.Ql ^
444matches the null string at the beginning of a line,
445and the
446.Ql \e
447escapes the
448.Ql \&. ,
449which would otherwise match any character.
450.Pp
451To find all lines in a file which do not contain the words
452.Sq foo
453or
454.Sq bar :
455.Pp
456.Dl $ grep -v -e 'foo' -e 'bar' myfile
457.Pp
458A simple example of an extended regular expression:
459.Pp
460.Dl $ egrep '19|20|25' calendar
461.Pp
462Peruses the file
463.Sq calendar
464looking for either 19, 20, or 25.
465.Sh SEE ALSO
466.Xr ed 1 ,
467.Xr ex 1 ,
468.Xr gzip 1 ,
469.Xr sed 1 ,
470.Xr re_format 7
471.Sh STANDARDS
472The
473.Nm
474utility is compliant with the
475.St -p1003.1-2008
476specification.
477.Pp
478The flags
479.Op Fl AaBbCDdGHhIJLmoPRSUVwZ
480are extensions to that specification, and the behaviour of the
481.Fl f
482flag when used with an empty pattern file is left undefined.
483.Pp
484All long options are provided for compatibility with
485GNU versions of this utility.
486.Pp
487Historic versions of the
488.Nm grep
489utility also supported the flags
490.Op Fl ruy .
491This implementation supports those options;
492however, their use is strongly discouraged.
493.Sh HISTORY
494The
495.Nm grep
496command first appeared in
497.At v6 .
498