1 .\" $NetBSD: grep.1,v 1.2 2011/02/16 01:31:33 joerg Exp $
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.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
38 .Nd file pattern searcher
42 .Op Fl abcdDEFGHhIiLlmnOopqRSsUVvwxz
48 .Op Fl Fl binary-files= Ns Ar value
49 .Op Fl Fl color Ns Op Cm = Ns Ar when
50 .Op Fl Fl colour Ns Op Cm = Ns Ar when
51 .Op Fl Fl context= Ns Ar num
53 .Op Fl Fl line-buffered
61 utility searches any given input files,
62 selecting lines that match one or more patterns.
63 By default, a pattern matches an input line if the regular expression
64 (RE) in the pattern matches the input line
65 without its trailing newline.
66 An empty expression matches every line.
67 Each input line that matches at least one of the patterns is written
68 to the standard output.
71 is used for simple patterns and
72 basic regular expressions
75 can handle extended regular expressions
79 for more information on regular expressions.
85 but can only handle fixed patterns
86 (i.e., it does not interpret regular expressions).
87 Patterns may consist of one or more lines,
88 allowing any of the pattern lines to match a portion of the input.
90 The following options are available:
91 .Bl -tag -width indent
92 .It Fl A Ar num , Fl Fl after-context= Ns Ar num
95 lines of trailing context after each match.
101 .It Fl a , Fl Fl text
102 Treat all files as ASCII text.
106 .Dq Binary file ... matches
107 if files contain binary characters.
108 Use of this option forces
110 to output lines matching the specified pattern.
111 .It Fl B Ar num , Fl Fl before-context= Ns Ar num
114 lines of leading context before each match.
120 .It Fl b , Fl Fl byte-offset
121 The offset in bytes of a matched pattern is
122 displayed in front of the respective matched line.
123 .It Fl C Ar num , Fl Fl context= Ns Ar num
126 lines of leading and trailing context surrounding each match.
132 .It Fl c , Fl Fl count
133 Only a count of selected lines is written to standard output.
134 .It Fl Fl colour= Ns Oo Ar when Oc , Fl Fl color= Ns Oo Ar when Oc
135 Mark up the matching text with the expression stored in the
137 environment variable.
138 The possible values of
145 .It Fl D Ar action , Fl Fl devices= Ns Ar action
148 for devices, FIFOs and sockets.
153 which means, that they are read as if they were normal files.
158 devices are silently skipped.
159 .It Fl d Ar action , Fl Fl directories= Ns Ar action
165 by default, which means that the directories
166 are read in the same manner as normal files.
167 Other possible values are
169 to silently ignore the directories, and
171 to read them recursively, which has the same effect as the
176 .It Fl E , Fl Fl extended-regexp
179 as an extended regular expression
184 .It Fl e Ar pattern , Fl Fl regexp= Ns Ar pattern
187 used during the search of the input:
188 an input line is selected if it matches any of the specified patterns.
189 This option is most useful when multiple
191 options are used to specify multiple patterns,
196 .It Fl Fl exclude Ar pattern
197 If specified, it excludes files matching the given
205 patterns are processed in the order given.
206 If a name matches multiple patterns, the latest matching rule wins.
209 pattern is specified, all files are searched that are
211 Patterns are matched to the full path specified,
212 not only to the filename component.
213 .It Fl Fl exclude-dir Ar pattern
216 is specified, it excludes directories matching the
224 patterns are processed in the order given.
225 If a name matches multiple patterns, the latest matching rule wins.
228 pattern is specified, all directories are searched that are
230 .It Fl F , Fl Fl fixed-strings
233 as a set of fixed strings
238 .It Fl f Ar file , Fl Fl file= Ns Ar file
239 Read one or more newline separated patterns from
241 Empty pattern lines match every input line.
242 Newlines are not considered part of a pattern.
245 is empty, nothing is matched.
246 .It Fl G , Fl Fl basic-regexp
249 as a basic regular expression
252 to behave as traditional
255 Always print filename headers with output lines.
256 .It Fl h , Fl Fl no-filename
257 Never print filename headers
261 Print a brief help message.
264 This option is equivalent to the
265 .Dq Fl Fl binary-files= Ns Cm without-match
267 .It Fl i , Fl Fl ignore-case
268 Perform case insensitive matching.
272 .It Fl Fl include Ar pattern
273 If specified, only files matching the given filename
280 patterns are processed in the order given.
281 If a name matches multiple patterns, the latest matching rule wins.
282 Patterns are matched to the full path specified,
283 not only to the filename component.
284 .It Fl Fl include-dir Ar pattern
287 is specified, only directories matching the given filename
294 patterns are processed in the order given.
295 If a name matches multiple patterns, the latest matching rule wins.
296 .It Fl L , Fl Fl files-without-match
297 Only the names of files not containing selected lines are written to
299 Pathnames are listed once per file searched.
300 If the standard input is searched, the string
305 .It Fl l , Fl Fl files-with-matches
306 Only the names of files containing selected lines are written to
309 will only search a file until a match has been found,
310 making searches potentially less expensive.
311 Pathnames are listed once per file searched.
312 If the standard input is searched, the string
318 Label to use in place of
320 for a file name where a file name would normally be printed.
321 This option applies to
331 to read input, which can result in better performance under some
332 circumstances but can cause undefined behaviour.
333 .It Fl m Ar num , Fl Fl max-count= Ns Ar num
334 Stop reading the file after
337 .It Fl n , Fl Fl line-number
338 Each output line is preceded by its relative line number in the file,
340 The line number counter is reset for each file processed.
341 This option is ignored if
350 Prints a zero-byte after the file name.
354 is specified, follow symbolic links only if they were explicitly listed
356 The default is not to follow symbolic links.
357 .It Fl o , Fl Fl only-matching
358 Prints only the matching part of the lines.
362 is specified, no symbolic links are followed.
364 .It Fl q , Fl Fl quiet , Fl Fl silent
366 suppress normal output.
368 will only search a file until a match has been found,
369 making searches potentially less expensive.
370 .It Fl R , Fl r , Fl Fl recursive
371 Recursively search subdirectories listed.
379 is specified, all symbolic links are followed.
380 The default is not to follow symbolic links.
381 .It Fl s , Fl Fl no-messages
383 Nonexistent and unreadable files are ignored
384 (i.e., their error messages are suppressed).
385 .It Fl U , Fl Fl binary
386 Search binary files, but do not attempt to print them.
388 This option has no effect and is provided only for compatibility with GNU grep.
389 .It Fl V , Fl Fl version
390 Display version information and exit.
391 .It Fl v , Fl Fl invert-match
392 Selected lines are those
394 matching any of the specified patterns.
395 .It Fl w , Fl Fl word-regexp
396 The expression is searched for as a word (as if surrounded by
402 This option has no effect if
405 .It Fl x , Fl Fl line-regexp
406 Only input lines selected against an entire fixed string or regular
407 expression are considered to be matching lines.
412 .It Fl z , Fl Fl null-data
413 Treat input and output data as sequences of lines terminated by a
414 zero-byte instead of a newline.
415 .It Fl Fl binary-files= Ns Ar value
416 Controls searching and printing of binary files.
418 .Bl -tag -compact -width "binary (default)"
419 .It Cm binary No (default)
420 Search binary files but do not print them.
422 Do not search binary files.
424 Treat all files as text.
426 .It Fl Fl line-buffered
427 Force output to be line buffered.
428 By default, output is line buffered when standard output is a terminal
429 and block buffered otherwise.
432 If no file arguments are specified, the standard input is used.
435 may be used in place of a file name, anywhere that a file name is accepted, to
436 read from standard input.
441 The following environment variables affect the execution of
443 .Bl -tag -width "GREP_OPTIONS"
445 This variable specifies the color used to highlight matched (non-empty) text.
447 This variable specifies default options
448 to be placed in front of any explicit options.
449 It may cause problems with portable scripts.
451 This variable specifies the type name of the terminal, console or display-device
459 utility exits with one of the following values:
461 .Bl -tag -width flag -compact
463 One or more lines were selected.
465 No lines were selected.
472 Find all occurrences of the pattern
476 .Dl $ grep 'patricia' myfile
478 Same as above but looking only for complete words:
480 .Dl $ grep -w 'patricia' myfile
482 Count occurrences of the exact pattern
486 .Dl $ grep -c FOO myfile
488 Same as above but ignoring case:
490 .Dl $ grep -c -i FOO myfile
492 Find all occurrences of the pattern
494 at the beginning of a line:
496 .Dl $ grep '^\e.Pp' myfile
498 The apostrophes ensure the entire expression is evaluated by
500 instead of by the user's shell.
503 matches the null string at the beginning of a line,
508 which would otherwise match any character.
510 Find all lines in a file which do not contain the words
515 .Dl $ grep -v -e 'foo' -e 'bar' myfile
519 looking for either 19, 20, or 25 using extended regular expressions:
521 .Dl $ egrep '19|20|25' calendar
523 Show matching lines and the name of the
525 files which contain the pattern
527 Do the search recursively from the
531 .Dl $ grep -H -R FIXME --include="*.h" /usr/src/sys/arm/
533 Same as above but show only the name of the matching file:
535 .Dl $ grep -l -R FIXME --include="*.h" /usr/src/sys/arm/
537 Show lines containing the text
539 The matching part of the output is colored and every line is prefixed with
540 the line number and the offset in the file for those lines that matched.
542 .Dl $ grep -b --colour -n foo myfile
544 Show lines that match the extended regular expression patterns read from the
547 .Dl $ echo -e 'Free\enBSD\enAll.*reserved' | grep -E -f - myfile
549 Show lines from the output of the
551 command matching the specified extended regular expression along with
552 three lines of leading context and one line of trailing context:
554 .Dl $ pciconf -lv | grep -B3 -A1 -E 'class.*=.*storage'
556 Suppress any output and use the exit status to show an appropriate message:
558 .Dl $ grep -q foo myfile && echo File matches
569 utility is compliant with the
574 .Op Fl AaBbCDdGHhILmopRSUVw
575 are extensions to that specification, and the behaviour of the
577 flag when used with an empty pattern file is left undefined.
579 All long options are provided for compatibility with
580 GNU versions of this utility.
582 Historic versions of the
584 utility also supported the flags
586 This implementation supports those options;
587 however, their use is strongly discouraged.
591 command first appeared in