5 . if \w'\(lq' .ds lq "\(lq
9 . if \w'\(rq' .ds rq "\(rq
13 .ie \n[.g] .mso www.tmac
16 \\$2 \(laemail: \\$1 \(ra\\$3
19 \\$2 \(laURL: \\$1 \(ra\\$3
23 .TH GREP 1 \*(Dt "GNU grep 2.22" "User Commands"
27 grep, egrep, fgrep \- print lines matching a pattern
46 searches the named input
48 for lines containing a match to the given
50 If no files are specified, or if the file
51 .RB "\*(lq" \- "\*(rq"
54 searches standard input.
57 prints the matching lines.
59 In addition, the variant programs
68 These variants are deprecated, but are provided for backward compatibility.
71 .SS "Generic Program Information"
74 Output a usage message and exit.
76 .BR \-V ", " \-\^\-version
77 Output the version number of
80 .SS "Matcher Selection"
82 .BR \-E ", " \-\^\-extended\-regexp
85 as an extended regular expression (ERE, see below).
87 .BR \-F ", " \-\^\-fixed\-strings
90 as a list of fixed strings, separated by newlines,
91 any of which is to be matched.
93 .BR \-G ", " \-\^\-basic\-regexp
96 as a basic regular expression (BRE, see below).
99 .BR \-P ", " \-\^\-perl\-regexp
102 as a Perl regular expression.
103 This is highly experimental and
105 may warn of unimplemented features.
106 .SS "Matching Control"
108 .BI \-e " PATTERN" "\fR,\fP \-\^\-regexp=" PATTERN
112 This can be used to specify multiple search patterns,
113 or to protect a pattern beginning with a hyphen
116 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
120 The empty file contains zero patterns, and therefore matches nothing.
122 .BR \-i ", " \-\^\-ignore\-case
123 Ignore case distinctions in both the
127 .BR \-v ", " \-\^\-invert\-match
128 Invert the sense of matching, to select non-matching lines.
130 .BR \-w ", " \-\^\-word\-regexp
131 Select only those lines containing matches that form whole words.
132 The test is that the matching substring must either be at the
133 beginning of the line, or preceded by a non-word constituent
135 Similarly, it must be either at the end of the line
136 or followed by a non-word constituent character.
137 Word-constituent characters are letters, digits, and the underscore.
139 .BR \-x ", " \-\^\-line\-regexp
140 Select only those matches that exactly match the whole line.
145 .SS "General Output Control"
147 .BR \-c ", " \-\^\-count
148 Suppress normal output; instead print a count of
149 matching lines for each input file.
151 .BR \-v ", " \-\^\-invert\-match
152 option (see below), count non-matching lines.
154 .BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
155 Surround the matched (non-empty) strings, matching lines, context lines,
156 file names, line numbers, byte offsets, and separators (for fields and
157 groups of context lines) with escape sequences to display them in color
159 The colors are defined by the environment variable
161 The deprecated environment variable
163 is still supported, but its setting does not have priority.
166 .BR never ", " always ", or " auto .
168 .BR \-L ", " \-\^\-files\-without\-match
169 Suppress normal output; instead print the name
170 of each input file from which no output would
171 normally have been printed.
172 The scanning will stop on the first match.
174 .BR \-l ", " \-\^\-files\-with\-matches
175 Suppress normal output; instead print
176 the name of each input file from which output
177 would normally have been printed.
178 The scanning will stop on the first match.
180 .BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM
181 Stop reading a file after
184 If the input is standard input from a regular file,
187 matching lines are output,
189 ensures that the standard input is positioned to just after the last
190 matching line before exiting, regardless of the presence of trailing
192 This enables a calling process to resume a search.
197 matching lines, it outputs any trailing context lines.
204 does not output a count greater than
209 .B \-\^\-invert\-match
212 stops after outputting
216 .BR \-o ", " \-\^\-only\-matching
217 Print only the matched (non-empty) parts of a matching line,
218 with each such part on a separate output line.
220 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
221 Quiet; do not write anything to standard output.
222 Exit immediately with zero status if any match is found,
223 even if an error was detected.
227 .B \-\^\-no\-messages
230 .BR \-s ", " \-\^\-no\-messages
231 Suppress error messages about nonexistent or unreadable files.
232 .SS "Output Line Prefix Control"
234 .BR \-b ", " \-\^\-byte\-offset
235 Print the 0-based byte offset within the input file
236 before each line of output.
239 .RB ( \-\^\-only\-matching )
241 print the offset of the matching part itself.
243 .BR \-H ", " \-\^\-with\-filename
244 Print the file name for each match.
245 This is the default when there is more than one file to search.
247 .BR \-h ", " \-\^\-no\-filename
248 Suppress the prefixing of file names on output.
249 This is the default when there is only one file
250 (or only standard input) to search.
252 .BI \-\^\-label= LABEL
253 Display input actually coming from standard input as input coming from file
255 This is especially useful when implementing tools like
258 .BR "gzip -cd foo.gz | grep --label=foo -H something" .
263 .BR \-n ", " \-\^\-line\-number
264 Prefix each line of output with the 1-based line number
265 within its input file.
267 .BR \-T ", " \-\^\-initial\-tab
268 Make sure that the first character of actual line content lies on a
269 tab stop, so that the alignment of tabs looks normal.
270 This is useful with options that prefix their output to the actual content:
274 In order to improve the probability that lines
275 from a single file will all start at the same column,
276 this also causes the line number and byte offset (if present)
277 to be printed in a minimum size field width.
279 .BR \-u ", " \-\^\-unix\-byte\-offsets
280 Report Unix-style byte offsets.
283 to report byte offsets as if the file were a Unix-style text file,
284 i.e., with CR characters stripped off.
285 This will produce results identical to running
288 This option has no effect unless
291 it has no effect on platforms other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
293 .BR \-Z ", " \-\^\-null
294 Output a zero byte (the \s-1ASCII\s0
296 character) instead of the character that normally follows a file name.
299 outputs a zero byte after each file name instead of the usual newline.
300 This option makes the output unambiguous, even in the presence of file
301 names containing unusual characters like newlines.
302 This option can be used with commands like
303 .BR "find \-print0" ,
308 to process arbitrary file names,
309 even those that contain newline characters.
310 .SS "Context Line Control"
312 .BI \-A " NUM" "\fR,\fP \-\^\-after\-context=" NUM
315 lines of trailing context after matching lines.
316 Places a line containing a group separator
318 between contiguous groups of matches.
322 .B \-\^\-only\-matching
323 option, this has no effect and a warning is given.
325 .BI \-B " NUM" "\fR,\fP \-\^\-before\-context=" NUM
328 lines of leading context before matching lines.
329 Places a line containing a group separator
331 between contiguous groups of matches.
335 .B \-\^\-only\-matching
336 option, this has no effect and a warning is given.
338 .BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM
341 lines of output context.
342 Places a line containing a group separator
344 between contiguous groups of matches.
348 .B \-\^\-only\-matching
349 option, this has no effect and a warning is given.
350 .SS "File and Directory Selection"
352 .BR \-a ", " \-\^\-text
353 Process a binary file as if it were text; this is equivalent to the
354 .B \-\^\-binary\-files=text
357 .BI \-\^\-binary\-files= TYPE
358 If the first few bytes of a file indicate that the file contains binary
359 data, assume that the file is of type
367 normally outputs either
368 a one-line message saying that a binary file matches, or no message if
375 assumes that a binary file does not match; this is equivalent to the
383 processes a binary file as if it were text; this is equivalent to the
386 When processing binary data,
388 may treat non-text bytes as line terminators; for example, the pattern
390 (period) might not match a null byte, as the null byte might be
391 treated as a line terminator.
393 .B "grep \-\^\-binary\-files=text"
394 might output binary garbage,
395 which can have nasty side effects if the output is a terminal and if the
396 terminal driver interprets some of it as commands.
398 .BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
399 If an input file is a device, FIFO or socket, use
406 which means that devices are read just as if they were ordinary files.
411 devices are silently skipped.
413 .BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
414 If an input file is a directory, use
421 i.e., read directories just as if they were ordinary files.
426 silently skip directories.
431 read all files under each directory, recursively,
432 following symbolic links only if they are on the command line.
433 This is equivalent to the
437 .BI \-\^\-exclude= GLOB
438 Skip files whose base name matches
440 (using wildcard matching).
441 A file-name glob can use
448 to quote a wildcard or backslash character literally.
450 .BI \-\^\-exclude-from= FILE
451 Skip files whose base name matches any of the file-name globs read from
453 (using wildcard matching as described under
456 .BI \-\^\-exclude-dir= DIR
457 Exclude directories matching the pattern
459 from recursive searches.
462 Process a binary file as if it did not contain matching data; this is
464 .B \-\^\-binary\-files=without-match
467 .BI \-\^\-include= GLOB
468 Search only files whose base name matches
470 (using wildcard matching as described under
473 .BR \-r ", " \-\^\-recursive
474 Read all files under each directory, recursively,
475 following symbolic links only if they are on the command line.
476 Note that if no file operand is given, grep searches the working directory.
477 This is equivalent to the
481 .BR \-R ", " \-\^\-dereference\-recursive
482 Read all files under each directory, recursively.
483 Follow all symbolic links, unlike
487 .BR \-\^\-line\-buffered
488 Use line buffering on output.
489 This can cause a performance penalty.
491 .BR \-U ", " \-\^\-binary
492 Treat the file(s) as binary.
493 By default, under \s-1MS-DOS\s0 and \s-1MS\s0-Windows,
495 guesses the file type by looking at the contents of the first 32KB
499 decides the file is a text file, it strips the CR characters from the
500 original file contents (to make regular expressions with
507 overrules this guesswork, causing all files to be read and passed to the
508 matching mechanism verbatim; if the file is a text file with CR/LF
509 pairs at the end of each line, this will cause some regular
511 This option has no effect on platforms
512 other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
514 .BR \-z ", " \-\^\-null\-data
515 Treat the input as a set of lines,
516 each terminated by a zero byte (the \s-1ASCII\s0
518 character) instead of a newline.
523 option, this option can be used with commands like
525 to process arbitrary file names.
527 .SH "REGULAR EXPRESSIONS"
528 A regular expression is a pattern that describes a set of strings.
529 Regular expressions are constructed analogously to arithmetic
530 expressions, by using various operators to combine smaller expressions.
533 understands three different versions of regular expression syntax:
534 \*(lqbasic,\*(rq \*(lqextended\*(rq and \*(lqperl.\*(rq In
535 .RB "\s-1GNU\s0\ " grep ,
536 there is no difference in available functionality between basic and
538 In other implementations, basic regular expressions are less powerful.
539 The following description applies to extended regular expressions;
540 differences for basic regular expressions are summarized afterwards.
541 Perl regular expressions give additional functionality, and are
542 documented in pcresyntax(3) and pcrepattern(3), but may not be
543 available on every system.
545 The fundamental building blocks are the regular expressions
546 that match a single character.
547 Most characters, including all letters and digits,
548 are regular expressions that match themselves.
549 Any meta-character with special meaning
550 may be quoted by preceding it with a backslash.
554 matches any single character.
555 .SS "Character Classes and Bracket Expressions"
557 .I "bracket expression"
558 is a list of characters enclosed by
562 It matches any single
563 character in that list; if the first character of the list
566 then it matches any character
569 For example, the regular expression
571 matches any single digit.
573 Within a bracket expression, a
574 .I "range expression"
575 consists of two characters separated by a hyphen.
576 It matches any single character that sorts between the two characters,
577 inclusive, using the locale's collating sequence and character set.
578 For example, in the default C locale,
582 Many locales sort characters in dictionary order, and in these locales
584 is typically not equivalent to
586 it might be equivalent to
589 To obtain the traditional interpretation of bracket expressions,
590 you can use the C locale by setting the
592 environment variable to the value
595 Finally, certain named classes of characters are predefined within
596 bracket expressions, as follows.
597 Their names are self explanatory, and they are
612 means the character class of numbers and
613 letters in the current locale. In the C locale and \s-1ASCII\s0
614 character set encoding, this is the same as
616 (Note that the brackets in these class names are part of the symbolic
617 names, and must be included in addition to the brackets delimiting
618 the bracket expression.)
619 Most meta-characters lose their special meaning inside bracket expressions.
622 place it first in the list.
623 Similarly, to include a literal
625 place it anywhere but first.
626 Finally, to include a literal
634 are meta-characters that respectively match the empty string at the
635 beginning and end of a line.
636 .SS "The Backslash Character and Special Expressions"
641 respectively match the empty string at the beginning and end of a word.
644 matches the empty string at the edge of a word,
647 matches the empty string provided it's
649 at the edge of a word.
659 A regular expression may be followed by one of several repetition operators:
663 The preceding item is optional and matched at most once.
666 The preceding item will be matched zero or more times.
669 The preceding item will be matched one or more times.
672 The preceding item is matched exactly
677 The preceding item is matched
682 The preceding item is matched at most
685 This is a \s-1GNU\s0 extension.
688 The preceding item is matched at least
690 times, but not more than
695 Two regular expressions may be concatenated; the resulting
696 regular expression matches any string formed by concatenating
697 two substrings that respectively match the concatenated
700 Two regular expressions may be joined by the infix operator
702 the resulting regular expression matches any string matching
703 either alternate expression.
705 Repetition takes precedence over concatenation, which in turn
706 takes precedence over alternation.
707 A whole expression may be enclosed in parentheses
708 to override these precedence rules and form a subexpression.
709 .SS "Back References and Subexpressions"
714 is a single digit, matches the substring
715 previously matched by the
717 parenthesized subexpression of the regular expression.
718 .SS "Basic vs Extended Regular Expressions"
719 In basic regular expressions the meta-characters
727 lose their special meaning; instead use the backslashed
737 .SH "ENVIRONMENT VARIABLES"
740 is affected by the following environment variables.
742 The locale for category
744 is specified by examining the three environment variables
749 The first of these variables that is set specifies the locale.
756 then the Brazilian Portuguese locale is used for the
759 The C locale is used if none of these environment variables are set,
760 if the locale catalog is not installed, or if
762 was not compiled with national language support (\s-1NLS\s0).
765 This variable specifies default options
766 to be placed in front of any explicit options.
767 As this causes problems when writing portable scripts,
768 this feature will be removed in a future release of
773 Please use an alias or script instead.
776 This variable specifies the color used to highlight matched (non-empty) text.
777 It is deprecated in favor of
787 have priority over it.
788 It can only specify the color used to highlight
789 the matching non-empty text in any matching line
790 (a selected line when the
792 command-line option is omitted,
793 or a context line when
798 which means a bold red foreground text on the terminal's default background.
801 Specifies the colors and other attributes
802 used to highlight various parts of the output.
803 Its value is a colon-separated list of capabilities
805 .B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
810 boolean capabilities omitted (i.e., false).
811 Supported capabilities are as follows.
815 SGR substring for whole selected lines
817 matching lines when the
819 command-line option is omitted,
820 or non-matching lines when
823 If however the boolean
828 command-line option are both specified,
829 it applies to context matching lines instead.
830 The default is empty (i.e., the terminal's default color pair).
833 SGR substring for whole context lines
835 non-matching lines when the
837 command-line option is omitted,
838 or matching lines when
841 If however the boolean
846 command-line option are both specified,
847 it applies to selected non-matching lines instead.
848 The default is empty (i.e., the terminal's default color pair).
851 Boolean value that reverses (swaps) the meanings of
859 command-line option is specified.
860 The default is false (i.e., the capability is omitted).
863 SGR substring for matching non-empty text in any matching line
865 a selected line when the
867 command-line option is omitted,
868 or a context line when
871 Setting this is equivalent to setting both
875 at once to the same value.
876 The default is a bold red text foreground over the current line background.
879 SGR substring for matching non-empty text in a selected line.
880 (This is only used when the
882 command-line option is omitted.)
889 capability remains active when this kicks in.
890 The default is a bold red text foreground over the current line background.
893 SGR substring for matching non-empty text in a context line.
894 (This is only used when the
896 command-line option is specified.)
903 capability remains active when this kicks in.
904 The default is a bold red text foreground over the current line background.
907 SGR substring for file names prefixing any content line.
908 The default is a magenta text foreground over the terminal's default background.
911 SGR substring for line numbers prefixing any content line.
912 The default is a green text foreground over the terminal's default background.
915 SGR substring for byte offsets prefixing any content line.
916 The default is a green text foreground over the terminal's default background.
919 SGR substring for separators that are inserted
920 between selected line fields
922 between context line fields,
924 and between groups of adjacent lines when nonzero context is specified
926 The default is a cyan text foreground over the terminal's default background.
929 Boolean value that prevents clearing to the end of line
930 using Erase in Line (EL) to Right
932 each time a colorized item ends.
933 This is needed on terminals on which EL is not supported.
934 It is otherwise useful on terminals
938 boolean terminfo capability does not apply,
939 when the chosen highlight colors do not affect the background,
940 or when EL is too slow or causes too much flicker.
941 The default is false (i.e., the capability is omitted).
943 Note that boolean capabilities have no
946 They are omitted (i.e., false) by default and become true when specified.
948 See the Select Graphic Rendition (SGR) section
949 in the documentation of the text terminal that is used
950 for permitted values and their meaning as character attributes.
951 These substring values are integers in decimal representation
952 and can be concatenated with semicolons.
954 takes care of assembling the result
955 into a complete SGR sequence
956 .RB ( \\\\\\33[ ... m ).
957 Common values to concatenate include
967 for default foreground color,
971 for foreground colors,
975 for 16-color mode foreground colors,
979 for 88-color and 256-color modes foreground colors,
981 for default background color,
985 for background colors,
989 for 16-color mode background colors, and
993 for 88-color and 256-color modes background colors.
996 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
997 These variables specify the locale for the
1000 which determines the collating sequence
1001 used to interpret range expressions like
1004 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
1005 These variables specify the locale for the
1008 which determines the type of characters,
1009 e.g., which characters are whitespace.
1011 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
1012 These variables specify the locale for the
1015 which determines the language that
1018 The default C locale uses American English messages.
1023 behaves as \s-1POSIX\s0 requires; otherwise,
1025 behaves more like other \s-1GNU\s0 programs.
1026 \s-1POSIX\s0 requires that options that follow file names must be
1027 treated as file names; by default, such options are permuted to the
1028 front of the operand list and are treated as options.
1029 Also, \s-1POSIX\s0 requires that unrecognized options be diagnosed as
1030 \*(lqillegal\*(rq, but since they are not really against the law the default
1031 is to diagnose them as \*(lqinvalid\*(rq.
1033 also disables \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP,
1036 \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP
1041 numeric process ID.) If the
1043 character of this environment variable's value is
1049 to be an option, even if it appears to be one.
1050 A shell can put this variable in the environment for each command it runs,
1051 specifying which operands are the results of file name wildcard
1052 expansion and therefore should not be treated as options.
1053 This behavior is available only with the \s-1GNU\s0 C library, and only
1059 Normally the exit status is 0 if a line is selected, 1 if no lines
1060 were selected, and 2 if an error occurred. However, if the
1066 is used and a line is selected, the exit status is 0 even if an error
1070 Copyright 1998-2000, 2002, 2005-2015 Free Software Foundation, Inc.
1072 This is free software;
1073 see the source for copying conditions.
1074 There is NO warranty;
1075 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1078 .SS "Reporting Bugs"
1079 Email bug reports to
1080 .MTO bug-grep@gnu.org "the bug-reporting address" .
1082 .URL http://lists.gnu.org/mailman/listinfo/bug-grep "email archive"
1084 .URL http://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep "bug tracker"
1087 Large repetition counts in the
1091 to use lots of memory.
1093 certain other obscure regular expressions require exponential time
1094 and space, and may cause
1096 to run out of memory.
1098 Back-references are very slow, and may require exponential time.
1101 .SS "Regular Manual Pages"
1102 awk(1), cmp(1), diff(1), find(1), gzip(1),
1103 perl(1), sed(1), sort(1), xargs(1), zgrep(1),
1105 pcre(3), pcresyntax(3), pcrepattern(3),
1108 .SS "\s-1POSIX\s0 Programmer's Manual Page"
1110 .SS "Full Documentation"
1112 .URL http://www.gnu.org/software/grep/manual/ "complete manual"
1118 programs are properly installed at your site, the command
1122 should give you access to the complete manual.
1125 This man page is maintained only fitfully;
1126 the full documentation is often more up-to-date.
1127 .\" Work around problems with some troff -man implementations.