6 . if \w'\(lq' .ds lq "\(lq
10 . if \w'\(rq' .ds rq "\(rq
16 .Id $Id: grep.1,v 1.23 2002/01/22 13:20:04 bero Exp $
17 .TH GREP 1 \*(Dt "GNU Project"
19 grep, egrep, fgrep, zgrep, zegrep, zfgrep,
20 bzgrep, bzegrep, bzfgrep \- print lines matching a pattern
37 searches the named input
39 (or standard input if no files are named, or
43 for lines containing a match to the given
47 prints the matching lines.
49 In addition, two variant programs
71 .BI \-A " NUM" "\fR,\fP \-\^\-after-context=" NUM
74 lines of trailing context after matching lines.
75 Places a line containing
77 between contiguous groups of matches.
79 .BR \-a ", " \-\^\-text
80 Process a binary file as if it were text; this is equivalent to the
81 .B \-\^\-binary-files=text
84 .BI \-B " NUM" "\fR,\fP \-\^\-before-context=" NUM
87 lines of leading context before matching lines.
88 Places a line containing
90 between contiguous groups of matches.
92 .BI \-C " NUM" "\fR,\fP \-\^\-context=" NUM
95 lines of output context.
96 Places a line containing
98 between contiguous groups of matches.
100 .BR \-b ", " \-\^\-byte-offset
101 Print the byte offset within the input file before
104 .BI \-\^\-binary-files= TYPE
105 If the first few bytes of a file indicate that the file contains binary
106 data, assume that the file is of type
114 normally outputs either
115 a one-line message saying that a binary file matches, or no message if
122 assumes that a binary file does not match; this is equivalent to the
130 processes a binary file as if it were text; this is equivalent to the
134 .B "grep \-\^\-binary-files=text"
135 might output binary garbage,
136 which can have nasty side effects if the output is a terminal and if the
137 terminal driver interprets some of it as commands.
139 .BI \-\^\-colour[=\fIWHEN\fR] ", " \-\^\-color[=\fIWHEN\fR]
140 Surround the matching string with the marker find in
142 environment variable. WHEN may be `never', `always', or `auto'
144 .BR \-c ", " \-\^\-count
145 Suppress normal output; instead print a count of
146 matching lines for each input file.
148 .BR \-v ", " \-\^\-invert-match
149 option (see below), count non-matching lines.
151 .BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
152 If an input file is a device, FIFO or socket, use
154 to process it. By default,
158 which means that devices are read just as if they were ordinary files.
163 devices are silently skipped.
165 .BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
166 If an input file is a directory, use
168 to process it. By default,
172 which means that directories are read just as if they were ordinary files.
177 directories are silently skipped.
183 reads all files under each directory, recursively;
184 this is equivalent to the
188 .BR \-E ", " \-\^\-extended-regexp
191 as an extended regular expression (see below).
193 .BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
196 as the pattern; useful to protect patterns beginning with
199 .BR \-F ", " \-\^\-fixed-strings
202 as a list of fixed strings, separated by newlines,
203 any of which is to be matched.
205 .BR \-P ", " \-\^\-perl-regexp
208 as a Perl regular expression.
209 This option is not supported in FreeBSD.
211 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
215 The empty file contains zero patterns, and therefore matches nothing.
217 .BR \-G ", " \-\^\-basic-regexp
220 as a basic regular expression (see below). This is the default.
222 .BR \-H ", " \-\^\-with-filename
223 Print the filename for each match.
225 .BR \-h ", " \-\^\-no-filename
226 Suppress the prefixing of filenames on output
227 when multiple files are searched.
230 Output a brief help message.
233 Process a binary file as if it did not contain matching data; this is
235 .B \-\^\-binary-files=without-match
238 .BR \-i ", " \-\^\-ignore-case
239 Ignore case distinctions in both the
243 .BR \-L ", " \-\^\-files-without-match
244 Suppress normal output; instead print the name
245 of each input file from which no output would
246 normally have been printed. The scanning will stop
249 .BR \-l ", " \-\^\-files-with-matches
250 Suppress normal output; instead print
251 the name of each input file from which output
252 would normally have been printed. The scanning will
253 stop on the first match.
255 .BI \-m " NUM" "\fR,\fP \-\^\-max-count=" NUM
256 Stop reading a file after
258 matching lines. If the input is standard input from a regular file,
261 matching lines are output,
263 ensures that the standard input is positioned to just after the last
264 matching line before exiting, regardless of the presence of trailing
265 context lines. This enables a calling process to resume a search.
270 matching lines, it outputs any trailing context lines. When the
276 does not output a count greater than
281 .B \-\^\-invert-match
284 stops after outputting
291 system call to read input, instead of
294 system call. In some situations,
296 yields better performance. However,
298 can cause undefined behavior (including core dumps)
299 if an input file shrinks while
301 is operating, or if an I/O error occurs.
303 .BR \-n ", " \-\^\-line-number
304 Prefix each line of output with the line number
305 within its input file.
307 .BR \-o ", " \-\^\-only-matching
308 Show only the part of a matching line that matches
311 .BI \-\^\-label= LABEL
312 Displays input actually coming from standard input as input coming from file
314 This is especially useful for tools like zgrep, e.g.
315 .B "gzip -cd foo.gz |grep --label=foo something"
317 .BR \-\^\-line-buffered
318 Flush output on every line.
319 Note that this incurs a performance penalty.
321 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
322 Quiet; do not write anything to standard output.
323 Exit immediately with zero status if any match is found,
324 even if an error was detected.
331 .BR \-R ", " \-r ", " \-\^\-recursive
332 Read all files under each directory, recursively;
333 this is equivalent to the
337 .BR "\fR \fP \-\^\-include=" PATTERN
338 Recurse in directories only searching file matching
341 .BR "\fR \fP \-\^\-exclude=" PATTERN
342 Recurse in directories skip file matching
345 .BR \-s ", " \-\^\-no-messages
346 Suppress error messages about nonexistent or unreadable files.
347 Portability note: unlike \s-1GNU\s0
351 did not conform to \s-1POSIX.2\s0, because traditional
357 option behaved like \s-1GNU\s0
361 Shell scripts intended to be portable to traditional
367 and should redirect output to /dev/null instead.
369 .BR \-U ", " \-\^\-binary
370 Treat the file(s) as binary. By default, under MS-DOS and MS-Windows,
372 guesses the file type by looking at the contents of the first 32KB
373 read from the file. If
375 decides the file is a text file, it strips the CR characters from the
376 original file contents (to make regular expressions with
380 work correctly). Specifying
382 overrules this guesswork, causing all files to be read and passed to the
383 matching mechanism verbatim; if the file is a text file with CR/LF
384 pairs at the end of each line, this will cause some regular
386 This option has no effect on platforms other than MS-DOS and
389 .BR \-u ", " \-\^\-unix-byte-offsets
390 Report Unix-style byte offsets. This switch causes
392 to report byte offsets as if the file were Unix-style text file, i.e. with
393 CR characters stripped off. This will produce results identical to running
395 on a Unix machine. This option has no effect unless
398 it has no effect on platforms other than MS-DOS and MS-Windows.
400 .BR \-V ", " \-\^\-version
401 Print the version number of
403 to standard error. This version number should
404 be included in all bug reports (see below).
406 .BR \-v ", " \-\^\-invert-match
407 Invert the sense of matching, to select non-matching lines.
409 .BR \-w ", " \-\^\-word-regexp
410 Select only those lines containing matches that form whole words.
411 The test is that the matching substring must either be at the
412 beginning of the line, or preceded by a non-word constituent
413 character. Similarly, it must be either at the end of the line
414 or followed by a non-word constituent character. Word-constituent
415 characters are letters, digits, and the underscore.
417 .BR \-x ", " \-\^\-line-regexp
418 Select only those matches that exactly match the whole line.
425 Output a zero byte (the \s-1ASCII\s0
427 character) instead of the character that normally follows a file name.
429 .B "grep \-l \-\^\-null"
430 outputs a zero byte after each file name instead of the usual newline.
431 This option makes the output unambiguous, even in the presence of file
432 names containing unusual characters like newlines. This option can be
433 used with commands like
434 .BR "find \-print0" ,
439 to process arbitrary file names,
440 even those that contain newline characters.
442 .BR \-Z ", " \-\^\-decompress
443 Decompress the input data before searching.
444 This option is only available if compiled with
448 .BR \-J ", " \-\^\-bz2decompress
451 compressed input data before searching.
452 .SH "REGULAR EXPRESSIONS"
453 A regular expression is a pattern that describes a set of strings.
454 Regular expressions are constructed analogously to arithmetic
455 expressions, by using various operators to combine smaller expressions.
458 understands two different versions of regular expression syntax:
459 \*(lqbasic\*(rq and \*(lqextended.\*(rq In
460 .RB "\s-1GNU\s0\ " grep ,
461 there is no difference in available functionality using either syntax.
462 In other implementations, basic regular expressions are less powerful.
463 The following description applies to extended regular expressions;
464 differences for basic regular expressions are summarized afterwards.
466 The fundamental building blocks are the regular expressions that match
467 a single character. Most characters, including all letters and digits,
468 are regular expressions that match themselves. Any metacharacter with
469 special meaning may be quoted by preceding it with a backslash.
472 .I "bracket expression"
473 is a list of characters enclosed by
477 It matches any single
478 character in that list; if the first character of the list
481 then it matches any character
484 For example, the regular expression
486 matches any single digit.
488 Within a bracket expression, a
489 .I "range expression"
490 consists of two characters separated by a hyphen.
491 It matches any single character that sorts between the two characters,
492 inclusive, using the locale's collating sequence and character set.
493 For example, in the default C locale,
497 Many locales sort characters in dictionary order, and in these locales
499 is typically not equivalent to
501 it might be equivalent to
504 To obtain the traditional interpretation of bracket expressions,
505 you can use the C locale by setting the
507 environment variable to the value
510 Finally, certain named classes of characters are predefined within
511 bracket expressions, as follows.
512 Their names are self explanatory, and they are
530 except the latter form depends upon the C locale and the
531 \s-1ASCII\s0 character encoding, whereas the former is independent
532 of locale and character set.
533 (Note that the brackets in these class names are part of the symbolic
534 names, and must be included in addition to the brackets delimiting
535 the bracket list.) Most metacharacters lose their special meaning
536 inside lists. To include a literal
538 place it first in the list. Similarly, to include a literal
540 place it anywhere but first. Finally, to include a literal
546 matches any single character.
560 are metacharacters that respectively match the empty string at the
561 beginning and end of a line.
566 respectively match the empty string at the beginning and end of a word.
569 matches the empty string at the edge of a word,
572 matches the empty string provided it's
574 at the edge of a word.
576 A regular expression may be followed by one of several repetition operators:
580 The preceding item is optional and matched at most once.
583 The preceding item will be matched zero or more times.
586 The preceding item will be matched one or more times.
589 The preceding item is matched exactly
594 The preceding item is matched
599 The preceding item is matched at least
601 times, but not more than
606 Two regular expressions may be concatenated; the resulting
607 regular expression matches any string formed by concatenating
608 two substrings that respectively match the concatenated
611 Two regular expressions may be joined by the infix operator
613 the resulting regular expression matches any string matching
614 either subexpression.
616 Repetition takes precedence over concatenation, which in turn
617 takes precedence over alternation. A whole subexpression may be
618 enclosed in parentheses to override these precedence rules.
624 is a single digit, matches the substring
625 previously matched by the
627 parenthesized subexpression of the regular expression.
629 In basic regular expressions the metacharacters
637 lose their special meaning; instead use the backslashed
651 metacharacter, and some
653 implementations support
655 instead, so portable scripts should avoid
659 patterns and should use
666 attempts to support traditional usage by assuming that
668 is not special if it would be the start of an invalid interval
669 specification. For example, the shell command
671 searches for the two-character string
673 instead of reporting a syntax error in the regular expression.
674 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
676 .SH "ENVIRONMENT VARIABLES"
677 Grep's behavior is affected by the following environment variables.
681 is specified by examining the three environment variables
686 The first of these variables that is set specifies the locale.
693 then Brazilian Portuguese is used for the
696 The C locale is used if none of these environment variables are set,
697 or if the locale catalog is not installed, or if
699 was not compiled with national language support (\s-1NLS\s0).
702 This variable specifies default options to be placed in front of any
703 explicit options. For example, if
706 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
708 behaves as if the two options
709 .B \-\^\-binary-files=without-match
711 .B \-\^\-directories=skip
712 had been specified before any explicit options.
713 Option specifications are separated by whitespace.
714 A backslash escapes the next character,
715 so it can be used to specify an option containing whitespace or a backslash.
718 Specifies the marker for highlighting.
720 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
721 These variables specify the
723 locale, which determines the collating sequence used to interpret
724 range expressions like
727 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
728 These variables specify the
730 locale, which determines the type of characters, e.g., which
731 characters are whitespace.
733 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
734 These variables specify the
736 locale, which determines the language that
739 The default C locale uses American English messages.
744 behaves as \s-1POSIX.2\s0 requires; otherwise,
746 behaves more like other \s-1GNU\s0 programs.
747 \s-1POSIX.2\s0 requires that options that follow file names must be
748 treated as file names; by default, such options are permuted to the
749 front of the operand list and are treated as options.
750 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
751 \*(lqillegal\*(rq, but since they are not really against the law the default
752 is to diagnose them as \*(lqinvalid\*(rq.
755 Normally, exit status is 0 if selected lines are found and 1 otherwise.
756 But the exit status is 2 if an error occurred, unless the
762 option is used and a selected line is found.
765 .BR bug-gnu-utils@gnu.org .
766 Be sure to include the word \*(lqgrep\*(rq somewhere in the
767 \*(lqSubject:\*(rq field.
769 Large repetition counts in the
771 construct may cause grep to use lots of memory.
773 certain other obscure regular expressions require exponential time
774 and space, and may cause
776 to run out of memory.
778 Backreferences are very slow, and may require exponential time.
779 .\" Work around problems with some troff -man implementations.