5 . if \w'\(lq' .ds lq "\(lq
9 . if \w'\(rq' .ds rq "\(rq
12 .ie t .ds Tx \s-1T\v'.4n'\h'-.1667'E\v'-.4n'\h'-.125'X\s0
21 . \" ISO 8601 date, complete format, extended representation
22 . ds Dt \\*(Yr-\\*(Mn-\\*(Dy
24 .TH GREP 1 \*(Dt "GNU grep 2.6.3" "User Commands"
28 grep, egrep, fgrep \- print lines matching a pattern
47 searches the named input
49 (or standard input if no files are named,
50 or if a single hyphen-minus
52 is given as file name)
53 for lines containing a match to the given
57 prints the matching lines.
59 In addition, two variant programs
70 Direct invocation as either
75 but is provided to allow historical applications
76 that rely on them to run unmodified.
79 .SS "Generic Program Information"
82 Print a usage message briefly summarizing these command-line options
83 and the bug-reporting address, then exit.
85 .BR \-V ", " \-\^\-version
86 Print the version number of
88 to the standard output stream.
89 This version number should
90 be included in all bug reports (see below).
91 .SS "Matcher Selection"
93 .BR \-E ", " \-\^\-extended\-regexp
96 as an extended regular expression (ERE, see below).
98 is specified by \s-1POSIX\s0.)
100 .BR \-F ", " \-\^\-fixed\-strings
103 as a list of fixed strings, separated by newlines,
104 any of which is to be matched.
106 is specified by \s-1POSIX\s0.)
108 .BR \-G ", " \-\^\-basic\-regexp
111 as a basic regular expression (BRE, see below).
114 .BR \-P ", " \-\^\-perl\-regexp
117 as a Perl regular expression.
118 This is highly experimental and
120 may warn of unimplemented features.
121 .SS "Matching Control"
123 .BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
127 This can be used to specify multiple search patterns,
128 or to protect a pattern beginning with a hyphen
131 is specified by \s-1POSIX\s0.)
133 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
137 The empty file contains zero patterns, and therefore matches nothing.
139 is specified by \s-1POSIX\s0.)
141 .BR \-i ", " \-\^\-ignore\-case
142 Ignore case distinctions in both the
146 is specified by \s-1POSIX\s0.)
148 .BR \-v ", " \-\^\-invert\-match
149 Invert the sense of matching, to select non-matching lines.
151 is specified by \s-1POSIX\s0.)
153 .BR \-w ", " \-\^\-word\-regexp
154 Select only those lines containing matches that form whole words.
155 The test is that the matching substring must either be at the
156 beginning of the line, or preceded by a non-word constituent
158 Similarly, it must be either at the end of the line
159 or followed by a non-word constituent character.
160 Word-constituent characters are letters, digits, and the underscore.
162 .BR \-x ", " \-\^\-line\-regexp
163 Select only those matches that exactly match the whole line.
165 is specified by \s-1POSIX\s0.)
170 .SS "General Output Control"
172 .BR \-c ", " \-\^\-count
173 Suppress normal output; instead print a count of
174 matching lines for each input file.
176 .BR \-v ", " \-\^\-invert\-match
177 option (see below), count non-matching lines.
179 is specified by \s-1POSIX\s0.)
181 .BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
182 Surround the matched (non-empty) strings, matching lines, context lines,
183 file names, line numbers, byte offsets, and separators (for fields and
184 groups of context lines) with escape sequences to display them in color
186 The colors are defined by the environment variable
188 The deprecated environment variable
190 is still supported, but its setting does not have priority.
193 .BR never ", " always ", or " auto .
195 .BR \-L ", " \-\^\-files\-without\-match
196 Suppress normal output; instead print the name
197 of each input file from which no output would
198 normally have been printed.
199 The scanning will stop on the first match.
201 .BR \-l ", " \-\^\-files\-with\-matches
202 Suppress normal output; instead print
203 the name of each input file from which output
204 would normally have been printed.
205 The scanning will stop on the first match.
207 is specified by \s-1POSIX\s0.)
209 .BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM
210 Stop reading a file after
213 If the input is standard input from a regular file,
216 matching lines are output,
218 ensures that the standard input is positioned to just after the last
219 matching line before exiting, regardless of the presence of trailing
221 This enables a calling process to resume a search.
226 matching lines, it outputs any trailing context lines.
233 does not output a count greater than
238 .B \-\^\-invert\-match
241 stops after outputting
245 .BR \-o ", " \-\^\-only\-matching
246 Print only the matched (non-empty) parts of a matching line,
247 with each such part on a separate output line.
249 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
250 Quiet; do not write anything to standard output.
251 Exit immediately with zero status if any match is found,
252 even if an error was detected.
256 .B \-\^\-no\-messages
259 is specified by \s-1POSIX\s0.)
261 .BR \-s ", " \-\^\-no\-messages
262 Suppress error messages about nonexistent or unreadable files.
263 Portability note: unlike \s-1GNU\s0
267 did not conform to \s-1POSIX\s0, because it lacked
271 option behaved like \s-1GNU\s0
281 option behaved like \s-1GNU\s0
283 Portable shell scripts
288 and should redirect standard and error output to
292 is specified by \s-1POSIX\s0.)
293 .SS "Output Line Prefix Control"
295 .BR \-b ", " \-\^\-byte\-offset
296 Print the 0-based byte offset within the input file
297 before each line of output.
300 .RB ( \-\^\-only\-matching )
302 print the offset of the matching part itself.
304 .BR \-H ", " \-\^\-with\-filename
305 Print the file name for each match.
306 This is the default when there is more than one file to search.
308 .BR \-h ", " \-\^\-no\-filename
309 Suppress the prefixing of file names on output.
310 This is the default when there is only one file
311 (or only standard input) to search.
313 .BI \-\^\-label= LABEL
314 Display input actually coming from standard input as input coming from file
316 This is especially useful when implementing tools like
319 .BR "gzip -cd foo.gz | grep --label=foo -H something" .
324 .BR \-n ", " \-\^\-line\-number
325 Prefix each line of output with the 1-based line number
326 within its input file.
328 is specified by \s-1POSIX\s0.)
330 .BR \-T ", " \-\^\-initial\-tab
331 Make sure that the first character of actual line content lies on a
332 tab stop, so that the alignment of tabs looks normal.
333 This is useful with options that prefix their output to the actual content:
337 In order to improve the probability that lines
338 from a single file will all start at the same column,
339 this also causes the line number and byte offset (if present)
340 to be printed in a minimum size field width.
342 .BR \-u ", " \-\^\-unix\-byte\-offsets
343 Report Unix-style byte offsets.
346 to report byte offsets as if the file were a Unix-style text file,
347 i.e., with CR characters stripped off.
348 This will produce results identical to running
351 This option has no effect unless
354 it has no effect on platforms other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
356 .BR \-Z ", " \-\^\-null
357 Output a zero byte (the \s-1ASCII\s0
359 character) instead of the character that normally follows a file name.
362 outputs a zero byte after each file name instead of the usual newline.
363 This option makes the output unambiguous, even in the presence of file
364 names containing unusual characters like newlines.
365 This option can be used with commands like
366 .BR "find \-print0" ,
371 to process arbitrary file names,
372 even those that contain newline characters.
373 .SS "Context Line Control"
375 .BI \-A " NUM" "\fR,\fP \-\^\-after\-context=" NUM
378 lines of trailing context after matching lines.
379 Places a line containing a group separator
381 between contiguous groups of matches.
385 .B \-\^\-only\-matching
386 option, this has no effect and a warning is given.
388 .BI \-B " NUM" "\fR,\fP \-\^\-before\-context=" NUM
391 lines of leading context before matching lines.
392 Places a line containing a group separator
394 between contiguous groups of matches.
398 .B \-\^\-only\-matching
399 option, this has no effect and a warning is given.
401 .BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM
404 lines of output context.
405 Places a line containing a group separator
407 between contiguous groups of matches.
411 .B \-\^\-only\-matching
412 option, this has no effect and a warning is given.
413 .SS "File and Directory Selection"
415 .BR \-a ", " \-\^\-text
416 Process a binary file as if it were text; this is equivalent to the
417 .B \-\^\-binary\-files=text
420 .BI \-\^\-binary\-files= TYPE
421 If the first few bytes of a file indicate that the file contains binary
422 data, assume that the file is of type
430 normally outputs either
431 a one-line message saying that a binary file matches, or no message if
438 assumes that a binary file does not match; this is equivalent to the
446 processes a binary file as if it were text; this is equivalent to the
450 .B "grep \-\^\-binary\-files=text"
451 might output binary garbage,
452 which can have nasty side effects if the output is a terminal and if the
453 terminal driver interprets some of it as commands.
455 .BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
456 If an input file is a device, FIFO or socket, use
463 which means that devices are read just as if they were ordinary files.
468 devices are silently skipped.
470 .BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
471 If an input file is a directory, use
478 which means that directories are read just as if they were ordinary files.
483 directories are silently skipped.
489 reads all files under each directory, recursively;
490 this is equivalent to the
494 .BI \-\^\-exclude= GLOB
495 Skip files whose base name matches
497 (using wildcard matching).
498 A file-name glob can use
505 to quote a wildcard or backslash character literally.
507 .BI \-\^\-exclude-from= FILE
508 Skip files whose base name matches any of the file-name globs read from
510 (using wildcard matching as described under
513 .BI \-\^\-exclude-dir= DIR
514 Exclude directories matching the pattern
516 from recursive searches.
519 Process a binary file as if it did not contain matching data; this is
521 .B \-\^\-binary\-files=without-match
524 .BI \-\^\-include= GLOB
525 Search only files whose base name matches
527 (using wildcard matching as described under
530 .BR \-R ", " \-r ", " \-\^\-recursive
531 Read all files under each directory, recursively;
532 this is equivalent to the
537 .BR \-\^\-line\-buffered
538 Use line buffering on output.
539 This can cause a performance penalty.
544 system call to read input, instead of
550 yields better performance.
553 can cause undefined behavior (including core dumps)
554 if an input file shrinks while
556 is operating, or if an I/O error occurs.
558 .BR \-U ", " \-\^\-binary
559 Treat the file(s) as binary.
560 By default, under \s-1MS-DOS\s0 and \s-1MS\s0-Windows,
562 guesses the file type by looking at the contents of the first 32KB
566 decides the file is a text file, it strips the CR characters from the
567 original file contents (to make regular expressions with
574 overrules this guesswork, causing all files to be read and passed to the
575 matching mechanism verbatim; if the file is a text file with CR/LF
576 pairs at the end of each line, this will cause some regular
578 This option has no effect on platforms
579 other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
581 .BR \-z ", " \-\^\-null\-data
582 Treat the input as a set of lines,
583 each terminated by a zero byte (the \s-1ASCII\s0
585 character) instead of a newline.
590 option, this option can be used with commands like
592 to process arbitrary file names.
594 .SH "REGULAR EXPRESSIONS"
595 A regular expression is a pattern that describes a set of strings.
596 Regular expressions are constructed analogously to arithmetic
597 expressions, by using various operators to combine smaller expressions.
600 understands three different versions of regular expression syntax:
601 \*(lqbasic,\*(rq \*(lqextended\*(rq and \*(lqperl.\*(rq In
602 .RB "\s-1GNU\s0\ " grep ,
603 there is no difference in available functionality between basic and
605 In other implementations, basic regular expressions are less powerful.
606 The following description applies to extended regular expressions;
607 differences for basic regular expressions are summarized afterwards.
608 Perl regular expressions give additional functionality, and are
609 documented in pcresyntax(3) and pcrepattern(3), but may not be
610 available on every system.
612 The fundamental building blocks are the regular expressions
613 that match a single character.
614 Most characters, including all letters and digits,
615 are regular expressions that match themselves.
616 Any meta-character with special meaning
617 may be quoted by preceding it with a backslash.
621 matches any single character.
622 .SS "Character Classes and Bracket Expressions"
624 .I "bracket expression"
625 is a list of characters enclosed by
629 It matches any single
630 character in that list; if the first character of the list
633 then it matches any character
636 For example, the regular expression
638 matches any single digit.
640 Within a bracket expression, a
641 .I "range expression"
642 consists of two characters separated by a hyphen.
643 It matches any single character that sorts between the two characters,
644 inclusive, using the locale's collating sequence and character set.
645 For example, in the default C locale,
649 Many locales sort characters in dictionary order, and in these locales
651 is typically not equivalent to
653 it might be equivalent to
656 To obtain the traditional interpretation of bracket expressions,
657 you can use the C locale by setting the
659 environment variable to the value
662 Finally, certain named classes of characters are predefined within
663 bracket expressions, as follows.
664 Their names are self explanatory, and they are
681 except the latter form depends upon the C locale and the
682 \s-1ASCII\s0 character encoding, whereas the former is independent
683 of locale and character set.
684 (Note that the brackets in these class names are part of the symbolic
685 names, and must be included in addition to the brackets delimiting
686 the bracket expression.)
687 Most meta-characters lose their special meaning inside bracket expressions.
690 place it first in the list.
691 Similarly, to include a literal
693 place it anywhere but first.
694 Finally, to include a literal
702 are meta-characters that respectively match the empty string at the
703 beginning and end of a line.
704 .SS "The Backslash Character and Special Expressions"
709 respectively match the empty string at the beginning and end of a word.
712 matches the empty string at the edge of a word,
715 matches the empty string provided it's
717 at the edge of a word.
727 A regular expression may be followed by one of several repetition operators:
731 The preceding item is optional and matched at most once.
734 The preceding item will be matched zero or more times.
737 The preceding item will be matched one or more times.
740 The preceding item is matched exactly
745 The preceding item is matched
750 The preceding item is matched at most
755 The preceding item is matched at least
757 times, but not more than
762 Two regular expressions may be concatenated; the resulting
763 regular expression matches any string formed by concatenating
764 two substrings that respectively match the concatenated
767 Two regular expressions may be joined by the infix operator
769 the resulting regular expression matches any string matching
770 either alternate expression.
772 Repetition takes precedence over concatenation, which in turn
773 takes precedence over alternation.
774 A whole expression may be enclosed in parentheses
775 to override these precedence rules and form a subexpression.
776 .SS "Back References and Subexpressions"
781 is a single digit, matches the substring
782 previously matched by the
784 parenthesized subexpression of the regular expression.
785 .SS "Basic vs Extended Regular Expressions"
786 In basic regular expressions the meta-characters
794 lose their special meaning; instead use the backslashed
808 meta-character, and some
810 implementations support
812 instead, so portable scripts should avoid
816 patterns and should use
823 attempts to support traditional usage by assuming that
825 is not special if it would be the start of an invalid interval
827 For example, the command
829 searches for the two-character string
831 instead of reporting a syntax error in the regular expression.
832 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
835 .SH "ENVIRONMENT VARIABLES"
838 is affected by the following environment variables.
840 The locale for category
842 is specified by examining the three environment variables
847 The first of these variables that is set specifies the locale.
854 then the Brazilian Portuguese locale is used for the
857 The C locale is used if none of these environment variables are set,
858 if the locale catalog is not installed, or if
860 was not compiled with national language support (\s-1NLS\s0).
863 This variable specifies default options
864 to be placed in front of any explicit options.
868 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
870 behaves as if the two options
871 .B \-\^\-binary\-files=without-match
873 .B \-\^\-directories=skip
874 had been specified before any explicit options.
875 Option specifications are separated by whitespace.
876 A backslash escapes the next character,
877 so it can be used to specify an option containing whitespace or a backslash.
880 This variable specifies the color used to highlight matched (non-empty) text.
881 It is deprecated in favor of
891 have priority over it.
892 It can only specify the color used to highlight
893 the matching non-empty text in any matching line
894 (a selected line when the
896 command-line option is omitted,
897 or a context line when
902 which means a bold red foreground text on the terminal's default background.
905 Specifies the colors and other attributes
906 used to highlight various parts of the output.
907 Its value is a colon-separated list of capabilities
909 .B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
914 boolean capabilities omitted (i.e., false).
915 Supported capabilities are as follows.
919 SGR substring for whole selected lines
921 matching lines when the
923 command-line option is omitted,
924 or non-matching lines when
927 If however the boolean
932 command-line option are both specified,
933 it applies to context matching lines instead.
934 The default is empty (i.e., the terminal's default color pair).
937 SGR substring for whole context lines
939 non-matching lines when the
941 command-line option is omitted,
942 or matching lines when
945 If however the boolean
950 command-line option are both specified,
951 it applies to selected non-matching lines instead.
952 The default is empty (i.e., the terminal's default color pair).
955 Boolean value that reverses (swaps) the meanings of
963 command-line option is specified.
964 The default is false (i.e., the capability is omitted).
967 SGR substring for matching non-empty text in any matching line
969 a selected line when the
971 command-line option is omitted,
972 or a context line when
975 Setting this is equivalent to setting both
979 at once to the same value.
980 The default is a bold red text foreground over the current line background.
983 SGR substring for matching non-empty text in a selected line.
984 (This is only used when the
986 command-line option is omitted.)
993 capability remains active when this kicks in.
994 The default is a bold red text foreground over the current line background.
997 SGR substring for matching non-empty text in a context line.
998 (This is only used when the
1000 command-line option is specified.)
1007 capability remains active when this kicks in.
1008 The default is a bold red text foreground over the current line background.
1011 SGR substring for file names prefixing any content line.
1012 The default is a magenta text foreground over the terminal's default background.
1015 SGR substring for line numbers prefixing any content line.
1016 The default is a green text foreground over the terminal's default background.
1019 SGR substring for byte offsets prefixing any content line.
1020 The default is a green text foreground over the terminal's default background.
1023 SGR substring for separators that are inserted
1024 between selected line fields
1026 between context line fields,
1028 and between groups of adjacent lines when nonzero context is specified
1030 The default is a cyan text foreground over the terminal's default background.
1033 Boolean value that prevents clearing to the end of line
1034 using Erase in Line (EL) to Right
1036 each time a colorized item ends.
1037 This is needed on terminals on which EL is not supported.
1038 It is otherwise useful on terminals
1042 boolean terminfo capability does not apply,
1043 when the chosen highlight colors do not affect the background,
1044 or when EL is too slow or causes too much flicker.
1045 The default is false (i.e., the capability is omitted).
1047 Note that boolean capabilities have no
1050 They are omitted (i.e., false) by default and become true when specified.
1052 See the Select Graphic Rendition (SGR) section
1053 in the documentation of the text terminal that is used
1054 for permitted values and their meaning as character attributes.
1055 These substring values are integers in decimal representation
1056 and can be concatenated with semicolons.
1058 takes care of assembling the result
1059 into a complete SGR sequence
1060 .RB ( \\\\\\33[ ... m ).
1061 Common values to concatenate include
1071 for default foreground color,
1075 for foreground colors,
1079 for 16-color mode foreground colors,
1083 for 88-color and 256-color modes foreground colors,
1085 for default background color,
1089 for background colors,
1093 for 16-color mode background colors, and
1097 for 88-color and 256-color modes background colors.
1100 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
1101 These variables specify the locale for the
1104 which determines the collating sequence
1105 used to interpret range expressions like
1108 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
1109 These variables specify the locale for the
1112 which determines the type of characters,
1113 e.g., which characters are whitespace.
1115 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
1116 These variables specify the locale for the
1119 which determines the language that
1122 The default C locale uses American English messages.
1127 behaves as \s-1POSIX.2\s0 requires; otherwise,
1129 behaves more like other \s-1GNU\s0 programs.
1130 \s-1POSIX.2\s0 requires that options that follow file names must be
1131 treated as file names; by default, such options are permuted to the
1132 front of the operand list and are treated as options.
1133 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
1134 \*(lqillegal\*(rq, but since they are not really against the law the default
1135 is to diagnose them as \*(lqinvalid\*(rq.
1137 also disables \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP,
1140 \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP
1145 numeric process ID.) If the
1147 character of this environment variable's value is
1153 to be an option, even if it appears to be one.
1154 A shell can put this variable in the environment for each command it runs,
1155 specifying which operands are the results of file name wildcard
1156 expansion and therefore should not be treated as options.
1157 This behavior is available only with the \s-1GNU\s0 C library, and only
1163 Normally, the exit status is 0 if selected lines are found and 1 otherwise.
1164 But the exit status is 2 if an error occurred, unless the
1170 option is used and a selected line is found.
1171 Note, however, that \s-1POSIX\s0 only mandates, for programs such as
1176 that the exit status in case of error be greater than 1;
1177 it is therefore advisable, for the sake of portability,
1178 to use logic that tests for this general condition
1179 instead of strict equality with\ 2.
1182 Copyright 1998-2000, 2002, 2005-2010 Free Software Foundation, Inc.
1184 This is free software;
1185 see the source for copying conditions.
1186 There is NO warranty;
1187 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1190 .SS "Reporting Bugs"
1191 Email bug reports to
1192 .RB < bug\-grep@gnu.org >,
1193 a mailing list whose web page is
1194 .RB < http://lists.gnu.org/mailman/listinfo/bug\-grep >.
1196 Savannah bug tracker is located at
1197 .RB < http://savannah.gnu.org/bugs/?group=grep >.
1199 Large repetition counts in the
1203 to use lots of memory.
1205 certain other obscure regular expressions require exponential time
1206 and space, and may cause
1208 to run out of memory.
1210 Back-references are very slow, and may require exponential time.
1213 .SS "Regular Manual Pages"
1214 awk(1), cmp(1), diff(1), find(1), gzip(1),
1215 perl(1), sed(1), sort(1), xargs(1), zgrep(1),
1217 pcre(3), pcresyntax(3), pcrepattern(3),
1220 .SS "\s-1POSIX\s0 Programmer's Manual Page"
1222 .SS "\*(Txinfo Documentation"
1223 The full documentation for
1225 is maintained as a \*(Txinfo manual.
1230 programs are properly installed at your site, the command
1234 should give you access to the complete manual.
1237 \s-1GNU\s0's not Unix, but Unix is a beast;
1238 its plural form is Unixen.
1239 .\" Work around problems with some troff -man implementations.