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.7" "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 \-O ", " \-\^\-only-files
538 Ignore all special files, except for symlinks. Yet, when recursing
539 into directories, ignore symlinked directories as well.
541 .BR \-\^\-line\-buffered
542 Use line buffering on output.
543 This can cause a performance penalty.
548 system call to read input, instead of
554 yields better performance.
557 can cause undefined behavior (including core dumps)
558 if an input file shrinks while
560 is operating, or if an I/O error occurs.
562 .BR \-U ", " \-\^\-binary
563 Treat the file(s) as binary.
564 By default, under \s-1MS-DOS\s0 and \s-1MS\s0-Windows,
566 guesses the file type by looking at the contents of the first 32KB
570 decides the file is a text file, it strips the CR characters from the
571 original file contents (to make regular expressions with
578 overrules this guesswork, causing all files to be read and passed to the
579 matching mechanism verbatim; if the file is a text file with CR/LF
580 pairs at the end of each line, this will cause some regular
582 This option has no effect on platforms
583 other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
585 .BR \-z ", " \-\^\-null\-data
586 Treat the input as a set of lines,
587 each terminated by a zero byte (the \s-1ASCII\s0
589 character) instead of a newline.
594 option, this option can be used with commands like
596 to process arbitrary file names.
598 .SH "REGULAR EXPRESSIONS"
599 A regular expression is a pattern that describes a set of strings.
600 Regular expressions are constructed analogously to arithmetic
601 expressions, by using various operators to combine smaller expressions.
604 understands three different versions of regular expression syntax:
605 \*(lqbasic,\*(rq \*(lqextended\*(rq and \*(lqperl.\*(rq In
606 .RB "\s-1GNU\s0\ " grep ,
607 there is no difference in available functionality between basic and
609 In other implementations, basic regular expressions are less powerful.
610 The following description applies to extended regular expressions;
611 differences for basic regular expressions are summarized afterwards.
612 Perl regular expressions give additional functionality, and are
613 documented in pcresyntax(3) and pcrepattern(3), but may not be
614 available on every system.
616 The fundamental building blocks are the regular expressions
617 that match a single character.
618 Most characters, including all letters and digits,
619 are regular expressions that match themselves.
620 Any meta-character with special meaning
621 may be quoted by preceding it with a backslash.
625 matches any single character.
626 .SS "Character Classes and Bracket Expressions"
628 .I "bracket expression"
629 is a list of characters enclosed by
633 It matches any single
634 character in that list; if the first character of the list
637 then it matches any character
640 For example, the regular expression
642 matches any single digit.
644 Within a bracket expression, a
645 .I "range expression"
646 consists of two characters separated by a hyphen.
647 It matches any single character that sorts between the two characters,
648 inclusive, using the locale's collating sequence and character set.
649 For example, in the default C locale,
653 Many locales sort characters in dictionary order, and in these locales
655 is typically not equivalent to
657 it might be equivalent to
660 To obtain the traditional interpretation of bracket expressions,
661 you can use the C locale by setting the
663 environment variable to the value
666 Finally, certain named classes of characters are predefined within
667 bracket expressions, as follows.
668 Their names are self explanatory, and they are
685 except the latter form depends upon the C locale and the
686 \s-1ASCII\s0 character encoding, whereas the former is independent
687 of locale and character set.
688 (Note that the brackets in these class names are part of the symbolic
689 names, and must be included in addition to the brackets delimiting
690 the bracket expression.)
691 Most meta-characters lose their special meaning inside bracket expressions.
694 place it first in the list.
695 Similarly, to include a literal
697 place it anywhere but first.
698 Finally, to include a literal
706 are meta-characters that respectively match the empty string at the
707 beginning and end of a line.
708 .SS "The Backslash Character and Special Expressions"
713 respectively match the empty string at the beginning and end of a word.
716 matches the empty string at the edge of a word,
719 matches the empty string provided it's
721 at the edge of a word.
731 A regular expression may be followed by one of several repetition operators:
735 The preceding item is optional and matched at most once.
738 The preceding item will be matched zero or more times.
741 The preceding item will be matched one or more times.
744 The preceding item is matched exactly
749 The preceding item is matched
754 The preceding item is matched at most
759 The preceding item is matched at least
761 times, but not more than
766 Two regular expressions may be concatenated; the resulting
767 regular expression matches any string formed by concatenating
768 two substrings that respectively match the concatenated
771 Two regular expressions may be joined by the infix operator
773 the resulting regular expression matches any string matching
774 either alternate expression.
776 Repetition takes precedence over concatenation, which in turn
777 takes precedence over alternation.
778 A whole expression may be enclosed in parentheses
779 to override these precedence rules and form a subexpression.
780 .SS "Back References and Subexpressions"
785 is a single digit, matches the substring
786 previously matched by the
788 parenthesized subexpression of the regular expression.
789 .SS "Basic vs Extended Regular Expressions"
790 In basic regular expressions the meta-characters
798 lose their special meaning; instead use the backslashed
812 meta-character, and some
814 implementations support
816 instead, so portable scripts should avoid
820 patterns and should use
827 attempts to support traditional usage by assuming that
829 is not special if it would be the start of an invalid interval
831 For example, the command
833 searches for the two-character string
835 instead of reporting a syntax error in the regular expression.
836 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
839 .SH "ENVIRONMENT VARIABLES"
842 is affected by the following environment variables.
844 The locale for category
846 is specified by examining the three environment variables
851 The first of these variables that is set specifies the locale.
858 then the Brazilian Portuguese locale is used for the
861 The C locale is used if none of these environment variables are set,
862 if the locale catalog is not installed, or if
864 was not compiled with national language support (\s-1NLS\s0).
867 This variable specifies default options
868 to be placed in front of any explicit options.
872 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
874 behaves as if the two options
875 .B \-\^\-binary\-files=without-match
877 .B \-\^\-directories=skip
878 had been specified before any explicit options.
879 Option specifications are separated by whitespace.
880 A backslash escapes the next character,
881 so it can be used to specify an option containing whitespace or a backslash.
884 This variable specifies the color used to highlight matched (non-empty) text.
885 It is deprecated in favor of
895 have priority over it.
896 It can only specify the color used to highlight
897 the matching non-empty text in any matching line
898 (a selected line when the
900 command-line option is omitted,
901 or a context line when
906 which means a bold red foreground text on the terminal's default background.
909 Specifies the colors and other attributes
910 used to highlight various parts of the output.
911 Its value is a colon-separated list of capabilities
913 .B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
918 boolean capabilities omitted (i.e., false).
919 Supported capabilities are as follows.
923 SGR substring for whole selected lines
925 matching lines when the
927 command-line option is omitted,
928 or non-matching lines when
931 If however the boolean
936 command-line option are both specified,
937 it applies to context matching lines instead.
938 The default is empty (i.e., the terminal's default color pair).
941 SGR substring for whole context lines
943 non-matching lines when the
945 command-line option is omitted,
946 or matching lines when
949 If however the boolean
954 command-line option are both specified,
955 it applies to selected non-matching lines instead.
956 The default is empty (i.e., the terminal's default color pair).
959 Boolean value that reverses (swaps) the meanings of
967 command-line option is specified.
968 The default is false (i.e., the capability is omitted).
971 SGR substring for matching non-empty text in any matching line
973 a selected line when the
975 command-line option is omitted,
976 or a context line when
979 Setting this is equivalent to setting both
983 at once to the same value.
984 The default is a bold red text foreground over the current line background.
987 SGR substring for matching non-empty text in a selected line.
988 (This is only used when the
990 command-line option is omitted.)
997 capability remains active when this kicks in.
998 The default is a bold red text foreground over the current line background.
1001 SGR substring for matching non-empty text in a context line.
1002 (This is only used when the
1004 command-line option is specified.)
1011 capability remains active when this kicks in.
1012 The default is a bold red text foreground over the current line background.
1015 SGR substring for file names prefixing any content line.
1016 The default is a magenta text foreground over the terminal's default background.
1019 SGR substring for line numbers prefixing any content line.
1020 The default is a green text foreground over the terminal's default background.
1023 SGR substring for byte offsets prefixing any content line.
1024 The default is a green text foreground over the terminal's default background.
1027 SGR substring for separators that are inserted
1028 between selected line fields
1030 between context line fields,
1032 and between groups of adjacent lines when nonzero context is specified
1034 The default is a cyan text foreground over the terminal's default background.
1037 Boolean value that prevents clearing to the end of line
1038 using Erase in Line (EL) to Right
1040 each time a colorized item ends.
1041 This is needed on terminals on which EL is not supported.
1042 It is otherwise useful on terminals
1046 boolean terminfo capability does not apply,
1047 when the chosen highlight colors do not affect the background,
1048 or when EL is too slow or causes too much flicker.
1049 The default is false (i.e., the capability is omitted).
1051 Note that boolean capabilities have no
1054 They are omitted (i.e., false) by default and become true when specified.
1056 See the Select Graphic Rendition (SGR) section
1057 in the documentation of the text terminal that is used
1058 for permitted values and their meaning as character attributes.
1059 These substring values are integers in decimal representation
1060 and can be concatenated with semicolons.
1062 takes care of assembling the result
1063 into a complete SGR sequence
1064 .RB ( \\\\\\33[ ... m ).
1065 Common values to concatenate include
1075 for default foreground color,
1079 for foreground colors,
1083 for 16-color mode foreground colors,
1087 for 88-color and 256-color modes foreground colors,
1089 for default background color,
1093 for background colors,
1097 for 16-color mode background colors, and
1101 for 88-color and 256-color modes background colors.
1104 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
1105 These variables specify the locale for the
1108 which determines the collating sequence
1109 used to interpret range expressions like
1112 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
1113 These variables specify the locale for the
1116 which determines the type of characters,
1117 e.g., which characters are whitespace.
1119 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
1120 These variables specify the locale for the
1123 which determines the language that
1126 The default C locale uses American English messages.
1131 behaves as \s-1POSIX.2\s0 requires; otherwise,
1133 behaves more like other \s-1GNU\s0 programs.
1134 \s-1POSIX.2\s0 requires that options that follow file names must be
1135 treated as file names; by default, such options are permuted to the
1136 front of the operand list and are treated as options.
1137 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
1138 \*(lqillegal\*(rq, but since they are not really against the law the default
1139 is to diagnose them as \*(lqinvalid\*(rq.
1141 also disables \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP,
1144 \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP
1149 numeric process ID.) If the
1151 character of this environment variable's value is
1157 to be an option, even if it appears to be one.
1158 A shell can put this variable in the environment for each command it runs,
1159 specifying which operands are the results of file name wildcard
1160 expansion and therefore should not be treated as options.
1161 This behavior is available only with the \s-1GNU\s0 C library, and only
1167 Normally, the exit status is 0 if selected lines are found and 1 otherwise.
1168 But the exit status is 2 if an error occurred, unless the
1174 option is used and a selected line is found.
1175 Note, however, that \s-1POSIX\s0 only mandates, for programs such as
1180 that the exit status in case of error be greater than 1;
1181 it is therefore advisable, for the sake of portability,
1182 to use logic that tests for this general condition
1183 instead of strict equality with\ 2.
1186 Copyright 1998-2000, 2002, 2005-2010 Free Software Foundation, Inc.
1188 This is free software;
1189 see the source for copying conditions.
1190 There is NO warranty;
1191 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1194 .SS "Reporting Bugs"
1195 Email bug reports to
1196 .RB < bug\-grep@gnu.org >,
1197 a mailing list whose web page is
1198 .RB < http://lists.gnu.org/mailman/listinfo/bug\-grep >.
1200 Savannah bug tracker is located at
1201 .RB < http://savannah.gnu.org/bugs/?group=grep >.
1203 Large repetition counts in the
1207 to use lots of memory.
1209 certain other obscure regular expressions require exponential time
1210 and space, and may cause
1212 to run out of memory.
1214 Back-references are very slow, and may require exponential time.
1217 .SS "Regular Manual Pages"
1218 awk(1), cmp(1), diff(1), find(1), gzip(1),
1219 perl(1), sed(1), sort(1), xargs(1), zgrep(1),
1221 pcre(3), pcresyntax(3), pcrepattern(3),
1224 .SS "\s-1POSIX\s0 Programmer's Manual Page"
1226 .SS "\*(Txinfo Documentation"
1227 The full documentation for
1229 is maintained as a \*(Txinfo manual.
1234 programs are properly installed at your site, the command
1238 should give you access to the complete manual.
1241 \s-1GNU\s0's not Unix, but Unix is a beast;
1242 its plural form is Unixen.
1243 .\" Work around problems with some troff -man implementations.
nant's projects / dragonfly.git / blob