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.14" "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 i.e., read directories just as if they were ordinary files.
483 silently skip directories.
488 read all files under each directory, recursively,
489 following symbolic links only if they are on the command line.
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 ", " \-\^\-recursive
531 Read all files under each directory, recursively,
532 following symbolic links only if they are on the command line.
533 This is equivalent to the
536 .BR \-R ", " \-\^\-dereference\-recursive
537 Read all files under each directory, recursively.
538 Follow all symbolic links, unlike
542 .BR \-\^\-line\-buffered
543 Use line buffering on output.
544 This can cause a performance penalty.
549 system call to read input, instead of
555 yields better performance.
558 can cause undefined behavior (including core dumps)
559 if an input file shrinks while
561 is operating, or if an I/O error occurs.
563 .BR \-U ", " \-\^\-binary
564 Treat the file(s) as binary.
565 By default, under \s-1MS-DOS\s0 and \s-1MS\s0-Windows,
567 guesses the file type by looking at the contents of the first 32KB
571 decides the file is a text file, it strips the CR characters from the
572 original file contents (to make regular expressions with
579 overrules this guesswork, causing all files to be read and passed to the
580 matching mechanism verbatim; if the file is a text file with CR/LF
581 pairs at the end of each line, this will cause some regular
583 This option has no effect on platforms
584 other than \s-1MS-DOS\s0 and \s-1MS\s0-Windows.
586 .BR \-z ", " \-\^\-null\-data
587 Treat the input as a set of lines,
588 each terminated by a zero byte (the \s-1ASCII\s0
590 character) instead of a newline.
595 option, this option can be used with commands like
597 to process arbitrary file names.
599 .SH "REGULAR EXPRESSIONS"
600 A regular expression is a pattern that describes a set of strings.
601 Regular expressions are constructed analogously to arithmetic
602 expressions, by using various operators to combine smaller expressions.
605 understands three different versions of regular expression syntax:
606 \*(lqbasic,\*(rq \*(lqextended\*(rq and \*(lqperl.\*(rq In
607 .RB "\s-1GNU\s0\ " grep ,
608 there is no difference in available functionality between basic and
610 In other implementations, basic regular expressions are less powerful.
611 The following description applies to extended regular expressions;
612 differences for basic regular expressions are summarized afterwards.
613 Perl regular expressions give additional functionality, and are
614 documented in pcresyntax(3) and pcrepattern(3), but may not be
615 available on every system.
617 The fundamental building blocks are the regular expressions
618 that match a single character.
619 Most characters, including all letters and digits,
620 are regular expressions that match themselves.
621 Any meta-character with special meaning
622 may be quoted by preceding it with a backslash.
626 matches any single character.
627 .SS "Character Classes and Bracket Expressions"
629 .I "bracket expression"
630 is a list of characters enclosed by
634 It matches any single
635 character in that list; if the first character of the list
638 then it matches any character
641 For example, the regular expression
643 matches any single digit.
645 Within a bracket expression, a
646 .I "range expression"
647 consists of two characters separated by a hyphen.
648 It matches any single character that sorts between the two characters,
649 inclusive, using the locale's collating sequence and character set.
650 For example, in the default C locale,
654 Many locales sort characters in dictionary order, and in these locales
656 is typically not equivalent to
658 it might be equivalent to
661 To obtain the traditional interpretation of bracket expressions,
662 you can use the C locale by setting the
664 environment variable to the value
667 Finally, certain named classes of characters are predefined within
668 bracket expressions, as follows.
669 Their names are self explanatory, and they are
684 means the character class of numbers and
685 letters in the current locale. In the C locale and \s-1ASCII\s0
686 character set encoding, this is the same as
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 least
756 times, but not more than
761 Two regular expressions may be concatenated; the resulting
762 regular expression matches any string formed by concatenating
763 two substrings that respectively match the concatenated
766 Two regular expressions may be joined by the infix operator
768 the resulting regular expression matches any string matching
769 either alternate expression.
771 Repetition takes precedence over concatenation, which in turn
772 takes precedence over alternation.
773 A whole expression may be enclosed in parentheses
774 to override these precedence rules and form a subexpression.
775 .SS "Back References and Subexpressions"
780 is a single digit, matches the substring
781 previously matched by the
783 parenthesized subexpression of the regular expression.
784 .SS "Basic vs Extended Regular Expressions"
785 In basic regular expressions the meta-characters
793 lose their special meaning; instead use the backslashed
807 meta-character, and some
809 implementations support
811 instead, so portable scripts should avoid
815 patterns and should use
822 attempts to support traditional usage by assuming that
824 is not special if it would be the start of an invalid interval
826 For example, the command
828 searches for the two-character string
830 instead of reporting a syntax error in the regular expression.
831 \s-1POSIX.2\s0 allows this behavior as an extension, but portable scripts
834 .SH "ENVIRONMENT VARIABLES"
837 is affected by the following environment variables.
839 The locale for category
841 is specified by examining the three environment variables
846 The first of these variables that is set specifies the locale.
853 then the Brazilian Portuguese locale is used for the
856 The C locale is used if none of these environment variables are set,
857 if the locale catalog is not installed, or if
859 was not compiled with national language support (\s-1NLS\s0).
862 This variable specifies default options
863 to be placed in front of any explicit options.
867 .BR "'\-\^\-binary-files=without-match \-\^\-directories=skip'" ,
869 behaves as if the two options
870 .B \-\^\-binary\-files=without-match
872 .B \-\^\-directories=skip
873 had been specified before any explicit options.
874 Option specifications are separated by whitespace.
875 A backslash escapes the next character,
876 so it can be used to specify an option containing whitespace or a backslash.
879 This variable specifies the color used to highlight matched (non-empty) text.
880 It is deprecated in favor of
890 have priority over it.
891 It can only specify the color used to highlight
892 the matching non-empty text in any matching line
893 (a selected line when the
895 command-line option is omitted,
896 or a context line when
901 which means a bold red foreground text on the terminal's default background.
904 Specifies the colors and other attributes
905 used to highlight various parts of the output.
906 Its value is a colon-separated list of capabilities
908 .B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
913 boolean capabilities omitted (i.e., false).
914 Supported capabilities are as follows.
918 SGR substring for whole selected lines
920 matching lines when the
922 command-line option is omitted,
923 or non-matching lines when
926 If however the boolean
931 command-line option are both specified,
932 it applies to context matching lines instead.
933 The default is empty (i.e., the terminal's default color pair).
936 SGR substring for whole context lines
938 non-matching lines when the
940 command-line option is omitted,
941 or matching lines when
944 If however the boolean
949 command-line option are both specified,
950 it applies to selected non-matching lines instead.
951 The default is empty (i.e., the terminal's default color pair).
954 Boolean value that reverses (swaps) the meanings of
962 command-line option is specified.
963 The default is false (i.e., the capability is omitted).
966 SGR substring for matching non-empty text in any matching line
968 a selected line when the
970 command-line option is omitted,
971 or a context line when
974 Setting this is equivalent to setting both
978 at once to the same value.
979 The default is a bold red text foreground over the current line background.
982 SGR substring for matching non-empty text in a selected line.
983 (This is only used when the
985 command-line option is omitted.)
992 capability remains active when this kicks in.
993 The default is a bold red text foreground over the current line background.
996 SGR substring for matching non-empty text in a context line.
997 (This is only used when the
999 command-line option is specified.)
1006 capability remains active when this kicks in.
1007 The default is a bold red text foreground over the current line background.
1010 SGR substring for file names prefixing any content line.
1011 The default is a magenta text foreground over the terminal's default background.
1014 SGR substring for line numbers prefixing any content line.
1015 The default is a green text foreground over the terminal's default background.
1018 SGR substring for byte offsets prefixing any content line.
1019 The default is a green text foreground over the terminal's default background.
1022 SGR substring for separators that are inserted
1023 between selected line fields
1025 between context line fields,
1027 and between groups of adjacent lines when nonzero context is specified
1029 The default is a cyan text foreground over the terminal's default background.
1032 Boolean value that prevents clearing to the end of line
1033 using Erase in Line (EL) to Right
1035 each time a colorized item ends.
1036 This is needed on terminals on which EL is not supported.
1037 It is otherwise useful on terminals
1041 boolean terminfo capability does not apply,
1042 when the chosen highlight colors do not affect the background,
1043 or when EL is too slow or causes too much flicker.
1044 The default is false (i.e., the capability is omitted).
1046 Note that boolean capabilities have no
1049 They are omitted (i.e., false) by default and become true when specified.
1051 See the Select Graphic Rendition (SGR) section
1052 in the documentation of the text terminal that is used
1053 for permitted values and their meaning as character attributes.
1054 These substring values are integers in decimal representation
1055 and can be concatenated with semicolons.
1057 takes care of assembling the result
1058 into a complete SGR sequence
1059 .RB ( \\\\\\33[ ... m ).
1060 Common values to concatenate include
1070 for default foreground color,
1074 for foreground colors,
1078 for 16-color mode foreground colors,
1082 for 88-color and 256-color modes foreground colors,
1084 for default background color,
1088 for background colors,
1092 for 16-color mode background colors, and
1096 for 88-color and 256-color modes background colors.
1099 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
1100 These variables specify the locale for the
1103 which determines the collating sequence
1104 used to interpret range expressions like
1107 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
1108 These variables specify the locale for the
1111 which determines the type of characters,
1112 e.g., which characters are whitespace.
1114 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
1115 These variables specify the locale for the
1118 which determines the language that
1121 The default C locale uses American English messages.
1126 behaves as \s-1POSIX.2\s0 requires; otherwise,
1128 behaves more like other \s-1GNU\s0 programs.
1129 \s-1POSIX.2\s0 requires that options that follow file names must be
1130 treated as file names; by default, such options are permuted to the
1131 front of the operand list and are treated as options.
1132 Also, \s-1POSIX.2\s0 requires that unrecognized options be diagnosed as
1133 \*(lqillegal\*(rq, but since they are not really against the law the default
1134 is to diagnose them as \*(lqinvalid\*(rq.
1136 also disables \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP,
1139 \fB_\fP\fIN\fP\fB_GNU_nonoption_argv_flags_\fP
1144 numeric process ID.) If the
1146 character of this environment variable's value is
1152 to be an option, even if it appears to be one.
1153 A shell can put this variable in the environment for each command it runs,
1154 specifying which operands are the results of file name wildcard
1155 expansion and therefore should not be treated as options.
1156 This behavior is available only with the \s-1GNU\s0 C library, and only
1162 Normally, the exit status is 0 if selected lines are found and 1 otherwise.
1163 But the exit status is 2 if an error occurred, unless the
1169 option is used and a selected line is found.
1170 Note, however, that \s-1POSIX\s0 only mandates, for programs such as
1175 that the exit status in case of error be greater than 1;
1176 it is therefore advisable, for the sake of portability,
1177 to use logic that tests for this general condition
1178 instead of strict equality with\ 2.
1181 Copyright 1998-2000, 2002, 2005-2012 Free Software Foundation, Inc.
1183 This is free software;
1184 see the source for copying conditions.
1185 There is NO warranty;
1186 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1189 .SS "Reporting Bugs"
1190 Email bug reports to
1191 .RB < bug\-grep@gnu.org >,
1192 a mailing list whose web page is
1193 .RB < http://lists.gnu.org/mailman/listinfo/bug\-grep >.
1195 Savannah bug tracker is located at
1196 .RB < http://savannah.gnu.org/bugs/?group=grep >.
1198 Large repetition counts in the
1202 to use lots of memory.
1204 certain other obscure regular expressions require exponential time
1205 and space, and may cause
1207 to run out of memory.
1209 Back-references are very slow, and may require exponential time.
1212 .SS "Regular Manual Pages"
1213 awk(1), cmp(1), diff(1), find(1), gzip(1),
1214 perl(1), sed(1), sort(1), xargs(1), zgrep(1),
1216 pcre(3), pcresyntax(3), pcrepattern(3),
1219 .SS "\s-1POSIX\s0 Programmer's Manual Page"
1221 .SS "\*(Txinfo Documentation"
1222 The full documentation for
1224 is maintained as a \*(Txinfo manual,
1225 which you can read at http://www.gnu.org/software/grep/manual/.
1230 programs are properly installed at your site, the command
1234 should give you access to the complete manual.
1237 This man page is maintained only fitfully;
1238 the full documentation is often more up-to-date.
1240 \s-1GNU\s0's not Unix, but Unix is a beast;
1241 its plural form is Unixen.
1242 .\" Work around problems with some troff -man implementations.
projects / dragonfly.git / blob