grep.texi revision 56230
153564Sobrien\input texinfo @c -*-texinfo-*- 253564Sobrien@c %**start of header 353564Sobrien@setfilename grep.info 453564Sobrien@settitle grep, print lines matching a pattern 553564Sobrien@c %**end of header 653564Sobrien 753564Sobrien@c This file has the new style title page commands. 853564Sobrien@c Run `makeinfo' rather than `texinfo-format-buffer'. 953564Sobrien 1053564Sobrien@c smallbook 1153564Sobrien 1253564Sobrien@c tex 1353564Sobrien@c \overfullrule=0pt 1453564Sobrien@c end tex 1553564Sobrien 1653564Sobrien@include version.texi 1753564Sobrien 1853564Sobrien@c Combine indices. 1953564Sobrien@syncodeindex ky cp 2053564Sobrien@syncodeindex pg cp 2153564Sobrien@syncodeindex tp cp 2253564Sobrien 2353564Sobrien@defcodeindex op 2453564Sobrien@syncodeindex op fn 2555360Sobrien@syncodeindex vr fn 2653564Sobrien 2753564Sobrien@ifinfo 2853564Sobrien@direntry 2953564Sobrien* grep: (grep). print lines matching a pattern. 3053564Sobrien@end direntry 3155360SobrienThis file documents @command{grep}, a pattern matching engine. 3253564Sobrien 3353564Sobrien 3453564SobrienPublished by the Free Software Foundation, 3553564Sobrien59 Temple Place - Suite 330 3653564SobrienBoston, MA 02111-1307, USA 3753564Sobrien 3855360SobrienCopyright 1999 Free Software Foundation, Inc. 3953564Sobrien 4053564SobrienPermission is granted to make and distribute verbatim copies of 4153564Sobrienthis manual provided the copyright notice and this permission notice 4253564Sobrienare preserved on all copies. 4353564Sobrien 4453564Sobrien@ignore 4553564SobrienPermission is granted to process this file through TeX and print the 4653564Sobrienresults, provided the printed document carries copying permission 4753564Sobriennotice identical to this one except for the removal of this paragraph 4853564Sobrien(this paragraph not being relevant to the printed manual). 4953564Sobrien 5053564Sobrien@end ignore 5153564SobrienPermission is granted to copy and distribute modified versions of this 5253564Sobrienmanual under the conditions for verbatim copying, provided that the entire 5353564Sobrienresulting derived work is distributed under the terms of a permission 5453564Sobriennotice identical to this one. 5553564Sobrien 5653564SobrienPermission is granted to copy and distribute translations of this manual 5753564Sobrieninto another language, under the above conditions for modified versions, 5853564Sobrienexcept that this permission notice may be stated in a translation approved 5953564Sobrienby the Foundation. 6053564Sobrien@end ifinfo 6153564Sobrien 6253564Sobrien@setchapternewpage off 6353564Sobrien 6453564Sobrien@titlepage 6553564Sobrien@title grep, searching for a pattern 6653564Sobrien@subtitle version @value{VERSION}, @value{UPDATED} 6753564Sobrien@author Alain Magloire et al. 6853564Sobrien 6953564Sobrien@page 7053564Sobrien@vskip 0pt plus 1filll 7155360SobrienCopyright @copyright{} 1999 Free Software Foundation, Inc. 7253564Sobrien 7353564Sobrien@sp 2 7453564SobrienPublished by the Free Software Foundation, @* 7553564Sobrien59 Temple Place - Suite 330, @* 7653564SobrienBoston, MA 02111-1307, USA 7753564Sobrien 7853564SobrienPermission is granted to make and distribute verbatim copies of 7953564Sobrienthis manual provided the copyright notice and this permission notice 8053564Sobrienare preserved on all copies. 8153564Sobrien 8253564SobrienPermission is granted to copy and distribute modified versions of this 8353564Sobrienmanual under the conditions for verbatim copying, provided that the entire 8453564Sobrienresulting derived work is distributed under the terms of a permission 8553564Sobriennotice identical to this one. 8653564Sobrien 8753564SobrienPermission is granted to copy and distribute translations of this manual 8853564Sobrieninto another language, under the above conditions for modified versions, 8953564Sobrienexcept that this permission notice may be stated in a translation approved 9053564Sobrienby the Foundation. 9153564Sobrien 9253564Sobrien@end titlepage 9353564Sobrien@page 9453564Sobrien 9553564Sobrien 9655360Sobrien@ifnottex 9755360Sobrien@node Top 9855360Sobrien@top Grep 9953564Sobrien 10055360Sobrien@command{grep} searches for lines matching a pattern. 10153564Sobrien 10255360SobrienThis document was produced for version @value{VERSION} of @sc{gnu} 10355360Sobrien@command{grep}. 10455360Sobrien@end ifnottex 10555360Sobrien 10653564Sobrien@menu 10753564Sobrien* Introduction:: Introduction. 10855360Sobrien* Invoking:: Invoking @command{grep}; description of options. 10955360Sobrien* Diagnostics:: Exit status returned by @command{grep}. 11055360Sobrien* Grep Programs:: @command{grep} programs. 11153564Sobrien* Regular Expressions:: Regular Expressions. 11255360Sobrien* Usage:: Examples. 11353564Sobrien* Reporting Bugs:: Reporting Bugs. 11453564Sobrien* Concept Index:: A menu with all the topics in this manual. 11555360Sobrien* Index:: A menu with all @command{grep} commands 11653564Sobrien and command-line options. 11753564Sobrien@end menu 11853564Sobrien 11953564Sobrien 12055360Sobrien@node Introduction 12153564Sobrien@chapter Introduction 12253564Sobrien 12353564Sobrien@cindex Searching for a pattern. 12455360Sobrien 12555360Sobrien@command{grep} searches the input files 12655360Sobrienfor lines containing a match to a given 12753564Sobrienpattern list. When it finds a match in a line, it copies the line to standard 12853564Sobrienoutput (by default), or does whatever other sort of output you have requested 12955360Sobrienwith options. @command{grep} expects to do the matching on text. 13053564SobrienSince newline is also a separator for the list of patterns, there 13153564Sobrienis no way to match newline characters in a text. 13253564Sobrien 13355360Sobrien@node Invoking 13455360Sobrien@chapter Invoking @command{grep} 13553564Sobrien 13655360Sobrien@command{grep} comes with a rich set of options from @sc{posix.2} and @sc{gnu} 13755360Sobrienextensions. 13853564Sobrien 13953564Sobrien@table @samp 14053564Sobrien 14153564Sobrien@item -c 14253564Sobrien@itemx --count 14353564Sobrien@opindex -c 14453564Sobrien@opindex -count 14553564Sobrien@cindex counting lines 14653564SobrienSuppress normal output; instead print a count of matching 14755360Sobrienlines for each input file. With the @samp{-v}, @samp{--invert-match} option, 14853564Sobriencount non-matching lines. 14953564Sobrien 15053564Sobrien@item -e @var{pattern} 15153564Sobrien@itemx --regexp=@var{pattern} 15253564Sobrien@opindex -e 15353564Sobrien@opindex --regexp=@var{pattern} 15453564Sobrien@cindex pattern list 15555360SobrienUse @var{pattern} as the pattern; useful to protect patterns 15653564Sobrienbeginning with a @samp{-}. 15753564Sobrien 15855360Sobrien@item -f @var{file} 15953564Sobrien@itemx --file=@var{file} 16055360Sobrien@opindex -f 16155360Sobrien@opindex --file 16253564Sobrien@cindex pattern from file 16355360SobrienObtain patterns from @var{file}, one per line. The empty 16453564Sobrienfile contains zero patterns, and therefore matches nothing. 16553564Sobrien 16653564Sobrien@item -i 16753564Sobrien@itemx --ignore-case 16853564Sobrien@opindex -i 16953564Sobrien@opindex --ignore-case 17053564Sobrien@cindex case insensitive search 17155360SobrienIgnore case distinctions in both the pattern and the input files. 17253564Sobrien 17353564Sobrien@item -l 17453564Sobrien@itemx --files-with-matches 17553564Sobrien@opindex -l 17653564Sobrien@opindex --files-with-matches 17753564Sobrien@cindex names of matching files 17855360SobrienSuppress normal output; instead print the name of each input 17955360Sobrienfile from which output would normally have been printed. 18053564SobrienThe scanning of every file will stop on the first match. 18153564Sobrien 18253564Sobrien@item -n 18353564Sobrien@itemx --line-number 18453564Sobrien@opindex -n 18553564Sobrien@opindex --line-number 18653564Sobrien@cindex line numbering 18755360SobrienPrefix each line of output with the line number within its input file. 18853564Sobrien 18953564Sobrien@item -q 19053564Sobrien@itemx --quiet 19153564Sobrien@itemx --silent 19253564Sobrien@opindex -q 19353564Sobrien@opindex --quiet 19453564Sobrien@opindex --silent 19553564Sobrien@cindex quiet, silent 19655360SobrienQuiet; suppress normal output. The scanning of every file will stop on 19753564Sobrienthe first match. Also see the @samp{-s} or @samp{--no-messages} option. 19853564Sobrien 19953564Sobrien@item -s 20053564Sobrien@itemx --no-messages 20153564Sobrien@opindex -s 20253564Sobrien@opindex --no-messages 20353564Sobrien@cindex suppress error messages 20453564SobrienSuppress error messages about nonexistent or unreadable files. 20555360SobrienPortability note: unlike @sc{gnu} @command{grep}, traditional 20655360Sobrien@command{grep} did not conform to @sc{posix.2}, because traditional 20755360Sobrien@command{grep} lacked a @samp{-q} option and its @samp{-s} option behaved 20855360Sobrienlike @sc{gnu} @command{grep}'s @samp{-q} option. Shell scripts intended 20955360Sobriento be portable to traditional @command{grep} should avoid both 21053564Sobrien@samp{-q} and @samp{-s} and should redirect 21153564Sobrienoutput to @file{/dev/null} instead. 21253564Sobrien 21353564Sobrien@item -v 21455360Sobrien@itemx --invert-match 21553564Sobrien@opindex -v 21655360Sobrien@opindex --invert-match 21755360Sobrien@cindex invert matching 21853564Sobrien@cindex print non-matching lines 21955360SobrienInvert the sense of matching, to select non-matching lines. 22053564Sobrien 22153564Sobrien@item -x 22253564Sobrien@itemx --line-regexp 22353564Sobrien@opindex -x 22453564Sobrien@opindex --line-regexp 22553564Sobrien@cindex match the whole line 22655360SobrienSelect only those matches that exactly match the whole line. 22753564Sobrien 22853564Sobrien@end table 22953564Sobrien 23055360Sobrien@section @sc{gnu} Extensions 23153564Sobrien 23253564Sobrien@table @samp 23353564Sobrien 23453564Sobrien@item -A @var{num} 23553564Sobrien@itemx --after-context=@var{num} 23653564Sobrien@opindex -A 23753564Sobrien@opindex --after-context 23853564Sobrien@cindex after context 23953564Sobrien@cindex context lines, after match 24053564SobrienPrint @var{num} lines of trailing context after matching lines. 24153564Sobrien 24253564Sobrien@item -B @var{num} 24353564Sobrien@itemx --before-context=@var{num} 24453564Sobrien@opindex -B 24553564Sobrien@opindex --before-context 24653564Sobrien@cindex before context 24753564Sobrien@cindex context lines, before match 24853564SobrienPrint @var{num} lines of leading context before matching lines. 24953564Sobrien 25055360Sobrien@item -C @var{num} 25155360Sobrien@itemx --context=[@var{num}] 25253564Sobrien@opindex -C 25353564Sobrien@opindex --context 25453564Sobrien@cindex context 25553564SobrienPrint @var{num} lines (default 2) of output context. 25653564Sobrien 25753564Sobrien 25855360Sobrien@item -@var{num} 25953564Sobrien@opindex -NUM 26055360SobrienSame as @samp{--context=@var{num}} lines of leading and trailing 26153564Sobriencontext. However, grep will never print any given line more than once. 26253564Sobrien 26353564Sobrien 26453564Sobrien@item -V 26553564Sobrien@itemx --version 26653564Sobrien@opindex -V 26753564Sobrien@opindex --version 26853564Sobrien@cindex Version, printing 26955360SobrienPrint the version number of @command{grep} to the standard output stream. 27055360SobrienThis version number should be included in all bug reports. 27153564Sobrien 27253564Sobrien@item --help 27353564Sobrien@opindex --help 27453564Sobrien@cindex Usage summary, printing 27553564SobrienPrint a usage message briefly summarizing these command-line options 27653564Sobrienand the bug-reporting address, then exit. 27753564Sobrien 27856230Sru@itemx --binary-files=@var{type} 27956230Sru@opindex --binary-files 28056230Sru@cindex binary files 28156230SruIf the first few bytes of a file indicate that the file contains binary 28256230Srudata, assume that the file is of type @var{type}. By default, 28356230Sru@var{type} is @samp{binary}, and @command{grep} normally outputs either 28456230Srua one-line message saying that a binary file matches, or no message if 28556230Sruthere is no match. If @var{type} is @samp{without-match}, 28656230Sru@command{grep} assumes that a binary file does not match. If @var{type} 28756230Sruis @samp{text}, @command{grep} processes a binary file as if it were 28856230Srutext; this is equivalent to the @samp{-a} or @samp{--text} option. 28956230Sru@emph{Warning:} @samp{--binary-files=text} might output binary garbage, 29056230Sruwhich can have nasty side effects if the output is a terminal and if the 29156230Sruterminal driver interprets some of it as commands. 29256230Sru 29353564Sobrien@item -b 29453564Sobrien@itemx --byte-offset 29553564Sobrien@opindex -b 29653564Sobrien@opindex --byte-offset 29753564Sobrien@cindex byte offset 29853564SobrienPrint the byte offset within the input file before each line of output. 29955360SobrienWhen @command{grep} runs on @sc{ms-dos} or MS-Windows, the printed 30055360Sobrienbyte offsets 30153564Sobriendepend on whether the @samp{-u} (@samp{--unix-byte-offsets}) option is 30253564Sobrienused; see below. 30353564Sobrien 30453564Sobrien@item -d @var{action} 30553564Sobrien@itemx --directories=@var{action} 30655360Sobrien@opindex -d 30753564Sobrien@opindex --directories 30853564Sobrien@cindex directory search 30955360SobrienIf an input file is a directory, use @var{action} to process it. 31055360SobrienBy default, @var{action} is @samp{read}, which means that directories are 31155360Sobrienread just as if they were ordinary files (some operating systems 31255360Sobrienand filesystems disallow this, and will cause @command{grep} to print error 31353564Sobrienmessages for every directory). If @var{action} is @samp{skip}, 31453564Sobriendirectories are silently skipped. If @var{action} is @samp{recurse}, 31555360Sobrien@command{grep} reads all files under each directory, recursively; this is 31653564Sobrienequivalent to the @samp{-r} option. 31753564Sobrien 31855360Sobrien@item -H 31955360Sobrien@itemx --with-filename 32055360Sobrien@opindex -H 32155360Sobrien@opindex --With-filename 32255360Sobrien@cindex with filename prefix 32355360SobrienPrint the filename for each match. 32455360Sobrien 32553564Sobrien@item -h 32653564Sobrien@itemx --no-filename 32753564Sobrien@opindex -h 32853564Sobrien@opindex --no-filename 32953564Sobrien@cindex no filename prefix 33053564SobrienSuppress the prefixing of filenames on output when multiple files are searched. 33153564Sobrien 33253564Sobrien@item -L 33353564Sobrien@itemx --files-without-match 33453564Sobrien@opindex -L 33553564Sobrien@opindex --files-without-match 33653564Sobrien@cindex files which don't match 33755360SobrienSuppress normal output; instead print the name of each input 33855360Sobrienfile from which no output would normally have been printed. 33955360SobrienThe scanning of every file will stop on the first match. 34053564Sobrien 34153564Sobrien@item -a 34253564Sobrien@itemx --text 34353564Sobrien@opindex -a 34453564Sobrien@opindex --text 34553564Sobrien@cindex suppress binary data 34653564Sobrien@cindex binary files 34756230SruProcess a binary file as if it were text; this is equivalent to the 34856230Sru@samp{--binary-files=text} option. 34953564Sobrien 35053564Sobrien@item -w 35153564Sobrien@itemx --word-regexp 35253564Sobrien@opindex -w 35353564Sobrien@opindex --word-regexp 35453564Sobrien@cindex matching whole words 35555360SobrienSelect only those lines containing matches that form 35655360Sobrienwhole words. The test is that the matching substring 35755360Sobrienmust either be at the beginning of the line, or preceded 35853564Sobrienby a non-word constituent character. Similarly, 35953564Sobrienit must be either at the end of the line or followed by 36055360Sobriena non-word constituent character. Word-constituent 36153564Sobriencharacters are letters, digits, and the underscore. 36253564Sobrien 36353564Sobrien@item -r 36453564Sobrien@itemx --recursive 36553564Sobrien@opindex -r 36653564Sobrien@opindex --recursive 36753564Sobrien@cindex recursive search 36853564Sobrien@cindex searching directory trees 36953564SobrienFor each directory mentioned in the command line, read and process all 37053564Sobrienfiles in that directory, recursively. This is the same as the @samp{-d 37153564Sobrienrecurse} option. 37253564Sobrien 37353564Sobrien@item -y 37453564Sobrien@opindex -y 37553564Sobrien@cindex case insensitive search, obsolete option 37653564SobrienObsolete synonym for @samp{-i}. 37753564Sobrien 37853564Sobrien@item -U 37953564Sobrien@itemx --binary 38053564Sobrien@opindex -U 38153564Sobrien@opindex --binary 38253564Sobrien@cindex DOS/Windows binary files 38353564Sobrien@cindex binary files, DOS/Windows 38455360SobrienTreat the file(s) as binary. By default, under @sc{ms-dos} 38555360Sobrienand MS-Windows, @command{grep} guesses the file type by looking 38655360Sobrienat the contents of the first 32kB read from the file. 38755360SobrienIf @command{grep} decides the file is a text file, it strips the 38855360Sobrien@code{CR} characters from the original file contents (to make 38955360Sobrienregular expressions with @code{^} and @code{$} work correctly). 39053564SobrienSpecifying @samp{-U} overrules this guesswork, causing all 39155360Sobrienfiles to be read and passed to the matching mechanism 39255360Sobrienverbatim; if the file is a text file with @code{CR/LF} pairs 39355360Sobrienat the end of each line, this will cause some regular 39455360Sobrienexpressions to fail. This option has no effect on platforms other than 39555360Sobrien@sc{ms-dos} and MS-Windows. 39653564Sobrien 39753564Sobrien@item -u 39853564Sobrien@itemx --unix-byte-offsets 39953564Sobrien@opindex -u 40053564Sobrien@opindex --unix-byte-offsets 40153564Sobrien@cindex DOS byte offsets 40253564Sobrien@cindex byte offsets, on DOS/Windows 40355360SobrienReport Unix-style byte offsets. This switch causes 40455360Sobrien@command{grep} to report byte offsets as if the file were Unix style 40555360Sobrientext file, i.e., the byte offsets ignore the @code{CR} characters which were 40655360Sobrienstripped. This will produce results identical to running @command{grep} on 40755360Sobriena Unix machine. This option has no effect unless @samp{-b} 40855360Sobrienoption is also used; it has no effect on platforms other than @sc{ms-dos} and 40953564SobrienMS-Windows. 41053564Sobrien 41155360Sobrien@item --mmap 41255360Sobrien@opindex --mmap 41355360Sobrien@cindex memory mapped input 41455360SobrienIf possible, use the @code{mmap} system call to read input, instead of 41555360Sobrienthe default @code{read} system call. In some situations, @samp{--mmap} 41655360Sobrienyields better performance. However, @samp{--mmap} can cause undefined 41755360Sobrienbehavior (including core dumps) if an input file shrinks while 41855360Sobrien@command{grep} is operating, or if an I/O error occurs. 41955360Sobrien 42055360Sobrien@item -Z 42155360Sobrien@itemx --null 42255360Sobrien@opindex -Z 42355360Sobrien@opindex --null 42455360Sobrien@cindex zero-terminated file names 42555360SobrienOutput a zero byte (the @sc{ascii} @code{NUL} character) instead of the 42655360Sobriencharacter that normally follows a file name. For example, @samp{grep 42755360Sobrien-lZ} outputs a zero byte after each file name instead of the usual 42855360Sobriennewline. This option makes the output unambiguous, even in the presence 42955360Sobrienof file names containing unusual characters like newlines. This option 43055360Sobriencan be used with commands like @samp{find -print0}, @samp{perl -0}, 43155360Sobrien@samp{sort -z}, and @samp{xargs -0} to process arbitrary file names, 43255360Sobrieneven those that contain newline characters. 43355360Sobrien 43455360Sobrien@item -z 43555360Sobrien@itemx --null-data 43655360Sobrien@opindex -z 43755360Sobrien@opindex --null-data 43855360Sobrien@cindex zero-terminated lines 43955360SobrienTreat the input as a set of lines, each terminated by a zero byte (the 44055360Sobrien@sc{ascii} @code{NUL} character) instead of a newline. Like the @samp{-Z} 44155360Sobrienor @samp{--null} option, this option can be used with commands like 44255360Sobrien@samp{sort -z} to process arbitrary file names. 44355360Sobrien 44453564Sobrien@end table 44553564Sobrien 44655360SobrienSeveral additional options control which variant of the @command{grep} 44753564Sobrienmatching engine is used. @xref{Grep Programs}. 44853564Sobrien 44955360Sobrien@section Environment Variables 45053564Sobrien 45155360SobrienGrep's behavior is affected by the following environment variables. 45255360Sobrien@cindex environment variables 45355360Sobrien 45455360Sobrien@table @code 45555360Sobrien 45655360Sobrien@item GREP_OPTIONS 45755360Sobrien@vindex GREP_OPTIONS 45855360Sobrien@cindex default options environment variable 45955360SobrienThis variable specifies default options to be placed in front of any 46055360Sobrienexplicit options. For example, if @code{GREP_OPTIONS} is @samp{--text 46155360Sobrien--directories=skip}, @command{grep} behaves as if the two options 46255360Sobrien@samp{--text} and @samp{--directories=skip} had been specified before 46355360Sobrienany explicit options. Option specifications are separated by 46455360Sobrienwhitespace. A backslash escapes the next character, so it can be used to 46555360Sobrienspecify an option containing whitespace or a backslash. 46655360Sobrien 46755360Sobrien@item LC_ALL 46855360Sobrien@itemx LC_MESSAGES 46955360Sobrien@itemx LANG 47055360Sobrien@vindex LC_ALL 47155360Sobrien@vindex LC_MESSAGES 47255360Sobrien@vindex LANG 47355360Sobrien@cindex language of messages 47455360Sobrien@cindex message language 47555360Sobrien@cindex national language support 47655360Sobrien@cindex NLS 47755360Sobrien@cindex translation of message language 47855360SobrienThese variables specify the @code{LC_MESSAGES} locale, which determines 47955360Sobrienthe language that @command{grep} uses for messages. The locale is determined 48055360Sobrienby the first of these variables that is set. American English is used 48155360Sobrienif none of these environment variables are set, or if the message 48255360Sobriencatalog is not installed, or if @command{grep} was not compiled with national 48355360Sobrienlanguage support (@sc{nls}). 48455360Sobrien 48555360Sobrien@item LC_ALL 48655360Sobrien@itemx LC_CTYPE 48755360Sobrien@itemx LANG 48855360Sobrien@vindex LC_ALL 48955360Sobrien@vindex LC_CTYPE 49055360Sobrien@vindex LANG 49155360Sobrien@cindex character type 49255360Sobrien@cindex national language support 49355360Sobrien@cindex NLS 49455360SobrienThese variables specify the @code{LC_CTYPE} locale, which determines the 49555360Sobrientype of characters, e.g., which characters are whitespace. The locale is 49655360Sobriendetermined by the first of these variables that is set. The @sc{posix} 49755360Sobrienlocale is used if none of these environment variables are set, or if the 49855360Sobrienlocale catalog is not installed, or if @command{grep} was not compiled with 49955360Sobriennational language support (@sc{nls}). 50055360Sobrien 50155360Sobrien@item POSIXLY_CORRECT 50255360Sobrien@vindex POSIXLY_CORRECT 50355360SobrienIf set, @command{grep} behaves as @sc{posix.2} requires; otherwise, 50455360Sobrien@command{grep} behaves more like other @sc{gnu} programs. @sc{posix.2} 50555360Sobrienrequires that options that 50655360Sobrienfollow file names must be treated as file names; by default, such 50755360Sobrienoptions are permuted to the front of the operand list and are treated as 50855360Sobrienoptions. Also, @sc{posix.2} requires that unrecognized options be 50955360Sobriendiagnosed as 51055360Sobrien``illegal'', but since they are not really against the law the default 51155360Sobrienis to diagnose them as ``invalid''. @code{POSIXLY_CORRECT} also 51255360Sobriendisables @code{_@var{N}_GNU_nonoption_argv_flags_}, described below. 51355360Sobrien 51455360Sobrien@item _@var{N}_GNU_nonoption_argv_flags_ 51555360Sobrien@vindex _@var{N}_GNU_nonoption_argv_flags_ 51655360Sobrien(Here @code{@var{N}} is @command{grep}'s numeric process ID.) If the 51755360Sobrien@var{i}th character of this environment variable's value is @samp{1}, do 51855360Sobriennot consider the @var{i}th operand of @command{grep} to be an option, even if 51955360Sobrienit appears to be one. A shell can put this variable in the environment 52055360Sobrienfor each command it runs, specifying which operands are the results of 52155360Sobrienfile name wildcard expansion and therefore should not be treated as 52255360Sobrienoptions. This behavior is available only with the @sc{gnu} C library, and 52355360Sobrienonly when @code{POSIXLY_CORRECT} is not set. 52455360Sobrien 52555360Sobrien@end table 52655360Sobrien 52755360Sobrien@node Diagnostics 52853564Sobrien@chapter Diagnostics 52955360Sobrien 53053564SobrienNormally, exit status is 0 if matches were found, and 1 if no matches 53153564Sobrienwere found (the @samp{-v} option inverts the sense of the exit status). 53255360SobrienExit status is 2 if there were syntax errors in the pattern, 53353564Sobrieninaccessible input files, or other system errors. 53453564Sobrien 53555360Sobrien@node Grep Programs 53655360Sobrien@chapter @command{grep} programs 53753564Sobrien 53855360Sobrien@command{grep} searches the named input files (or standard input if no 53953564Sobrienfiles are named, or the file name @file{-} is given) for lines containing 54055360Sobriena match to the given pattern. By default, @command{grep} prints the 54155360Sobrienmatching lines. There are three major variants of @command{grep}, 54255360Sobriencontrolled by the following options. 54353564Sobrien 54453564Sobrien@table @samp 54553564Sobrien 54653564Sobrien@item -G 54753564Sobrien@itemx --basic-regexp 54853564Sobrien@opindex -G 54953564Sobrien@opindex --basic-regexp 55053564Sobrien@cindex matching basic regular expressions 55155360SobrienInterpret pattern as a basic regular expression. This is the default. 55253564Sobrien 55353564Sobrien@item -E 55455360Sobrien@itemx --extended-regexp 55553564Sobrien@opindex -E 55653564Sobrien@opindex --extended-regexp 55753564Sobrien@cindex matching extended regular expressions 55855360SobrienInterpret pattern as an extended regular expression. 55953564Sobrien 56053564Sobrien 56153564Sobrien@item -F 56253564Sobrien@itemx --fixed-strings 56353564Sobrien@opindex -F 56453564Sobrien@opindex --fixed-strings 56553564Sobrien@cindex matching fixed strings 56653564SobrienInterpret pattern as a list of fixed strings, separated 56753564Sobrienby newlines, any of which is to be matched. 56853564Sobrien 56953564Sobrien@end table 57053564Sobrien 57153564SobrienIn addition, two variant programs @sc{egrep} and @sc{fgrep} are available. 57255360Sobrien@sc{egrep} is the same as @samp{grep -E}. @sc{fgrep} is the 57353564Sobriensame as @samp{grep -F}. 57453564Sobrien 57555360Sobrien@node Regular Expressions 57653564Sobrien@chapter Regular Expressions 57753564Sobrien@cindex regular expressions 57853564Sobrien 57955360SobrienA @dfn{regular expression} is a pattern that describes a set of strings. 58053564SobrienRegular expressions are constructed analogously to arithmetic expressions, 58155360Sobrienby using various operators to combine smaller expressions. 58255360Sobrien@command{grep} understands two different versions of regular expression 58355360Sobriensyntax: ``basic'' and ``extended''. In @sc{gnu} @command{grep}, there is no 58455360Sobriendifference in available functionality using either syntax. 58555360SobrienIn other implementations, basic regular expressions are less powerful. 58655360SobrienThe following description applies to extended regular expressions; 58753564Sobriendifferences for basic regular expressions are summarized afterwards. 58853564Sobrien 58955360SobrienThe fundamental building blocks are the regular expressions that match 59053564Sobriena single character. Most characters, including all letters and digits, 59155360Sobrienare regular expressions that match themselves. Any metacharacter 59253564Sobrienwith special meaning may be quoted by preceding it with a backslash. 59353564SobrienA list of characters enclosed by @samp{[} and @samp{]} matches any 59453564Sobriensingle character in that list; if the first character of the list is the 59555360Sobriencaret @samp{^}, then it 59653564Sobrienmatches any character @strong{not} in the list. For example, the regular 59753564Sobrienexpression @samp{[0123456789]} matches any single digit. 59855360SobrienA range of @sc{ascii} characters may be specified by giving the first 59955360Sobrienand last characters, separated by a hyphen. 60053564Sobrien 60155360SobrienFinally, certain named classes of characters are predefined, as follows. 60255360SobrienTheir interpretation depends on the @code{LC_CTYPE} locale; the 60355360Sobrieninterpretation below is that of the @sc{posix} locale, which is the default 60455360Sobrienif no @code{LC_CTYPE} locale is specified. 60555360Sobrien 60653564Sobrien@cindex classes of characters 60753564Sobrien@cindex character classes 60853564Sobrien@table @samp 60953564Sobrien 61053564Sobrien@item [:alnum:] 61155360Sobrien@opindex alnum 61255360Sobrien@cindex alphanumeric characters 61355360SobrienAny of @samp{[:digit:]} or @samp{[:alpha:]} 61453564Sobrien 61553564Sobrien@item [:alpha:] 61653564Sobrien@opindex alpha 61753564Sobrien@cindex alphabetic characters 61855360SobrienAny letter:@* 61953564Sobrien@code{a b c d e f g h i j k l m n o p q r s t u v w x y z},@* 62053564Sobrien@code{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}. 62153564Sobrien 62255360Sobrien@item [:blank:] 62355360Sobrien@opindex blank 62455360Sobrien@cindex blank characters 62555360SobrienSpace or tab. 62655360Sobrien 62753564Sobrien@item [:cntrl:] 62853564Sobrien@opindex cntrl 62953564Sobrien@cindex control characters 63055360SobrienAny character with octal codes 000 through 037, or @code{DEL} (octal 63155360Sobriencode 177). 63253564Sobrien 63353564Sobrien@item [:digit:] 63453564Sobrien@opindex digit 63553564Sobrien@cindex digit characters 63653564Sobrien@cindex numeric characters 63753564SobrienAny one of @code{0 1 2 3 4 5 6 7 8 9}. 63853564Sobrien 63953564Sobrien@item [:graph:] 64053564Sobrien@opindex graph 64153564Sobrien@cindex graphic characters 64255360SobrienAnything that is not a @samp{[:alnum:]} or @samp{[:punct:]}. 64353564Sobrien 64453564Sobrien@item [:lower:] 64553564Sobrien@opindex lower 64653564Sobrien@cindex lower-case alphabetic characters 64753564SobrienAny one of @code{a b c d e f g h i j k l m n o p q r s t u v w x y z}. 64853564Sobrien 64953564Sobrien@item [:print:] 65053564Sobrien@opindex print 65153564Sobrien@cindex printable characters 65253564SobrienAny character from the @samp{[:space:]} class, and any character that is 65355360Sobrien@strong{not} in the @samp{[:graph:]} class. 65453564Sobrien 65553564Sobrien@item [:punct:] 65653564Sobrien@opindex punct 65753564Sobrien@cindex punctuation characters 65855360SobrienAny one of @code{!@: " # $ % & ' ( ) * + , - .@: / : ; < = > ?@: @@ [ \ ] ^ _ ` @{ | @} ~}. 65953564Sobrien 66053564Sobrien@item [:space:] 66153564Sobrien@opindex space 66253564Sobrien@cindex space characters 66353564Sobrien@cindex whitespace characters 66453564SobrienAny one of @code{CR FF HT NL VT SPACE}. 66553564Sobrien 66653564Sobrien@item [:upper:] 66753564Sobrien@opindex upper 66853564Sobrien@cindex upper-case alphabetic characters 66953564SobrienAny one of @code{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}. 67053564Sobrien 67153564Sobrien@item [:xdigit:] 67253564Sobrien@opindex xdigit 67353564Sobrien@cindex xdigit class 67453564Sobrien@cindex hexadecimal digits 67553564SobrienAny one of @code{a b c d e f A B C D E F 0 1 2 3 4 5 6 7 8 9}. 67653564Sobrien 67753564Sobrien@end table 67853564SobrienFor example, @samp{[[:alnum:]]} means @samp{[0-9A-Za-z]}, except the latter 67955360Sobrienform is dependent upon the @sc{ascii} character encoding, whereas the 68055360Sobrienformer is portable. (Note that the brackets in these class names are 68155360Sobrienpart of the symbolic names, and must be included in addition to 68255360Sobrienthe brackets delimiting the bracket list.) Most metacharacters lose 68353564Sobrientheir special meaning inside lists. To include a literal @samp{]}, place it 68453564Sobrienfirst in the list. Similarly, to include a literal @samp{^}, place it anywhere 68555360Sobrienbut first. Finally, to include a literal @samp{-}, place it last. 68653564Sobrien 68753564SobrienThe period @samp{.} matches any single character. The symbol @samp{\w} 68853564Sobrienis a synonym for @samp{[[:alnum:]]} and @samp{\W} is a synonym for 68953564Sobrien@samp{[^[:alnum]]}. 69053564Sobrien 69153564SobrienThe caret @samp{^} and the dollar sign @samp{$} are metacharacters that 69253564Sobrienrespectively match the empty string at the beginning and end 69355360Sobrienof a line. The symbols @samp{\<} and @samp{\>} respectively match the 69453564Sobrienempty string at the beginning and end of a word. The symbol 69555360Sobrien@samp{\b} matches the empty string at the edge of a word, and @samp{\B} 69655360Sobrienmatches the empty string provided it's not at the edge of a word. 69753564Sobrien 69855360SobrienA regular expression may be followed by one of several 69953564Sobrienrepetition operators: 70053564Sobrien 70153564Sobrien 70253564Sobrien@table @samp 70353564Sobrien 70453564Sobrien@item ? 70553564Sobrien@opindex ? 70653564Sobrien@cindex question mark 70753564Sobrien@cindex match sub-expression at most once 70853564SobrienThe preceding item is optional and will be matched at most once. 70953564Sobrien 71053564Sobrien@item * 71153564Sobrien@opindex * 71253564Sobrien@cindex asterisk 71353564Sobrien@cindex match sub-expression zero or more times 71453564SobrienThe preceding item will be matched zero or more times. 71553564Sobrien 71653564Sobrien@item + 71753564Sobrien@opindex + 71855360Sobrien@cindex plus sign 71953564SobrienThe preceding item will be matched one or more times. 72053564Sobrien 72153564Sobrien@item @{@var{n}@} 72253564Sobrien@opindex @{n@} 72353564Sobrien@cindex braces, one argument 72453564Sobrien@cindex match sub-expression n times 72553564SobrienThe preceding item is matched exactly @var{n} times. 72653564Sobrien 72753564Sobrien@item @{@var{n},@} 72853564Sobrien@opindex @{n,@} 72953564Sobrien@cindex braces, second argument omitted 73053564Sobrien@cindex match sub-expression n or more times 73153564SobrienThe preceding item is matched n or more times. 73253564Sobrien 73353564Sobrien@item @{@var{n},@var{m}@} 73453564Sobrien@opindex @{n,m@} 73553564Sobrien@cindex braces, two arguments 73653564SobrienThe preceding item is matched at least @var{n} times, but not more than 73753564Sobrien@var{m} times. 73853564Sobrien 73953564Sobrien@end table 74053564Sobrien 74155360SobrienTwo regular expressions may be concatenated; the resulting regular 74253564Sobrienexpression matches any string formed by concatenating two substrings 74355360Sobrienthat respectively match the concatenated subexpressions. 74453564Sobrien 74555360SobrienTwo regular expressions may be joined by the infix operator @samp{|}; the 74655360Sobrienresulting regular expression matches any string matching either 74753564Sobriensubexpression. 74853564Sobrien 74955360SobrienRepetition takes precedence over concatenation, which in turn 75053564Sobrientakes precedence over alternation. A whole subexpression may be 75155360Sobrienenclosed in parentheses to override these precedence rules. 75253564Sobrien 75353564SobrienThe backreference @samp{\@var{n}}, where @var{n} is a single digit, matches the 75453564Sobriensubstring previously matched by the @var{n}th parenthesized subexpression 75553564Sobrienof the regular expression. 75653564Sobrien 75753564Sobrien@cindex basic regular expressions 75853564SobrienIn basic regular expressions the metacharacters @samp{?}, @samp{+}, 75953564Sobrien@samp{@{}, @samp{|}, @samp{(}, and @samp{)} lose their special meaning; 76053564Sobrieninstead use the backslashed versions @samp{\?}, @samp{\+}, @samp{\@{}, 76153564Sobrien@samp{\|}, @samp{\(}, and @samp{\)}. 76253564Sobrien 76355360Sobrien@cindex interval specifications 76455360SobrienTraditional @command{egrep} did not support the @samp{@{} metacharacter, 76555360Sobrienand some @command{egrep} implementations support @samp{\@{} instead, so 76655360Sobrienportable scripts should avoid @samp{@{} in @samp{egrep} patterns and 76755360Sobrienshould use @samp{[@{]} to match a literal @samp{@{}. 76853564Sobrien 76955360Sobrien@sc{gnu} @command{egrep} attempts to support traditional usage by 77055360Sobrienassuming that @samp{@{} is not special if it would be the start of an 77155360Sobrieninvalid interval specification. For example, the shell command 77255360Sobrien@samp{egrep '@{1'} searches for the two-character string @samp{@{1} 77355360Sobrieninstead of reporting a syntax error in the regular expression. 77455360Sobrien@sc{posix.2} allows this behavior as an extension, but portable scripts 77555360Sobrienshould avoid it. 77653564Sobrien 77755360Sobrien@node Usage 77855360Sobrien@chapter Usage 77955360Sobrien 78055360Sobrien@cindex Usage, examples 78155360SobrienHere is an example shell command that invokes @sc{gnu} @command{grep}: 78255360Sobrien 78355360Sobrien@example 78455360Sobriengrep -i 'hello.*world' menu.h main.c 78555360Sobrien@end example 78655360Sobrien 78755360Sobrien@noindent 78855360SobrienThis lists all lines in the files @file{menu.h} and @file{main.c} that 78955360Sobriencontain the string @samp{hello} followed by the string @samp{world}; 79055360Sobrienthis is because @samp{.*} matches zero or more characters within a line. 79155360Sobrien@xref{Regular Expressions}. The @samp{-i} option causes @command{grep} 79255360Sobriento ignore case, causing it to match the line @samp{Hello, world!}, which 79355360Sobrienit would not otherwise match. @xref{Invoking}, for more details about 79455360Sobrienhow to invoke @command{grep}. 79555360Sobrien 79655360Sobrien@cindex Using @command{grep}, Q&A 79755360Sobrien@cindex FAQ about @command{grep} usage 79855360SobrienHere are some common questions and answers about @command{grep} usage. 79955360Sobrien 80055360Sobrien@enumerate 80155360Sobrien 80255360Sobrien@item 80355360SobrienHow can I list just the names of matching files? 80455360Sobrien 80555360Sobrien@example 80655360Sobriengrep -l 'main' *.c 80755360Sobrien@end example 80855360Sobrien 80955360Sobrien@noindent 81055360Sobrienlists the names of all C files in the current directory whose contents 81155360Sobrienmention @samp{main}. 81255360Sobrien 81355360Sobrien@item 81455360SobrienHow do I search directories recursively? 81555360Sobrien 81655360Sobrien@example 81755360Sobriengrep -r 'hello' /home/gigi 81855360Sobrien@end example 81955360Sobrien 82055360Sobrien@noindent 82155360Sobriensearches for @samp{hello} in all files under the directory 82255360Sobrien@file{/home/gigi}. For more control of which files are searched, use 82355360Sobrien@command{find}, @command{grep} and @command{xargs}. For example, 82455360Sobrienthe following command searches only C files: 82555360Sobrien 82655360Sobrien@smallexample 82755360Sobrienfind /home/gigi -name '*.c' -print | xargs grep 'hello' /dev/null 82855360Sobrien@end smallexample 82955360Sobrien 83055360Sobrien@item 83155360SobrienWhat if a pattern has a leading @samp{-}? 83255360Sobrien 83355360Sobrien@example 83455360Sobriengrep -e '--cut here--' * 83555360Sobrien@end example 83655360Sobrien 83755360Sobrien@noindent 83855360Sobriensearches for all lines matching @samp{--cut here--}. Without @samp{-e}, 83955360Sobrien@command{grep} would attempt to parse @samp{--cut here--} as a list of 84055360Sobrienoptions. 84155360Sobrien 84255360Sobrien@item 84355360SobrienSuppose I want to search for a whole word, not a part of a word? 84455360Sobrien 84555360Sobrien@example 84655360Sobriengrep -w 'hello' * 84755360Sobrien@end example 84855360Sobrien 84955360Sobrien@noindent 85055360Sobriensearches only for instances of @samp{hello} that are entire words; it 85155360Sobriendoes not match @samp{Othello}. For more control, use @samp{\<} and 85255360Sobrien@samp{\>} to match the start and end of words. For example: 85355360Sobrien 85455360Sobrien@example 85555360Sobriengrep 'hello\>' * 85655360Sobrien@end example 85755360Sobrien 85855360Sobrien@noindent 85955360Sobriensearches only for words ending in @samp{hello}, so it matches the word 86055360Sobrien@samp{Othello}. 86155360Sobrien 86255360Sobrien@item 86355360SobrienHow do I output context around the matching lines? 86455360Sobrien 86555360Sobrien@example 86655360Sobriengrep -C 2 'hello' * 86755360Sobrien@end example 86855360Sobrien 86955360Sobrien@noindent 87055360Sobrienprints two lines of context around each matching line. 87155360Sobrien 87255360Sobrien@item 87355360SobrienHow do I force grep to print the name of the file? 87455360Sobrien 87555360SobrienAppend @file{/dev/null}: 87655360Sobrien 87755360Sobrien@example 87855360Sobriengrep 'eli' /etc/passwd /dev/null 87955360Sobrien@end example 88055360Sobrien 88155360Sobrien@item 88255360SobrienWhy do people use strange regular expressions on @command{ps} output? 88355360Sobrien 88455360Sobrien@example 88555360Sobrienps -ef | grep '[c]ron' 88655360Sobrien@end example 88755360Sobrien 88855360SobrienIf the pattern had been written without the square brackets, it would 88955360Sobrienhave matched not only the @command{ps} output line for @command{cron}, 89055360Sobrienbut also the @command{ps} output line for @command{grep}. 89155360Sobrien 89255360Sobrien@item 89355360SobrienWhy does @command{grep} report ``Binary file matches''? 89455360Sobrien 89555360SobrienIf @command{grep} listed all matching ``lines'' from a binary file, it 89655360Sobrienwould probably generate output that is not useful, and it might even 89755360Sobrienmuck up your display. So @sc{gnu} @command{grep} suppresses output from 89855360Sobrienfiles that appear to be binary files. To force @sc{gnu} @command{grep} 89955360Sobriento output lines even from files that appear to be binary, use the 90055360Sobrien@samp{-a} or @samp{--text} option. 90155360Sobrien 90255360Sobrien@item 90355360SobrienWhy doesn't @samp{grep -lv} print nonmatching file names? 90455360Sobrien 90555360Sobrien@samp{grep -lv} lists the names of all files containing one or more 90655360Sobrienlines that do not match. To list the names of all files that contain no 90755360Sobrienmatching lines, use the @samp{-L} or @samp{--files-without-match} 90855360Sobrienoption. 90955360Sobrien 91055360Sobrien@item 91155360SobrienI can do @sc{or} with @samp{|}, but what about @sc{and}? 91255360Sobrien 91355360Sobrien@example 91455360Sobriengrep 'paul' /etc/motd | grep 'franc,ois' 91555360Sobrien@end example 91655360Sobrien 91755360Sobrien@noindent 91855360Sobrienfinds all lines that contain both @samp{paul} and @samp{franc,ois}. 91955360Sobrien 92055360Sobrien@item 92155360SobrienHow can I search in both standard input and in files? 92255360Sobrien 92355360SobrienUse the special file name @samp{-}: 92455360Sobrien 92555360Sobrien@example 92655360Sobriencat /etc/passwd | grep 'alain' - /etc/motd 92755360Sobrien@end example 92855360Sobrien@end enumerate 92955360Sobrien 93055360Sobrien@node Reporting Bugs 93153564Sobrien@chapter Reporting bugs 93253564Sobrien 93353564Sobrien@cindex Bugs, reporting 93453564SobrienEmail bug reports to @email{bug-gnu-utils@@gnu.org}. 93553564SobrienBe sure to include the word ``grep'' somewhere in the ``Subject:'' field. 93653564Sobrien 93755360SobrienLarge repetition counts in the @samp{@{m,n@}} construct may cause 93855360Sobrien@command{grep} to use lots of memory. In addition, certain other 93955360Sobrienobscure regular expressions require exponential time and 94053564Sobrienspace, and may cause grep to run out of memory. 94155360SobrienBackreferences are very slow, and may require exponential time. 94253564Sobrien 94353564Sobrien@page 94455360Sobrien@node Concept Index 94553564Sobrien@unnumbered Concept Index 94653564Sobrien 94753564SobrienThis is a general index of all issues discussed in this manual, with the 94855360Sobrienexception of the @command{grep} commands and command-line options. 94953564Sobrien 95053564Sobrien@printindex cp 95153564Sobrien 95253564Sobrien@page 95355360Sobrien@node Index 95453564Sobrien@unnumbered Index 95553564Sobrien 95655360SobrienThis is an alphabetical list of all @command{grep} commands, command-line 95755360Sobrienoptions, and environment variables. 95853564Sobrien 95953564Sobrien@printindex fn 96053564Sobrien 96153564Sobrien@contents 96253564Sobrien@bye 963