2 .\" $FreeBSD: src/gnu/usr.bin/grep/grep.1,v 1.16.2.3 2001/11/27 08:25:45 ru Exp $
6 . if \w'\(lq' .ds lq "\(lq
10 . if \w'\(rq' .ds rq "\(rq
16 .Id $Id: grep.1,v 1.9 2000/01/26 03:42:16 alainm Exp $
17 .TH GREP 1 \*(Dt "GNU Project"
19 grep, egrep, fgrep, zgrep \- print lines matching a pattern
36 searches the named input
38 (or standard input if no files are named, or
42 for lines containing a match to the given
46 prints the matching lines.
48 In addition, two variant programs
64 .BI \-A " NUM" "\fR,\fP \-\^\-after-context=" NUM
67 lines of trailing context after matching lines.
69 .BR \-a ", " \-\^\-text
70 Process a binary file as if it were text; this is equivalent to the
71 .B \-\^\-binary-files=text
74 .BI \-B " NUM" "\fR,\fP \-\^\-before-context=" NUM
77 lines of leading context before matching lines.
79 \fB\-C\fP [\fINUM\fP], \fB\-\fP\fINUM\fP, \fB\-\^\-context\fP[\fB=\fP\fINUM\fP]
82 lines (default 2) of output context.
84 .BR \-b ", " \-\^\-byte-offset
85 Print the byte offset within the input file before
88 .BI \-\^\-binary-files= TYPE
89 If the first few bytes of a file indicate that the file contains binary
90 data, assume that the file is of type
98 normally outputs either
99 a one-line message saying that a binary file matches, or no message if
106 assumes that a binary file does not match; this is equivalent to the
114 processes a binary file as if it were text; this is equivalent to the
118 .B "grep \-\^\-binary-files=text"
119 might output binary garbage,
120 which can have nasty side effects if the output is a terminal and if the
121 terminal driver interprets some of it as commands.
123 .BR \-c ", " \-\^\-count
124 Suppress normal output; instead print a count of
125 matching lines for each input file.
127 .BR \-v ", " \-\^\-invert-match
128 option (see below), count non-matching lines.
130 .BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
131 If an input file is a directory, use
133 to process it. By default,
137 which means that directories are read just as if they were ordinary files.
142 directories are silently skipped.
148 grep reads all files under each directory, recursively;
149 this is equivalent to the
153 .BR \-E ", " \-\^\-extended-regexp
156 as an extended regular expression (see below).
158 .BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
161 as the pattern; useful to protect patterns beginning with
164 .BR \-F ", " \-\^\-fixed-strings
167 as a list of fixed strings, separated by newlines,
168 any of which is to be matched.
170 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
174 The empty file contains zero patterns, and therfore matches nothing.
176 .BR \-G ", " \-\^\-basic-regexp
179 as a basic regular expression (see below). This is the default.
181 .BR \-H ", " \-\^\-with-filename
182 Print the filename for each match.
184 .BR \-h ", " \-\^\-no-filename
185 Suppress the prefixing of filenames on output
186 when multiple files are searched.
189 Output a brief help message.
192 Process a binary file as if it did not contain matching data; this is
194 .B \-\^\-binary-files=without-match
197 .BR \-i ", " \-\^\-ignore-case
198 Ignore case distinctions in both the
202 .BR \-L ", " \-\^\-files-without-match
203 Suppress normal output; instead print the name
204 of each input file from which no output would
205 normally have been printed. The scanning will stop
208 .BR \-l ", " \-\^\-files-with-matches
209 Suppress normal output; instead print
210 the name of each input file from which output
211 would normally have been printed. The scanning will
212 stop on the first match.
217 system call to read input, instead of
220 system call. In some situations,
222 yields better performance. However,
224 can cause undefined behavior (including core dumps)
225 if an input file shrinks while
227 is operating, or if an I/O error occurs.
229 .BR \-n ", " \-\^\-line-number
230 Prefix each line of output with the line number
231 within its input file.
233 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
234 Quiet; suppress normal output. The scanning will stop
242 .BR \-r ", " \-\^\-recursive
243 Read all files under each directory, recursively;
244 this is equivalent to the
248 .BR \-s ", " \-\^\-no-messages
249 Suppress error messages about nonexistent or unreadable files.
250 Portability note: unlike \s-1GNU\s0
254 did not conform to \s-1POSIX.2\s0, because traditional
260 option behaved like \s-1GNU\s0
264 Shell scripts intended to be portable to traditional
270 and should redirect output to /dev/null instead.
272 .BR \-U ", " \-\^\-binary
273 Treat the file(s) as binary. By default, under MS-DOS and MS-Windows,
275 guesses the file type by looking at the contents of the first 32KB
276 read from the file. If
278 decides the file is a text file, it strips the CR characters from the
279 original file contents (to make regular expressions with
283 work correctly). Specifying
285 overrules this guesswork, causing all files to be read and passed to the
286 matching mechanism verbatim; if the file is a text file with CR/LF
287 pairs at the end of each line, this will cause some regular
289 This option has no effect on platforms other than MS-DOS and
292 .BR \-u ", " \-\^\-unix-byte-offsets
293 Report Unix-style byte offsets. This switch causes
295 to report byte offsets as if the file were Unix-style text file, i.e. with
296 CR characters stripped off. This will produce results identical to running
298 on a Unix machine. This option has no effect unless
301 it has no effect on platforms other than MS-DOS and MS-Windows.
303 .BR \-V ", " \-\^\-version
304 Print the version number of
306 to standard error. This version number should
307 be included in all bug reports (see below).
309 .BR \-v ", " \-\^\-invert-match
310 Invert the sense of matching, to select non-matching lines.
312 .BR \-w ", " \-\^\-word-regexp
313 Select only those lines containing matches that form whole words.
314 The test is that the matching substring must either be at the
315 beginning of the line, or preceded by a non-word constituent
316 character. Similarly, it must be either at the end of the line
317 or followed by a non-word constituent character. Word-constituent
318 characters are letters, digits, and the underscore.
320 .BR \-x ", " \-\^\-line-regexp
321 Select only those matches that exactly match the whole line.
328 Output a zero byte (the \s-1ASCII\s0
330 character) instead of the character that normally follows a file name.
332 .B "grep \-l \-\^\-null"
333 outputs a zero byte after each file name instead of the usual newline.
334 This option makes the output unambiguous, even in the presence of file
335 names containing unusual characters like newlines. This option can be
336 used with commands like
337 .BR "find \-print0" ,
342 to process arbitrary file names,
343 even those that contain newline characters.
345 .BR \-Z ", " \-\^\-decompress
346 Decompress the input data before searching.
347 This option is only available if compiled with zlib(3) library.
348 .SH "REGULAR EXPRESSIONS"
349 A regular expression is a pattern that describes a set of strings.
350 Regular expressions are constructed analogously to arithmetic
351 expressions, by using various operators to combine smaller expressions.
354 understands two different versions of regular expression syntax:
355 \*(lqbasic\*(rq and \*(lqextended.\*(rq In
356 .RB "\s-1GNU\s0\ " grep ,
357 there is no difference in available functionality using either syntax.
358 In other implementations, basic regular expressions are less powerful.
359 The following description applies to extended regular expressions;
360 differences for basic regular expressions are summarized afterwards.
362 The fundamental building blocks are the regular expressions that match
363 a single character. Most characters, including all letters and digits,
364 are regular expressions that match themselves. Any metacharacter with
365 special meaning may be quoted by preceding it with a backslash.
367 A list of characters enclosed by
372 character in that list; if the first character of the list
375 then it matches any character
378 For example, the regular expression
380 matches any single digit. A range of characters
381 may be specified by giving the first and last characters, separated
383 Finally, certain named classes of characters are predefined.
384 Their names are self explanatory, and they are
401 except the latter form depends upon the \s-1POSIX\s0 locale and the
402 \s-1ASCII\s0 character encoding, whereas the former is independent
403 of locale and character set.
404 (Note that the brackets in these class names are part of the symbolic
405 names, and must be included in addition to the brackets delimiting
406 the bracket list.) Most metacharacters lose their special meaning
407 inside lists. To include a literal
409 place it first in the list. Similarly, to include a literal
411 place it anywhere but first. Finally, to include a literal
417 matches any single character.
431 are metacharacters that respectively match the empty string at the
432 beginning and end of a line.
437 respectively match the empty string at the beginning and end of a word.
440 matches the empty string at the edge of a word,
443 matches the empty string provided it's
445 at the edge of a word.
447 A regular expression may be followed by one of several repetition operators:
451 The preceding item is optional and matched at most once.
454 The preceding item will be matched zero or more times.
457 The preceding item will be matched one or more times.
460 The preceding item is matched exactly
465 The preceding item is matched
470 The preceding item is matched at least
472 times, but not more than
477 Two regular expressions may be concatenated; the resulting
478 regular expression matches any string formed by concatenating
479 two substrings that respectively match the concatenated
482 Two regular expressions may be joined by the infix operator
484 the resulting regular expression matches any string matching
485 either subexpression.
487 Repetition takes precedence over concatenation, which in turn
488 takes precedence over alternation. A whole subexpression may be
489 enclosed in parentheses to override these precedence rules.
495 is a single digit, matches the substring
496 previously matched by the
498 parenthesized subexpression of the regular expression.
500 In basic regular expressions the metacharacters
508 lose their special meaning; instead use the backslashed
522 metacharacter, and some
524 implementations support
526 instead, so portable scripts should avoid
530 patterns and should use
537 attempts to support traditional usage by assuming that
539 is not special if it would be the start of an invalid interval
540 specification. For example, the shell command
542 searches for the two-character string
544 instead of reporting a syntax error in the regular expression.
545 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
547 .SH "ENVIRONMENT VARIABLES"
550 This variable specifies default options to be placed in front of any
551 explicit options. For example, if
554 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
556 behaves as if the two options
557 .B \-\^\-binary-files=without-match
559 .B \-\^\-directories=skip
560 had been specified before any explicit options.
561 Option specifications are separated by whitespace.
562 A backslash escapes the next character,
563 so it can be used to specify an option containing whitespace or a backslash.
565 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
566 These variables specify the
568 locale, which determines the language that
571 The locale is determined by the first of these variables that is set.
572 American English is used if none of these environment variables are set,
573 or if the message catalog is not installed, or if
575 was not compiled with national language support (\s-1NLS\s0).
577 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
578 These variables specify the
580 locale, which determines the type of characters, e.g., which
581 characters are whitespace.
582 The locale is determined by the first of these variables that is set.
583 The \s-1POSIX\s0 locale is used if none of these environment variables
584 are set, or if the locale catalog is not installed, or if
586 was not compiled with national language support (\s-1NLS\s0).
591 behaves as \s-1POSIX.2\s0 requires; otherwise,
593 behaves more like other \s-1GNU\s0 programs.
594 \s-1POSIX.2\s0 requires that options that follow file names must be
595 treated as file names; by default, such options are permuted to the
596 front of the operand list and are treated as options.
597 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
598 \*(lqillegal\*(rq, but since they are not really against the law the default
599 is to diagnose them as \*(lqinvalid\*(rq.
601 Normally, exit status is 0 if matches were found,
602 and 1 if no matches were found. (The
604 option inverts the sense of the exit status.)
605 Exit status is 2 if there were syntax errors
606 in the pattern, inaccessible input files, or
610 .BR bug-gnu-utils@gnu.org .
611 Be sure to include the word \*(lqgrep\*(rq somewhere in the
612 \*(lqSubject:\*(rq field.
614 Large repetition counts in the
616 construct may cause grep to use lots of memory.
618 certain other obscure regular expressions require exponential time
619 and space, and may cause
621 to run out of memory.
623 Backreferences are very slow, and may require exponential time.
624 .\" Work around problems with some troff -man implementations.