1GREP(1) General Commands Manual GREP(1)
2
6 grep, egrep, fgrep - print lines matching a pattern
7
9 grep [OPTIONS] PATTERN [FILE...]
10 grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]
11
13 grep searches the named input FILEs (or standard input if no files are
14 named, or if a single hyphen-minus (-) is given as file name) for lines
15 containing a match to the given PATTERN. By default, grep prints the
16 matching lines.
17 In addition, two variant programs egrep and fgrep are available. egrep
19 is the same as grep -E. fgrep is the same as grep -F. Direct
20 invocation as either egrep or fgrep is deprecated, but is provided to
21 allow historical applications that rely on them to run unmodified.
22
24 Generic Program Information
25 --help Print a usage message briefly summarizing these command-line
26 options and the bug-reporting address, then exit.
27 -V, --version
29 Print the version number of grep to the standard output stream.
30 This version number should be included in all bug reports (see
31 below).
32 Matcher Selection
34 -E, --extended-regexp
35 Interpret PATTERN as an extended regular expression (ERE, see
36 below). (-E is specified by POSIX.)
37 -F, --fixed-strings
39 Interpret PATTERN as a list of fixed strings, separated by
40 newlines, any of which is to be matched. (-F is specified by
41 POSIX.)
42 -G, --basic-regexp
44 Interpret PATTERN as a basic regular expression (BRE, see
45 below). This is the default.
46 -P, --perl-regexp
48 Interpret PATTERN as a Perl regular expression. This is highly
49 experimental and grep -P may warn of unimplemented features.
50 Matching Control
52 -e PATTERN, --regexp=PATTERN
53 Use PATTERN as the pattern. This can be used to specify
54 multiple search patterns, or to protect a pattern beginning with
55 a hyphen (-). (-e is specified by POSIX.)
56 -f FILE, --file=FILE
58 Obtain patterns from FILE, one per line. The empty file
59 contains zero patterns, and therefore matches nothing. (-f is
60 specified by POSIX.)
61 -i, --ignore-case
63 Ignore case distinctions in both the PATTERN and the input
64 files. (-i is specified by POSIX.)
65 -v, --invert-match
67 Invert the sense of matching, to select non-matching lines. (-v
68 is specified by POSIX.)
69 -w, --word-regexp
71 Select only those lines containing matches that form whole
72 words. The test is that the matching substring must either be
73 at the beginning of the line, or preceded by a non-word
74 constituent character. Similarly, it must be either at the end
75 of the line or followed by a non-word constituent character.
76 Word-constituent characters are letters, digits, and the
77 underscore.
78 -x, --line-regexp
80 Select only those matches that exactly match the whole line.
81 (-x is specified by POSIX.)
82 -y Obsolete synonym for -i.
84 General Output Control
86 -c, --count
87 Suppress normal output; instead print a count of matching lines
88 for each input file. With the -v, --invert-match option (see
89 below), count non-matching lines. (-c is specified by POSIX.)
90 --color[=WHEN], --colour[=WHEN]
92 Surround the matched (non-empty) strings, matching lines,
93 context lines, file names, line numbers, byte offsets, and
94 separators (for fields and groups of context lines) with escape
95 sequences to display them in color on the terminal. The colors
96 are defined by the environment variable GREP_COLORS. The
97 deprecated environment variable GREP_COLOR is still supported,
98 but its setting does not have priority. WHEN is never, always,
99 or auto.
100 -L, --files-without-match
102 Suppress normal output; instead print the name of each input
103 file from which no output would normally have been printed. The
104 scanning will stop on the first match.
105 -l, --files-with-matches
107 Suppress normal output; instead print the name of each input
108 file from which output would normally have been printed. The
109 scanning will stop on the first match. (-l is specified by
110 POSIX.)
111 -m NUM, --max-count=NUM
113 Stop reading a file after NUM matching lines. If the input is
114 standard input from a regular file, and NUM matching lines are
115 output, grep ensures that the standard input is positioned to
116 just after the last matching line before exiting, regardless of
117 the presence of trailing context lines. This enables a calling
118 process to resume a search. When grep stops after NUM matching
119 lines, it outputs any trailing context lines. When the -c or
120 --count option is also used, grep does not output a count
121 greater than NUM. When the -v or --invert-match option is also
122 used, grep stops after outputting NUM non-matching lines.
123 -o, --only-matching
125 Print only the matched (non-empty) parts of a matching line,
126 with each such part on a separate output line.
127 -q, --quiet, --silent
129 Quiet; do not write anything to standard output. Exit
130 immediately with zero status if any match is found, even if an
131 error was detected. Also see the -s or --no-messages option.
132 (-q is specified by POSIX.)
133 -s, --no-messages
135 Suppress error messages about nonexistent or unreadable files.
136 Portability note: unlike GNU grep, 7th Edition Unix grep did not
137 conform to POSIX, because it lacked -q and its -s option behaved
138 like GNU grep's -q option. USG-style grep also lacked -q but
139 its -s option behaved like GNU grep. Portable shell scripts
140 should avoid both -q and -s and should redirect standard and
141 error output to /dev/null instead. (-s is specified by POSIX.)
142 Output Line Prefix Control
144 -b, --byte-offset
145 Print the 0-based byte offset within the input file before each
146 line of output. If -o (--only-matching) is specified, print the
147 offset of the matching part itself.
148 -H, --with-filename
150 Print the file name for each match. This is the default when
151 there is more than one file to search.
152 -h, --no-filename
154 Suppress the prefixing of file names on output. This is the
155 default when there is only one file (or only standard input) to
156 search.
157 --label=LABEL
159 Display input actually coming from standard input as input
160 coming from file LABEL. This is especially useful when
161 implementing tools like zgrep, e.g., gzip -cd foo.gz | grep
162 --label=foo -H something. See also the -H option.
163 -n, --line-number
165 Prefix each line of output with the 1-based line number within
166 its input file. (-n is specified by POSIX.)
167 -T, --initial-tab
169 Make sure that the first character of actual line content lies
170 on a tab stop, so that the alignment of tabs looks normal. This
171 is useful with options that prefix their output to the actual
172 content: -H,-n, and -b. In order to improve the probability
173 that lines from a single file will all start at the same column,
174 this also causes the line number and byte offset (if present) to
175 be printed in a minimum size field width.
176 -u, --unix-byte-offsets
178 Report Unix-style byte offsets. This switch causes grep to
179 report byte offsets as if the file were a Unix-style text file,
180 i.e., with CR characters stripped off. This will produce
181 results identical to running grep on a Unix machine. This
182 option has no effect unless -b option is also used; it has no
183 effect on platforms other than MS-DOS and MS-Windows.
184 -Z, --null
186 Output a zero byte (the ASCII NUL character) instead of the
187 character that normally follows a file name. For example, grep
188 -lZ outputs a zero byte after each file name instead of the
189 usual newline. This option makes the output unambiguous, even
190 in the presence of file names containing unusual characters like
191 newlines. This option can be used with commands like find
192 -print0, perl -0, sort -z, and xargs -0 to process arbitrary
193 file names, even those that contain newline characters.
194 Context Line Control
196 -A NUM, --after-context=NUM
197 Print NUM lines of trailing context after matching lines.
198 Places a line containing a group separator (--) between
199 contiguous groups of matches. With the -o or --only-matching
200 option, this has no effect and a warning is given.
201 -B NUM, --before-context=NUM
203 Print NUM lines of leading context before matching lines.
204 Places a line containing a group separator (--) between
205 contiguous groups of matches. With the -o or --only-matching
206 option, this has no effect and a warning is given.
207 -C NUM, -NUM, --context=NUM
209 Print NUM lines of output context. Places a line containing a
210 group separator (--) between contiguous groups of matches. With
211 the -o or --only-matching option, this has no effect and a
212 warning is given.
213 File and Directory Selection
215 -a, --text
216 Process a binary file as if it were text; this is equivalent to
217 the --binary-files=text option.
218 --binary-files=TYPE
220 If the first few bytes of a file indicate that the file contains
221 binary data, assume that the file is of type TYPE. By default,
222 TYPE is binary, and grep normally outputs either a one-line
223 message saying that a binary file matches, or no message if
224 there is no match. If TYPE is without-match, grep assumes that
225 a binary file does not match; this is equivalent to the -I
226 option. If TYPE is text, grep processes a binary file as if it
227 were text; this is equivalent to the -a option. Warning: grep
228 --binary-files=text might output binary garbage, which can have
229 nasty side effects if the output is a terminal and if the
230 terminal driver interprets some of it as commands.
231 -D ACTION, --devices=ACTION
233 If an input file is a device, FIFO or socket, use ACTION to
234 process it. By default, ACTION is read, which means that
235 devices are read just as if they were ordinary files. If ACTION
236 is skip, devices are silently skipped.
237 -d ACTION, --directories=ACTION
239 If an input file is a directory, use ACTION to process it. By
240 default, ACTION is read, which means that directories are read
241 just as if they were ordinary files. If ACTION is skip,
242 directories are silently skipped. If ACTION is recurse, grep
243 reads all files under each directory, recursively; this is
244 equivalent to the -r option.
245 --exclude=GLOB
247 Skip files whose base name matches GLOB (using wildcard
248 matching). A file-name glob can use *, ?, and [...] as
249 wildcards, and \ to quote a wildcard or backslash character
250 literally.
251 --exclude-from=FILE
253 Skip files whose base name matches any of the file-name globs
254 read from FILE (using wildcard matching as described under
255 --exclude).
256 --exclude-dir=DIR
258 Exclude directories matching the pattern DIR from recursive
259 searches.
260 -I Process a binary file as if it did not contain matching data;
262 this is equivalent to the --binary-files=without-match option.
263 --include=GLOB
265 Search only files whose base name matches GLOB (using wildcard
266 matching as described under --exclude).
267 -R, -r, --recursive
269 Read all files under each directory, recursively; this is
270 equivalent to the -d recurse option.
271 Other Options
273 --line-buffered
274 Use line buffering on output. This can cause a performance
275 penalty.
276 --mmap If possible, use the mmap(2) system call to read input, instead
278 of the default read(2) system call. In some situations, --mmap
279 yields better performance. However, --mmap can cause undefined
280 behavior (including core dumps) if an input file shrinks while
281 grep is operating, or if an I/O error occurs.
282 -U, --binary
284 Treat the file(s) as binary. By default, under MS-DOS and MS-
285 Windows, grep guesses the file type by looking at the contents
286 of the first 32KB read from the file. If grep decides the file
287 is a text file, it strips the CR characters from the original
288 file contents (to make regular expressions with ^ and $ work
289 correctly). Specifying -U overrules this guesswork, causing all
290 files to be read and passed to the matching mechanism verbatim;
291 if the file is a text file with CR/LF pairs at the end of each
292 line, this will cause some regular expressions to fail. This
293 option has no effect on platforms other than MS-DOS and MS-
294 Windows.
295 -z, --null-data
297 Treat the input as a set of lines, each terminated by a zero
298 byte (the ASCII NUL character) instead of a newline. Like the
299 -Z or --null option, this option can be used with commands like
300 sort -z to process arbitrary file names.
301
303 A regular expression is a pattern that describes a set of strings.
304 Regular expressions are constructed analogously to arithmetic
305 expressions, by using various operators to combine smaller expressions.
306 grep understands three different versions of regular expression syntax:
308 “basic,” “extended” and “perl.” In GNU grep, there is no difference in
309 available functionality between basic and extended syntaxes. In other
310 implementations, basic regular expressions are less powerful. The
311 following description applies to extended regular expressions;
312 differences for basic regular expressions are summarized afterwards.
313 Perl regular expressions give additional functionality, and are
314 documented in pcresyntax(3) and pcrepattern(3), but may not be
315 available on every system.
316 The fundamental building blocks are the regular expressions that match
318 a single character. Most characters, including all letters and digits,
319 are regular expressions that match themselves. Any meta-character with
320 special meaning may be quoted by preceding it with a backslash.
321 The period . matches any single character.
323 Character Classes and Bracket Expressions
325 A bracket expression is a list of characters enclosed by [ and ]. It
326 matches any single character in that list; if the first character of
327 the list is the caret ^ then it matches any character not in the list.
328 For example, the regular expression [0123456789] matches any single
329 digit.
330 Within a bracket expression, a range expression consists of two
332 characters separated by a hyphen. It matches any single character that
333 sorts between the two characters, inclusive, using the locale's
334 collating sequence and character set. For example, in the default C
335 locale, [a-d] is equivalent to [abcd]. Many locales sort characters in
336 dictionary order, and in these locales [a-d] is typically not
337 equivalent to [abcd]; it might be equivalent to [aBbCcDd], for example.
338 To obtain the traditional interpretation of bracket expressions, you
339 can use the C locale by setting the LC_ALL environment variable to the
340 value C.
341 Finally, certain named classes of characters are predefined within
343 bracket expressions, as follows. Their names are self explanatory, and
344 they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:],
345 [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:].
346 For example, [[:alnum:]] means [0-9A-Za-z], except the latter form
347 depends upon the C locale and the ASCII character encoding, whereas the
348 former is independent of locale and character set. (Note that the
349 brackets in these class names are part of the symbolic names, and must
350 be included in addition to the brackets delimiting the bracket
351 expression.) Most meta-characters lose their special meaning inside
352 bracket expressions. To include a literal ] place it first in the
353 list. Similarly, to include a literal ^ place it anywhere but first.
354 Finally, to include a literal - place it last.
355 Anchoring
357 The caret ^ and the dollar sign $ are meta-characters that respectively
358 match the empty string at the beginning and end of a line.
359 The Backslash Character and Special Expressions
361 The symbols \< and \> respectively match the empty string at the
362 beginning and end of a word. The symbol \b matches the empty string at
363 the edge of a word, and \B matches the empty string provided it's not
364 at the edge of a word. The symbol \w is a synonym for [[:alnum:]] and
365 \W is a synonym for [^[:alnum:]].
366 Repetition
368 A regular expression may be followed by one of several repetition
369 operators:
370 ? The preceding item is optional and matched at most once.
371 * The preceding item will be matched zero or more times.
372 + The preceding item will be matched one or more times.
373 {n} The preceding item is matched exactly n times.
374 {n,} The preceding item is matched n or more times.
375 {n,m} The preceding item is matched at least n times, but not more
376 than m times.
377 Concatenation
379 Two regular expressions may be concatenated; the resulting regular
380 expression matches any string formed by concatenating two substrings
381 that respectively match the concatenated expressions.
382 Alternation
384 Two regular expressions may be joined by the infix operator |; the
385 resulting regular expression matches any string matching either
386 alternate expression.
387 Precedence
389 Repetition takes precedence over concatenation, which in turn takes
390 precedence over alternation. A whole expression may be enclosed in
391 parentheses to override these precedence rules and form a
392 subexpression.
393 Back References and Subexpressions
395 The back-reference \n, where n is a single digit, matches the substring
396 previously matched by the nth parenthesized subexpression of the
397 regular expression.
398 Basic vs Extended Regular Expressions
400 In basic regular expressions the meta-characters ?, +, {, |, (, and )
401 lose their special meaning; instead use the backslashed versions \?,
402 \+, \{, \|, \(, and \).
403 Traditional egrep did not support the { meta-character, and some egrep
405 implementations support \{ instead, so portable scripts should avoid {
406 in grep -E patterns and should use [{] to match a literal {.
407 GNU grep -E attempts to support traditional usage by assuming that { is
409 not special if it would be the start of an invalid interval
410 specification. For example, the command grep -E '{1' searches for the
411 two-character string {1 instead of reporting a syntax error in the
412 regular expression. POSIX.2 allows this behavior as an extension, but
413 portable scripts should avoid it.
414
416 The behavior of grep is affected by the following environment
417 variables.
418 The locale for category LC_foo is specified by examining the three
420 environment variables LC_ALL, LC_foo, LANG, in that order. The first
421 of these variables that is set specifies the locale. For example, if
422 LC_ALL is not set, but LC_MESSAGES is set to pt_BR, then the Brazilian
423 Portuguese locale is used for the LC_MESSAGES category. The C locale
424 is used if none of these environment variables are set, if the locale
425 catalog is not installed, or if grep was not compiled with national
426 language support (NLS).
427 GREP_OPTIONS
429 This variable specifies default options to be placed in front of
430 any explicit options. For example, if GREP_OPTIONS is
431 '--binary-files=without-match --directories=skip', grep behaves
432 as if the two options --binary-files=without-match and
433 --directories=skip had been specified before any explicit
434 options. Option specifications are separated by whitespace. A
435 backslash escapes the next character, so it can be used to
436 specify an option containing whitespace or a backslash.
437 GREP_COLOR
439 This variable specifies the color used to highlight matched
440 (non-empty) text. It is deprecated in favor of GREP_COLORS, but
441 still supported. The mt, ms, and mc capabilities of GREP_COLORS
442 have priority over it. It can only specify the color used to
443 highlight the matching non-empty text in any matching line (a
444 selected line when the -v command-line option is omitted, or a
445 context line when -v is specified). The default is 01;31, which
446 means a bold red foreground text on the terminal's default
447 background.
448 GREP_COLORS
450 Specifies the colors and other attributes used to highlight
451 various parts of the output. Its value is a colon-separated
452 list of capabilities that defaults to
453 ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36 with the rv
454 and ne boolean capabilities omitted (i.e., false). Supported
455 capabilities are as follows.
456 sl= SGR substring for whole selected lines (i.e., matching
458 lines when the -v command-line option is omitted, or non-
459 matching lines when -v is specified). If however the
460 boolean rv capability and the -v command-line option are
461 both specified, it applies to context matching lines
462 instead. The default is empty (i.e., the terminal's
463 default color pair).
464 cx= SGR substring for whole context lines (i.e., non-matching
466 lines when the -v command-line option is omitted, or
467 matching lines when -v is specified). If however the
468 boolean rv capability and the -v command-line option are
469 both specified, it applies to selected non-matching lines
470 instead. The default is empty (i.e., the terminal's
471 default color pair).
472 rv Boolean value that reverses (swaps) the meanings of the
474 sl= and cx= capabilities when the -v command-line option
475 is specified. The default is false (i.e., the capability
476 is omitted).
477 mt=01;31
479 SGR substring for matching non-empty text in any matching
480 line (i.e., a selected line when the -v command-line
481 option is omitted, or a context line when -v is
482 specified). Setting this is equivalent to setting both
483 ms= and mc= at once to the same value. The default is a
484 bold red text foreground over the current line
485 background.
486 ms=01;31
488 SGR substring for matching non-empty text in a selected
489 line. (This is only used when the -v command-line option
490 is omitted.) The effect of the sl= (or cx= if rv)
491 capability remains active when this kicks in. The
492 default is a bold red text foreground over the current
493 line background.
494 mc=01;31
496 SGR substring for matching non-empty text in a context
497 line. (This is only used when the -v command-line option
498 is specified.) The effect of the cx= (or sl= if rv)
499 capability remains active when this kicks in. The
500 default is a bold red text foreground over the current
501 line background.
502 fn=35 SGR substring for file names prefixing any content line.
504 The default is a magenta text foreground over the
505 terminal's default background.
506 ln=32 SGR substring for line numbers prefixing any content
508 line. The default is a green text foreground over the
509 terminal's default background.
510 bn=32 SGR substring for byte offsets prefixing any content
512 line. The default is a green text foreground over the
513 terminal's default background.
514 se=36 SGR substring for separators that are inserted between
516 selected line fields (:), between context line fields,
517 (-), and between groups of adjacent lines when nonzero
518 context is specified (--). The default is a cyan text
519 foreground over the terminal's default background.
520 ne Boolean value that prevents clearing to the end of line
522 using Erase in Line (EL) to Right (\33[K) each time a
523 colorized item ends. This is needed on terminals on
524 which EL is not supported. It is otherwise useful on
525 terminals for which the back_color_erase (bce) boolean
526 terminfo capability does not apply, when the chosen
527 highlight colors do not affect the background, or when EL
528 is too slow or causes too much flicker. The default is
529 false (i.e., the capability is omitted).
530 Note that boolean capabilities have no =... part. They are
532 omitted (i.e., false) by default and become true when specified.
533 See the Select Graphic Rendition (SGR) section in the
535 documentation of the text terminal that is used for permitted
536 values and their meaning as character attributes. These
537 substring values are integers in decimal representation and can
538 be concatenated with semicolons. grep takes care of assembling
539 the result into a complete SGR sequence (\33[...m). Common
540 values to concatenate include 1 for bold, 4 for underline, 5 for
541 blink, 7 for inverse, 39 for default foreground color, 30 to 37
542 for foreground colors, 90 to 97 for 16-color mode foreground
543 colors, 38;5;0 to 38;5;255 for 88-color and 256-color modes
544 foreground colors, 49 for default background color, 40 to 47 for
545 background colors, 100 to 107 for 16-color mode background
546 colors, and 48;5;0 to 48;5;255 for 88-color and 256-color modes
547 background colors.
548 LC_ALL, LC_COLLATE, LANG
550 These variables specify the locale for the LC_COLLATE category,
551 which determines the collating sequence used to interpret range
552 expressions like [a-z].
553 LC_ALL, LC_CTYPE, LANG
555 These variables specify the locale for the LC_CTYPE category,
556 which determines the type of characters, e.g., which characters
557 are whitespace.
558 LC_ALL, LC_MESSAGES, LANG
560 These variables specify the locale for the LC_MESSAGES category,
561 which determines the language that grep uses for messages. The
562 default C locale uses American English messages.
563 POSIXLY_CORRECT
565 If set, grep behaves as POSIX.2 requires; otherwise, grep
566 behaves more like other GNU programs. POSIX.2 requires that
567 options that follow file names must be treated as file names; by
568 default, such options are permuted to the front of the operand
569 list and are treated as options. Also, POSIX.2 requires that
570 unrecognized options be diagnosed as “illegal”, but since they
571 are not really against the law the default is to diagnose them
572 as “invalid”. POSIXLY_CORRECT also disables
573 _N_GNU_nonoption_argv_flags_, described below.
574 _N_GNU_nonoption_argv_flags_
576 (Here N is grep's numeric process ID.) If the ith character of
577 this environment variable's value is 1, do not consider the ith
578 operand of grep to be an option, even if it appears to be one.
579 A shell can put this variable in the environment for each
580 command it runs, specifying which operands are the results of
581 file name wildcard expansion and therefore should not be treated
582 as options. This behavior is available only with the GNU C
583 library, and only when POSIXLY_CORRECT is not set.
584
586 Normally, the exit status is 0 if selected lines are found and 1
587 otherwise. But the exit status is 2 if an error occurred, unless the
588 -q or --quiet or --silent option is used and a selected line is found.
589 Note, however, that POSIX only mandates, for programs such as grep,
590 cmp, and diff, that the exit status in case of error be greater than 1;
591 it is therefore advisable, for the sake of portability, to use logic
592 that tests for this general condition instead of strict equality
593 with 2.
594
596 Copyright 1998-2000, 2002, 2005-2011 Free Software Foundation, Inc.
597 This is free software; see the source for copying conditions. There is
599 NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
600 PURPOSE.
601
603 Reporting Bugs
604 Email bug reports to <bug-grep@gnu.org>, a mailing list whose web page
605 is <http://lists.gnu.org/mailman/listinfo/bug-grep>. grep's Savannah
606 bug tracker is located at <http://savannah.gnu.org/bugs/?group=grep>.
607 Known Bugs
609 Large repetition counts in the {n,m} construct may cause grep to use
610 lots of memory. In addition, certain other obscure regular expressions
611 require exponential time and space, and may cause grep to run out of
612 memory.
613 Back-references are very slow, and may require exponential time.
615
617 Regular Manual Pages
618 awk(1), cmp(1), diff(1), find(1), gzip(1), perl(1), sed(1), sort(1),
619 xargs(1), zgrep(1), mmap(2), read(2), pcre(3), pcresyntax(3),
620 pcrepattern(3), terminfo(5), glob(7), regex(7).
621 POSIX Programmer's Manual Page
623 grep(1p).
624 TeXinfo Documentation
626 The full documentation for grep is maintained as a TeXinfo manual. If
627 the info and grep programs are properly installed at your site, the
628 command
629 info grep
631 should give you access to the complete manual.
633
635 GNU's not Unix, but Unix is a beast; its plural form is Unixen.
636User Commands GNU grep 2.8 GREP(1)