1 .\" $NetBSD: grep.1,v 1.2 2011/02/16 01:31:33 joerg Exp $
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.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
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.
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
31 .\" @(#)grep.1 8.3 (Berkeley) 4/18/94
41 .Nd file pattern searcher
45 .Op Fl abcdDEFGHhIiLlmnOopqRSsUVvwxz
51 .Op Fl Fl binary-files= Ns Ar value
52 .Op Fl Fl color Ns Op Cm = Ns Ar when
53 .Op Fl Fl colour Ns Op Cm = Ns Ar when
54 .Op Fl Fl context= Ns Ar num
56 .Op Fl Fl line-buffered
64 utility searches any given input files,
65 selecting lines that match one or more patterns.
66 By default, a pattern matches an input line if the regular expression
67 (RE) in the pattern matches the input line
68 without its trailing newline.
69 An empty expression matches every line.
70 Each input line that matches at least one of the patterns is written
71 to the standard output.
74 is used for simple patterns and
75 basic regular expressions
78 can handle extended regular expressions
82 for more information on regular expressions.
88 but can only handle fixed patterns
89 (i.e., it does not interpret regular expressions).
90 Patterns may consist of one or more lines,
91 allowing any of the pattern lines to match a portion of the input.
93 The following options are available:
94 .Bl -tag -width indent
95 .It Fl A Ar num , Fl Fl after-context= Ns Ar num
98 lines of trailing context after each match.
104 .It Fl a , Fl Fl text
105 Treat all files as ASCII text.
109 .Dq Binary file ... matches
110 if files contain binary characters.
111 Use of this option forces
113 to output lines matching the specified pattern.
114 .It Fl B Ar num , Fl Fl before-context= Ns Ar num
117 lines of leading context before each match.
123 .It Fl b , Fl Fl byte-offset
124 The offset in bytes of a matched pattern is
125 displayed in front of the respective matched line.
126 .It Fl C Ar num , Fl Fl context= Ns Ar num
129 lines of leading and trailing context surrounding each match.
135 .It Fl c , Fl Fl count
136 Only a count of selected lines is written to standard output.
137 .It Fl Fl colour= Ns Oo Ar when Oc , Fl Fl color= Ns Oo Ar when Oc
138 Mark up the matching text with the expression stored in the
140 environment variable.
141 The possible values of
148 .It Fl D Ar action , Fl Fl devices= Ns Ar action
151 for devices, FIFOs and sockets.
156 which means, that they are read as if they were normal files.
161 devices are silently skipped.
162 .It Fl d Ar action , Fl Fl directories= Ns Ar action
168 by default, which means that the directories
169 are read in the same manner as normal files.
170 Other possible values are
172 to silently ignore the directories, and
174 to read them recursively, which has the same effect as the
179 .It Fl E , Fl Fl extended-regexp
182 as an extended regular expression
187 .It Fl e Ar pattern , Fl Fl regexp= Ns Ar pattern
190 used during the search of the input:
191 an input line is selected if it matches any of the specified patterns.
192 This option is most useful when multiple
194 options are used to specify multiple patterns,
199 .It Fl Fl exclude Ar pattern
200 If specified, it excludes files matching the given
208 patterns are processed in the order given.
209 If a name matches multiple patterns, the latest matching rule wins.
212 pattern is specified, all files are searched that are
214 Patterns are matched to the full path specified,
215 not only to the filename component.
216 .It Fl Fl exclude-dir Ar pattern
219 is specified, it excludes directories matching the
227 patterns are processed in the order given.
228 If a name matches multiple patterns, the latest matching rule wins.
231 pattern is specified, all directories are searched that are
233 .It Fl F , Fl Fl fixed-strings
236 as a set of fixed strings
241 .It Fl f Ar file , Fl Fl file= Ns Ar file
242 Read one or more newline separated patterns from
244 Empty pattern lines match every input line.
245 Newlines are not considered part of a pattern.
248 is empty, nothing is matched.
249 .It Fl G , Fl Fl basic-regexp
252 as a basic regular expression
255 to behave as traditional
258 Always print filename headers with output lines.
259 .It Fl h , Fl Fl no-filename
260 Never print filename headers
264 Print a brief help message.
267 This option is equivalent to the
268 .Dq Fl Fl binary-files= Ns Cm without-match
270 .It Fl i , Fl Fl ignore-case
271 Perform case insensitive matching.
275 .It Fl Fl include Ar pattern
276 If specified, only files matching the given filename
283 patterns are processed in the order given.
284 If a name matches multiple patterns, the latest matching rule wins.
285 Patterns are matched to the full path specified,
286 not only to the filename component.
287 .It Fl Fl include-dir Ar pattern
290 is specified, only directories matching the given filename
297 patterns are processed in the order given.
298 If a name matches multiple patterns, the latest matching rule wins.
299 .It Fl L , Fl Fl files-without-match
300 Only the names of files not containing selected lines are written to
302 Pathnames are listed once per file searched.
303 If the standard input is searched, the string
308 .It Fl l , Fl Fl files-with-matches
309 Only the names of files containing selected lines are written to
312 will only search a file until a match has been found,
313 making searches potentially less expensive.
314 Pathnames are listed once per file searched.
315 If the standard input is searched, the string
321 Label to use in place of
323 for a file name where a file name would normally be printed.
324 This option applies to
334 to read input, which can result in better performance under some
335 circumstances but can cause undefined behaviour.
336 .It Fl m Ar num , Fl Fl max-count= Ns Ar num
337 Stop reading the file after
340 .It Fl n , Fl Fl line-number
341 Each output line is preceded by its relative line number in the file,
343 The line number counter is reset for each file processed.
344 This option is ignored if
353 Prints a zero-byte after the file name.
357 is specified, follow symbolic links only if they were explicitly listed
359 The default is not to follow symbolic links.
360 .It Fl o , Fl Fl only-matching
361 Prints only the matching part of the lines.
365 is specified, no symbolic links are followed.
367 .It Fl q , Fl Fl quiet , Fl Fl silent
369 suppress normal output.
371 will only search a file until a match has been found,
372 making searches potentially less expensive.
373 .It Fl R , Fl r , Fl Fl recursive
374 Recursively search subdirectories listed.
382 is specified, all symbolic links are followed.
383 The default is not to follow symbolic links.
384 .It Fl s , Fl Fl no-messages
386 Nonexistent and unreadable files are ignored
387 (i.e., their error messages are suppressed).
388 .It Fl U , Fl Fl binary
389 Search binary files, but do not attempt to print them.
391 This option has no effect and is provided only for compatibility with GNU grep.
392 .It Fl V , Fl Fl version
393 Display version information and exit.
394 .It Fl v , Fl Fl invert-match
395 Selected lines are those
397 matching any of the specified patterns.
398 .It Fl w , Fl Fl word-regexp
399 The expression is searched for as a word (as if surrounded by
405 This option has no effect if
408 .It Fl x , Fl Fl line-regexp
409 Only input lines selected against an entire fixed string or regular
410 expression are considered to be matching lines.
415 .It Fl z , Fl Fl null-data
416 Treat input and output data as sequences of lines terminated by a
417 zero-byte instead of a newline.
418 .It Fl Fl binary-files= Ns Ar value
419 Controls searching and printing of binary files.
421 .Bl -tag -compact -width "binary (default)"
422 .It Cm binary No (default)
423 Search binary files but do not print them.
425 Do not search binary files.
427 Treat all files as text.
429 .It Fl Fl line-buffered
430 Force output to be line buffered.
431 By default, output is line buffered when standard output is a terminal
432 and block buffered otherwise.
435 If no file arguments are specified, the standard input is used.
438 may be used in place of a file name, anywhere that a file name is accepted, to
439 read from standard input.
444 The following environment variables affect the execution of
446 .Bl -tag -width "GREP_OPTIONS"
448 This variable specifies the color used to highlight matched (non-empty) text.
450 This variable specifies default options
451 to be placed in front of any explicit options.
452 It may cause problems with portable scripts.
454 This variable specifies the type name of the terminal, console or display-device
462 utility exits with one of the following values:
464 .Bl -tag -width flag -compact
466 One or more lines were selected.
468 No lines were selected.
475 Find all occurrences of the pattern
479 .Dl $ grep 'patricia' myfile
481 Same as above but looking only for complete words:
483 .Dl $ grep -w 'patricia' myfile
485 Count occurrences of the exact pattern
489 .Dl $ grep -c FOO myfile
491 Same as above but ignoring case:
493 .Dl $ grep -c -i FOO myfile
495 Find all occurrences of the pattern
497 at the beginning of a line:
499 .Dl $ grep '^\e.Pp' myfile
501 The apostrophes ensure the entire expression is evaluated by
503 instead of by the user's shell.
506 matches the null string at the beginning of a line,
511 which would otherwise match any character.
513 Find all lines in a file which do not contain the words
518 .Dl $ grep -v -e 'foo' -e 'bar' myfile
522 looking for either 19, 20, or 25 using extended regular expressions:
524 .Dl $ egrep '19|20|25' calendar
526 Show matching lines and the name of the
528 files which contain the pattern
530 Do the search recursively from the
534 .Dl $ grep -H -R FIXME --include="*.h" /usr/src/sys/arm/
536 Same as above but show only the name of the matching file:
538 .Dl $ grep -l -R FIXME --include="*.h" /usr/src/sys/arm/
540 Show lines containing the text
542 The matching part of the output is colored and every line is prefixed with
543 the line number and the offset in the file for those lines that matched.
545 .Dl $ grep -b --colour -n foo myfile
547 Show lines that match the extended regular expression patterns read from the
550 .Dl $ echo -e 'Free\enBSD\enAll.*reserved' | grep -E -f - myfile
552 Show lines from the output of the
554 command matching the specified extended regular expression along with
555 three lines of leading context and one line of trailing context:
557 .Dl $ pciconf -lv | grep -B3 -A1 -E 'class.*=.*storage'
559 Suppress any output and use the exit status to show an appropriate message:
561 .Dl $ grep -q foo myfile && echo File matches
572 utility is compliant with the
577 .Op Fl AaBbCDdGHhILmopRSUVw
578 are extensions to that specification, and the behaviour of the
580 flag when used with an empty pattern file is left undefined.
582 All long options are provided for compatibility with
583 GNU versions of this utility.
585 Historic versions of the
587 utility also supported the flags
589 This implementation supports those options;
590 however, their use is strongly discouraged.
594 command first appeared in