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.
210 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
214 The empty file contains zero patterns, and therefore matches nothing.
216 .BR \-G ", " \-\^\-basic-regexp
219 as a basic regular expression (see below). This is the default.
221 .BR \-H ", " \-\^\-with-filename
222 Print the filename for each match.
224 .BR \-h ", " \-\^\-no-filename
225 Suppress the prefixing of filenames on output
226 when multiple files are searched.
229 Output a brief help message.
232 Process a binary file as if it did not contain matching data; this is
234 .B \-\^\-binary-files=without-match
237 .BR \-i ", " \-\^\-ignore-case
238 Ignore case distinctions in both the
242 .BR \-L ", " \-\^\-files-without-match
243 Suppress normal output; instead print the name
244 of each input file from which no output would
245 normally have been printed. The scanning will stop
248 .BR \-l ", " \-\^\-files-with-matches
249 Suppress normal output; instead print
250 the name of each input file from which output
251 would normally have been printed. The scanning will
252 stop on the first match.
254 .BI \-m " NUM" "\fR,\fP \-\^\-max-count=" NUM
255 Stop reading a file after
257 matching lines. If the input is standard input from a regular file,
260 matching lines are output,
262 ensures that the standard input is positioned to just after the last
263 matching line before exiting, regardless of the presence of trailing
264 context lines. This enables a calling process to resume a search.
269 matching lines, it outputs any trailing context lines. When the
275 does not output a count greater than
280 .B \-\^\-invert-match
283 stops after outputting
290 system call to read input, instead of
293 system call. In some situations,
295 yields better performance. However,
297 can cause undefined behavior (including core dumps)
298 if an input file shrinks while
300 is operating, or if an I/O error occurs.
302 .BR \-n ", " \-\^\-line-number
303 Prefix each line of output with the line number
304 within its input file.
306 .BR \-o ", " \-\^\-only-matching
307 Show only the part of a matching line that matches
310 .BI \-\^\-label= LABEL
311 Displays input actually coming from standard input as input coming from file
313 This is especially useful for tools like zgrep, e.g.
314 .B "gzip -cd foo.gz |grep --label=foo something"
316 .BR \-\^\-line-buffered
317 Flush output on every line.
318 Note that this incurs a performance penalty.
320 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
321 Quiet; do not write anything to standard output.
322 Exit immediately with zero status if any match is found,
323 even if an error was detected.
330 .BR \-R ", " \-r ", " \-\^\-recursive
331 Read all files under each directory, recursively;
332 this is equivalent to the
336 .BR "\fR \fP \-\^\-include=" PATTERN
337 Recurse in directories only searching file matching
340 .BR "\fR \fP \-\^\-exclude=" PATTERN
341 Recurse in directories skip file matching
344 .BR \-s ", " \-\^\-no-messages
345 Suppress error messages about nonexistent or unreadable files.
346 Portability note: unlike \s-1GNU\s0
350 did not conform to \s-1POSIX.2\s0, because traditional
356 option behaved like \s-1GNU\s0
360 Shell scripts intended to be portable to traditional
366 and should redirect output to /dev/null instead.
368 .BR \-U ", " \-\^\-binary
369 Treat the file(s) as binary. By default, under MS-DOS and MS-Windows,
371 guesses the file type by looking at the contents of the first 32KB
372 read from the file. If
374 decides the file is a text file, it strips the CR characters from the
375 original file contents (to make regular expressions with
379 work correctly). Specifying
381 overrules this guesswork, causing all files to be read and passed to the
382 matching mechanism verbatim; if the file is a text file with CR/LF
383 pairs at the end of each line, this will cause some regular
385 This option has no effect on platforms other than MS-DOS and
388 .BR \-u ", " \-\^\-unix-byte-offsets
389 Report Unix-style byte offsets. This switch causes
391 to report byte offsets as if the file were Unix-style text file, i.e. with
392 CR characters stripped off. This will produce results identical to running
394 on a Unix machine. This option has no effect unless
397 it has no effect on platforms other than MS-DOS and MS-Windows.
399 .BR \-V ", " \-\^\-version
400 Print the version number of
402 to standard error. This version number should
403 be included in all bug reports (see below).
405 .BR \-v ", " \-\^\-invert-match
406 Invert the sense of matching, to select non-matching lines.
408 .BR \-w ", " \-\^\-word-regexp
409 Select only those lines containing matches that form whole words.
410 The test is that the matching substring must either be at the
411 beginning of the line, or preceded by a non-word constituent
412 character. Similarly, it must be either at the end of the line
413 or followed by a non-word constituent character. Word-constituent
414 characters are letters, digits, and the underscore.
416 .BR \-x ", " \-\^\-line-regexp
417 Select only those matches that exactly match the whole line.
424 Output a zero byte (the \s-1ASCII\s0
426 character) instead of the character that normally follows a file name.
428 .B "grep \-l \-\^\-null"
429 outputs a zero byte after each file name instead of the usual newline.
430 This option makes the output unambiguous, even in the presence of file
431 names containing unusual characters like newlines. This option can be
432 used with commands like
433 .BR "find \-print0" ,
438 to process arbitrary file names,
439 even those that contain newline characters.
441 .BR \-Z ", " \-\^\-decompress
442 Decompress the input data before searching.
443 This option is only available if compiled with
447 .BR \-J ", " \-\^\-bz2decompress
450 compressed input data before searching.
451 .SH "REGULAR EXPRESSIONS"
452 A regular expression is a pattern that describes a set of strings.
453 Regular expressions are constructed analogously to arithmetic
454 expressions, by using various operators to combine smaller expressions.
457 understands two different versions of regular expression syntax:
458 \*(lqbasic\*(rq and \*(lqextended.\*(rq In
459 .RB "\s-1GNU\s0\ " grep ,
460 there is no difference in available functionality using either syntax.
461 In other implementations, basic regular expressions are less powerful.
462 The following description applies to extended regular expressions;
463 differences for basic regular expressions are summarized afterwards.
465 The fundamental building blocks are the regular expressions that match
466 a single character. Most characters, including all letters and digits,
467 are regular expressions that match themselves. Any metacharacter with
468 special meaning may be quoted by preceding it with a backslash.
471 .I "bracket expression"
472 is a list of characters enclosed by
476 It matches any single
477 character in that list; if the first character of the list
480 then it matches any character
483 For example, the regular expression
485 matches any single digit.
487 Within a bracket expression, a
488 .I "range expression"
489 consists of two characters separated by a hyphen.
490 It matches any single character that sorts between the two characters,
491 inclusive, using the locale's collating sequence and character set.
492 For example, in the default C locale,
496 Many locales sort characters in dictionary order, and in these locales
498 is typically not equivalent to
500 it might be equivalent to
503 To obtain the traditional interpretation of bracket expressions,
504 you can use the C locale by setting the
506 environment variable to the value
509 Finally, certain named classes of characters are predefined within
510 bracket expressions, as follows.
511 Their names are self explanatory, and they are
529 except the latter form depends upon the C locale and the
530 \s-1ASCII\s0 character encoding, whereas the former is independent
531 of locale and character set.
532 (Note that the brackets in these class names are part of the symbolic
533 names, and must be included in addition to the brackets delimiting
534 the bracket list.) Most metacharacters lose their special meaning
535 inside lists. To include a literal
537 place it first in the list. Similarly, to include a literal
539 place it anywhere but first. Finally, to include a literal
545 matches any single character.
559 are metacharacters that respectively match the empty string at the
560 beginning and end of a line.
565 respectively match the empty string at the beginning and end of a word.
568 matches the empty string at the edge of a word,
571 matches the empty string provided it's
573 at the edge of a word.
575 A regular expression may be followed by one of several repetition operators:
579 The preceding item is optional and matched at most once.
582 The preceding item will be matched zero or more times.
585 The preceding item will be matched one or more times.
588 The preceding item is matched exactly
593 The preceding item is matched
598 The preceding item is matched at least
600 times, but not more than
605 Two regular expressions may be concatenated; the resulting
606 regular expression matches any string formed by concatenating
607 two substrings that respectively match the concatenated
610 Two regular expressions may be joined by the infix operator
612 the resulting regular expression matches any string matching
613 either subexpression.
615 Repetition takes precedence over concatenation, which in turn
616 takes precedence over alternation. A whole subexpression may be
617 enclosed in parentheses to override these precedence rules.
623 is a single digit, matches the substring
624 previously matched by the
626 parenthesized subexpression of the regular expression.
628 In basic regular expressions the metacharacters
636 lose their special meaning; instead use the backslashed
650 metacharacter, and some
652 implementations support
654 instead, so portable scripts should avoid
658 patterns and should use
665 attempts to support traditional usage by assuming that
667 is not special if it would be the start of an invalid interval
668 specification. For example, the shell command
670 searches for the two-character string
672 instead of reporting a syntax error in the regular expression.
673 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
675 .SH "ENVIRONMENT VARIABLES"
676 Grep's behavior is affected by the following environment variables.
680 is specified by examining the three environment variables
685 The first of these variables that is set specifies the locale.
692 then Brazilian Portuguese is used for the
695 The C locale is used if none of these environment variables are set,
696 or if the locale catalog is not installed, or if
698 was not compiled with national language support (\s-1NLS\s0).
701 This variable specifies default options to be placed in front of any
702 explicit options. For example, if
705 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
707 behaves as if the two options
708 .B \-\^\-binary-files=without-match
710 .B \-\^\-directories=skip
711 had been specified before any explicit options.
712 Option specifications are separated by whitespace.
713 A backslash escapes the next character,
714 so it can be used to specify an option containing whitespace or a backslash.
717 Specifies the marker for highlighting.
719 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
720 These variables specify the
722 locale, which determines the collating sequence used to interpret
723 range expressions like
726 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
727 These variables specify the
729 locale, which determines the type of characters, e.g., which
730 characters are whitespace.
732 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
733 These variables specify the
735 locale, which determines the language that
738 The default C locale uses American English messages.
743 behaves as \s-1POSIX.2\s0 requires; otherwise,
745 behaves more like other \s-1GNU\s0 programs.
746 \s-1POSIX.2\s0 requires that options that follow file names must be
747 treated as file names; by default, such options are permuted to the
748 front of the operand list and are treated as options.
749 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
750 \*(lqillegal\*(rq, but since they are not really against the law the default
751 is to diagnose them as \*(lqinvalid\*(rq.
754 Normally, exit status is 0 if selected lines are found and 1 otherwise.
755 But the exit status is 2 if an error occurred, unless the
761 option is used and a selected line is found.
764 .BR bug-gnu-utils@gnu.org .
765 Be sure to include the word \*(lqgrep\*(rq somewhere in the
766 \*(lqSubject:\*(rq field.
768 Large repetition counts in the
770 construct may cause grep to use lots of memory.
772 certain other obscure regular expressions require exponential time
773 and space, and may cause
775 to run out of memory.
777 Backreferences are very slow, and may require exponential time.
778 .\" Work around problems with some troff -man implementations.