1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename grep.info 4@include version.texi 5@settitle GNU Grep @value{VERSION} 6 7@c Combine indices. 8@syncodeindex ky cp 9@syncodeindex pg cp 10@syncodeindex tp cp 11@defcodeindex op 12@syncodeindex op cp 13@syncodeindex vr cp 14@c %**end of header 15 16@copying 17This manual is for @command{grep}, a pattern matching engine. 18 19Copyright @copyright{} 1999-2002, 2005, 2008-2012 Free Software Foundation, 20Inc. 21 22@quotation 23Permission is granted to copy, distribute and/or modify this document 24under the terms of the GNU Free Documentation License, Version 1.3 or 25any later version published by the Free Software Foundation; with no 26Invariant Sections, with no Front-Cover Texts, and with no Back-Cover 27Texts. A copy of the license is included in the section entitled 28``GNU Free Documentation License''. 29@end quotation 30@end copying 31 32@dircategory Text creation and manipulation 33@direntry 34* grep: (grep). Print lines matching a pattern. 35@end direntry 36 37@titlepage 38@title GNU Grep: Print lines matching a pattern 39@subtitle version @value{VERSION}, @value{UPDATED} 40@author Alain Magloire et al. 41@page 42@vskip 0pt plus 1filll 43@insertcopying 44@end titlepage 45 46@contents 47 48 49@ifnottex 50@node Top 51@top grep 52 53@command{grep} prints lines that contain a match for a pattern. 54 55This manual is for version @value{VERSION} of GNU Grep. 56 57@insertcopying 58@end ifnottex 59 60@menu 61* Introduction:: Introduction. 62* Invoking:: Command-line options, environment, exit status. 63* Regular Expressions:: Regular Expressions. 64* Usage:: Examples. 65* Reporting Bugs:: Reporting Bugs. 66* Copying:: License terms for this manual. 67* Index:: Combined index. 68@end menu 69 70 71@node Introduction 72@chapter Introduction 73 74@cindex searching for a pattern 75 76@command{grep} searches input files 77for lines containing a match to a given pattern list. 78When it finds a match in a line, 79it copies the line to standard output (by default), 80or produces whatever other sort of output you have requested with options. 81 82Though @command{grep} expects to do the matching on text, 83it has no limits on input line length other than available memory, 84and it can match arbitrary characters within a line. 85If the final byte of an input file is not a newline, 86@command{grep} silently supplies one. 87Since newline is also a separator for the list of patterns, 88there is no way to match newline characters in a text. 89 90 91@node Invoking 92@chapter Invoking @command{grep} 93 94The general synopsis of the @command{grep} command line is 95 96@example 97grep @var{options} @var{pattern} @var{input_file_names} 98@end example 99 100@noindent 101There can be zero or more @var{options}. 102@var{pattern} will only be seen as such 103(and not as an @var{input_file_name}) 104if it wasn't already specified within @var{options} 105(by using the @samp{-e@ @var{pattern}} 106or @samp{-f@ @var{file}} options). 107There can be zero or more @var{input_file_names}. 108 109@menu 110* Command-line Options:: Short and long names, grouped by category. 111* Environment Variables:: POSIX, GNU generic, and GNU grep specific. 112* Exit Status:: Exit status returned by @command{grep}. 113* grep Programs:: @command{grep} programs. 114@end menu 115 116@node Command-line Options 117@section Command-line Options 118 119@command{grep} comes with a rich set of options: 120some from POSIX and some being GNU extensions. 121Long option names are always a GNU extension, 122even for options that are from POSIX specifications. 123Options that are specified by POSIX, 124under their short names, 125are explicitly marked as such 126to facilitate POSIX-portable programming. 127A few option names are provided 128for compatibility with older or more exotic implementations. 129 130@menu 131* Generic Program Information:: 132* Matching Control:: 133* General Output Control:: 134* Output Line Prefix Control:: 135* Context Line Control:: 136* File and Directory Selection:: 137* Other Options:: 138@end menu 139 140Several additional options control 141which variant of the @command{grep} matching engine is used. 142@xref{grep Programs}. 143 144@node Generic Program Information 145@subsection Generic Program Information 146 147@table @option 148 149@item --help 150@opindex --help 151@cindex usage summary, printing 152Print a usage message briefly summarizing the command-line options 153and the bug-reporting address, then exit. 154 155@item -V 156@itemx --version 157@opindex -V 158@opindex --version 159@cindex version, printing 160Print the version number of @command{grep} to the standard output stream. 161This version number should be included in all bug reports. 162 163@end table 164 165@node Matching Control 166@subsection Matching Control 167 168@table @option 169 170@item -e @var{pattern} 171@itemx --regexp=@var{pattern} 172@opindex -e 173@opindex --regexp=@var{pattern} 174@cindex pattern list 175Use @var{pattern} as the pattern. 176This can be used to specify multiple search patterns, 177or to protect a pattern beginning with a @samp{-}. 178(@option{-e} is specified by POSIX.) 179 180@item -f @var{file} 181@itemx --file=@var{file} 182@opindex -f 183@opindex --file 184@cindex pattern from file 185Obtain patterns from @var{file}, one per line. 186The empty file contains zero patterns, and therefore matches nothing. 187(@option{-f} is specified by POSIX.) 188 189@item -i 190@itemx -y 191@itemx --ignore-case 192@opindex -i 193@opindex -y 194@opindex --ignore-case 195@cindex case insensitive search 196Ignore case distinctions in both the pattern and the input files. 197@option{-y} is an obsolete synonym that is provided for compatibility. 198(@option{-i} is specified by POSIX.) 199 200@item -v 201@itemx --invert-match 202@opindex -v 203@opindex --invert-match 204@cindex invert matching 205@cindex print non-matching lines 206Invert the sense of matching, to select non-matching lines. 207(@option{-v} is specified by POSIX.) 208 209@item -w 210@itemx --word-regexp 211@opindex -w 212@opindex --word-regexp 213@cindex matching whole words 214Select only those lines containing matches that form whole words. 215The test is that the matching substring must either 216be at the beginning of the line, 217or preceded by a non-word constituent character. 218Similarly, 219it must be either at the end of the line 220or followed by a non-word constituent character. 221Word-constituent characters are letters, digits, and the underscore. 222 223@item -x 224@itemx --line-regexp 225@opindex -x 226@opindex --line-regexp 227@cindex match the whole line 228Select only those matches that exactly match the whole line. 229(@option{-x} is specified by POSIX.) 230 231@end table 232 233@node General Output Control 234@subsection General Output Control 235 236@table @option 237 238@item -c 239@itemx --count 240@opindex -c 241@opindex --count 242@cindex counting lines 243Suppress normal output; 244instead print a count of matching lines for each input file. 245With the @option{-v} (@option{--invert-match}) option, 246count non-matching lines. 247(@option{-c} is specified by POSIX.) 248 249@item --color[=@var{WHEN}] 250@itemx --colour[=@var{WHEN}] 251@opindex --color 252@opindex --colour 253@cindex highlight, color, colour 254Surround the matched (non-empty) strings, matching lines, context lines, 255file names, line numbers, byte offsets, and separators (for fields and 256groups of context lines) with escape sequences to display them in color 257on the terminal. 258The colors are defined by the environment variable @env{GREP_COLORS} 259and default to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36} 260for bold red matched text, magenta file names, green line numbers, 261green byte offsets, cyan separators, and default terminal colors otherwise. 262The deprecated environment variable @env{GREP_COLOR} is still supported, 263but its setting does not have priority; 264it defaults to @samp{01;31} (bold red) 265which only covers the color for matched text. 266@var{WHEN} is @samp{never}, @samp{always}, or @samp{auto}. 267 268@item -L 269@itemx --files-without-match 270@opindex -L 271@opindex --files-without-match 272@cindex files which don't match 273Suppress normal output; 274instead print the name of each input file from which 275no output would normally have been printed. 276The scanning of each file stops on the first match. 277 278@item -l 279@itemx --files-with-matches 280@opindex -l 281@opindex --files-with-matches 282@cindex names of matching files 283Suppress normal output; 284instead print the name of each input file from which 285output would normally have been printed. 286The scanning of each file stops on the first match. 287(@option{-l} is specified by POSIX.) 288 289@item -m @var{num} 290@itemx --max-count=@var{num} 291@opindex -m 292@opindex --max-count 293@cindex max-count 294Stop reading a file after @var{num} matching lines. 295If the input is standard input from a regular file, 296and @var{num} matching lines are output, 297@command{grep} ensures that the standard input is positioned 298just after the last matching line before exiting, 299regardless of the presence of trailing context lines. 300This enables a calling process to resume a search. 301For example, the following shell script makes use of it: 302 303@example 304while grep -m 1 PATTERN 305do 306 echo xxxx 307done < FILE 308@end example 309 310But the following probably will not work because a pipe is not a regular 311file: 312 313@example 314# This probably will not work. 315cat FILE | 316while grep -m 1 PATTERN 317do 318 echo xxxx 319done 320@end example 321 322When @command{grep} stops after @var{num} matching lines, 323it outputs any trailing context lines. 324Since context does not include matching lines, 325@command{grep} will stop when it encounters another matching line. 326When the @option{-c} or @option{--count} option is also used, 327@command{grep} does not output a count greater than @var{num}. 328When the @option{-v} or @option{--invert-match} option is also used, 329@command{grep} stops after outputting @var{num} non-matching lines. 330 331@item -o 332@itemx --only-matching 333@opindex -o 334@opindex --only-matching 335@cindex only matching 336Print only the matched (non-empty) parts of matching lines, 337with each such part on a separate output line. 338 339@item -q 340@itemx --quiet 341@itemx --silent 342@opindex -q 343@opindex --quiet 344@opindex --silent 345@cindex quiet, silent 346Quiet; do not write anything to standard output. 347Exit immediately with zero status if any match is found, 348even if an error was detected. 349Also see the @option{-s} or @option{--no-messages} option. 350(@option{-q} is specified by POSIX.) 351 352@item -s 353@itemx --no-messages 354@opindex -s 355@opindex --no-messages 356@cindex suppress error messages 357Suppress error messages about nonexistent or unreadable files. 358Portability note: 359unlike GNU @command{grep}, 3607th Edition Unix @command{grep} did not conform to POSIX, 361because it lacked @option{-q} 362and its @option{-s} option behaved like 363GNU @command{grep}'s @option{-q} option.@footnote{Of course, 7th Edition 364Unix predated POSIX by several years!} 365USG-style @command{grep} also lacked @option{-q} 366but its @option{-s} option behaved like GNU @command{grep}'s. 367Portable shell scripts should avoid both 368@option{-q} and @option{-s} and should redirect 369standard and error output to @file{/dev/null} instead. 370(@option{-s} is specified by POSIX.) 371 372@end table 373 374@node Output Line Prefix Control 375@subsection Output Line Prefix Control 376 377When several prefix fields are to be output, 378the order is always file name, line number, and byte offset, 379regardless of the order in which these options were specified. 380 381@table @option 382 383@item -b 384@itemx --byte-offset 385@opindex -b 386@opindex --byte-offset 387@cindex byte offset 388Print the 0-based byte offset within the input file 389before each line of output. 390If @option{-o} (@option{--only-matching}) is specified, 391print the offset of the matching part itself. 392When @command{grep} runs on MS-DOS or MS-Windows, 393the printed byte offsets depend on whether 394the @option{-u} (@option{--unix-byte-offsets}) option is used; 395see below. 396 397@item -H 398@itemx --with-filename 399@opindex -H 400@opindex --with-filename 401@cindex with filename prefix 402Print the file name for each match. 403This is the default when there is more than one file to search. 404 405@item -h 406@itemx --no-filename 407@opindex -h 408@opindex --no-filename 409@cindex no filename prefix 410Suppress the prefixing of file names on output. 411This is the default when there is only one file 412(or only standard input) to search. 413 414@item --label=@var{LABEL} 415@opindex --label 416@cindex changing name of standard input 417Display input actually coming from standard input 418as input coming from file @var{LABEL}. This is 419especially useful when implementing tools like 420@command{zgrep}; e.g.: 421 422@example 423gzip -cd foo.gz | grep --label=foo -H something 424@end example 425 426@item -n 427@itemx --line-number 428@opindex -n 429@opindex --line-number 430@cindex line numbering 431Prefix each line of output with the 1-based line number within its input file. 432(@option{-n} is specified by POSIX.) 433 434@item -T 435@itemx --initial-tab 436@opindex -T 437@opindex --initial-tab 438@cindex tab-aligned content lines 439Make sure that the first character of actual line content lies on a tab stop, 440so that the alignment of tabs looks normal. 441This is useful with options that prefix their output to the actual content: 442@option{-H}, @option{-n}, and @option{-b}. 443In order to improve the probability that lines 444from a single file will all start at the same column, 445this also causes the line number and byte offset (if present) 446to be printed in a minimum-size field width. 447 448@item -u 449@itemx --unix-byte-offsets 450@opindex -u 451@opindex --unix-byte-offsets 452@cindex MS-DOS/MS-Windows byte offsets 453@cindex byte offsets, on MS-DOS/MS-Windows 454Report Unix-style byte offsets. 455This option causes @command{grep} to report byte offsets 456as if the file were a Unix-style text file, 457i.e., the byte offsets ignore the @code{CR} characters that were stripped. 458This will produce results identical 459to running @command{grep} on a Unix machine. 460This option has no effect unless the @option{-b} option is also used; 461it has no effect on platforms other than MS-DOS and MS-Windows. 462 463@item -Z 464@itemx --null 465@opindex -Z 466@opindex --null 467@cindex zero-terminated file names 468Output a zero byte (the ASCII @code{NUL} character) 469instead of the character that normally follows a file name. 470For example, 471@samp{grep -lZ} outputs a zero byte after each file name 472instead of the usual newline. 473This option makes the output unambiguous, 474even in the presence of file names containing unusual characters like newlines. 475This option can be used with commands like 476@samp{find -print0}, @samp{perl -0}, @samp{sort -z}, and @samp{xargs -0} 477to process arbitrary file names, 478even those that contain newline characters. 479 480@end table 481 482@node Context Line Control 483@subsection Context Line Control 484 485Regardless of how these options are set, 486@command{grep} will never print any given line more than once. 487If the @option{-o} (@option{--only-matching}) option is specified, 488these options have no effect and a warning is given upon their use. 489 490@table @option 491 492@item -A @var{num} 493@itemx --after-context=@var{num} 494@opindex -A 495@opindex --after-context 496@cindex after context 497@cindex context lines, after match 498Print @var{num} lines of trailing context after matching lines. 499 500@item -B @var{num} 501@itemx --before-context=@var{num} 502@opindex -B 503@opindex --before-context 504@cindex before context 505@cindex context lines, before match 506Print @var{num} lines of leading context before matching lines. 507 508@item -C @var{num} 509@itemx -@var{num} 510@itemx --context=@var{num} 511@opindex -C 512@opindex --context 513@opindex -@var{num} 514@cindex context 515Print @var{num} lines of leading and trailing output context. 516 517@item --group-separator=@var{string} 518@opindex --group-separator 519@cindex group separator 520When @option{-A}, @option{-B} or @option{-C} are in use, 521print @var{string} instead of @option{--} around disjoint groups 522of lines. 523 524@item --no-group-separator 525@opindex --group-separator 526@cindex group separator 527When @option{-A}, @option{-B} or @option{-C} are in use, 528print disjoint groups of lines adjacent to each other. 529 530@end table 531 532Here are some points about how @command{grep} chooses 533the separator to print between prefix fields and line content: 534 535@itemize @bullet 536@item 537Matching lines normally use @samp{:} as a separator 538between prefix fields and actual line content. 539 540@item 541Context (i.e., non-matching) lines use @samp{-} instead. 542 543@item 544When no context is specified, 545matching lines are simply output one right after another. 546 547@item 548When nonzero context is specified, 549lines that are adjacent in the input form a group 550and are output one right after another, while 551a separator appears by default between disjoint groups on a line 552of its own and without any prefix. 553 554@item 555The default separator 556is @samp{--}, however whether to include it and its appearance 557can be changed with the options above. 558 559@item 560Each group may contain 561several matching lines when they are close enough to each other 562that two otherwise adjacent but divided groups connect 563and can just merge into a single contiguous one. 564@end itemize 565 566@node File and Directory Selection 567@subsection File and Directory Selection 568 569@table @option 570 571@item -a 572@itemx --text 573@opindex -a 574@opindex --text 575@cindex suppress binary data 576@cindex binary files 577Process a binary file as if it were text; 578this is equivalent to the @samp{--binary-files=text} option. 579 580@item --binary-files=@var{type} 581@opindex --binary-files 582@cindex binary files 583If a file's allocation metadata or its first few bytes 584indicate that the file contains binary data, 585assume that the file is of type @var{type}. 586By default, @var{type} is @samp{binary}, 587and @command{grep} normally outputs either 588a one-line message saying that a binary file matches, 589or no message if there is no match. 590 591If @var{type} is @samp{without-match}, 592@command{grep} assumes that a binary file does not match; 593this is equivalent to the @option{-I} option. 594 595If @var{type} is @samp{text}, 596@command{grep} processes a binary file as if it were text; 597this is equivalent to the @option{-a} option. 598 599@emph{Warning:} @samp{--binary-files=text} might output binary garbage, 600which can have nasty side effects 601if the output is a terminal and 602if the terminal driver interprets some of it as commands. 603 604@item -D @var{action} 605@itemx --devices=@var{action} 606@opindex -D 607@opindex --devices 608@cindex device search 609If an input file is a device, FIFO, or socket, use @var{action} to process it. 610If @var{action} is @samp{read}, 611all devices are read just as if they were ordinary files. 612If @var{action} is @samp{skip}, 613devices, FIFOs, and sockets are silently skipped. 614By default, devices are read if they are on the command line or if the 615@option{-R} (@option{--dereference-recursive}) option is used, and are 616skipped if they are encountered recursively and the @option{-r} 617(@option{--recursive}) option is used. 618This option has no effect on a file that is read via standard input. 619 620@item -d @var{action} 621@itemx --directories=@var{action} 622@opindex -d 623@opindex --directories 624@cindex directory search 625@cindex symbolic links 626If an input file is a directory, use @var{action} to process it. 627By default, @var{action} is @samp{read}, 628which means that directories are read just as if they were ordinary files 629(some operating systems and file systems disallow this, 630and will cause @command{grep} 631to print error messages for every directory or silently skip them). 632If @var{action} is @samp{skip}, directories are silently skipped. 633If @var{action} is @samp{recurse}, 634@command{grep} reads all files under each directory, recursively, 635following command-line symbolic links and skipping other symlinks; 636this is equivalent to the @option{-r} option. 637 638@item --exclude=@var{glob} 639@opindex --exclude 640@cindex exclude files 641@cindex searching directory trees 642Skip files whose base name matches @var{glob} 643(using wildcard matching). 644A file-name glob can use 645@samp{*}, @samp{?}, and @samp{[}...@samp{]} as wildcards, 646and @code{\} to quote a wildcard or backslash character literally. 647 648@item --exclude-from=@var{file} 649@opindex --exclude-from 650@cindex exclude files 651@cindex searching directory trees 652Skip files whose base name matches any of the file-name globs 653read from @var{file} (using wildcard matching as described 654under @option{--exclude}). 655 656@item --exclude-dir=@var{dir} 657@opindex --exclude-dir 658@cindex exclude directories 659Exclude directories matching the pattern @var{dir} from recursive 660directory searches. 661 662@item -I 663Process a binary file as if it did not contain matching data; 664this is equivalent to the @samp{--binary-files=without-match} option. 665 666@item --include=@var{glob} 667@opindex --include 668@cindex include files 669@cindex searching directory trees 670Search only files whose base name matches @var{glob} 671(using wildcard matching as described under @option{--exclude}). 672 673@item -r 674@itemx --recursive 675@opindex -r 676@opindex --recursive 677@cindex recursive search 678@cindex searching directory trees 679@cindex symbolic links 680For each directory operand, 681read and process all files in that directory, recursively. 682Follow symbolic links on the command line, but skip symlinks 683that are encountered recursively. 684This is the same as the @samp{--directories=recurse} option. 685 686@item -R 687@itemx --dereference-recursive 688@opindex -R 689@opindex --dereference-recursive 690@cindex recursive search 691@cindex searching directory trees 692@cindex symbolic links 693For each directory operand, read and process all files in that 694directory, recursively, following all symbolic links. 695 696@end table 697 698@node Other Options 699@subsection Other Options 700 701@table @option 702 703@item --line-buffered 704@opindex --line-buffered 705@cindex line buffering 706Use line buffering on output. 707This can cause a performance penalty. 708 709@item --mmap 710@opindex --mmap 711@cindex memory mapped input 712This option is deprecated and now elicits a warning, but is otherwise a no-op. 713It used to make @command{grep} read 714input with the @code{mmap} system call, instead of the default @code{read} 715system call. On modern systems, @code{mmap} would rarely if ever yield 716better performance. 717 718@item -U 719@itemx --binary 720@opindex -U 721@opindex --binary 722@cindex MS-DOS/MS-Windows binary files 723@cindex binary files, MS-DOS/MS-Windows 724Treat the file(s) as binary. 725By default, under MS-DOS and MS-Windows, 726@command{grep} guesses whether a file is text or binary 727as described for the @option{--binary-files} option. 728If @command{grep} decides the file is a text file, 729it strips the @code{CR} characters from the original file contents 730(to make regular expressions with @code{^} and @code{$} work correctly). 731Specifying @option{-U} overrules this guesswork, 732causing all files to be read and passed to the matching mechanism verbatim; 733if the file is a text file with @code{CR/LF} pairs at the end of each line, 734this will cause some regular expressions to fail. 735This option has no effect 736on platforms other than MS-DOS and MS-Windows. 737 738@item -z 739@itemx --null-data 740@opindex -z 741@opindex --null-data 742@cindex zero-terminated lines 743Treat the input as a set of lines, each terminated by a zero byte (the 744ASCII @code{NUL} character) instead of a newline. 745Like the @option{-Z} or @option{--null} option, 746this option can be used with commands like 747@samp{sort -z} to process arbitrary file names. 748 749@end table 750 751@node Environment Variables 752@section Environment Variables 753 754The behavior of @command{grep} is affected 755by the following environment variables. 756 757The locale for category @w{@code{LC_@var{foo}}} 758is specified by examining the three environment variables 759@env{LC_ALL}, @w{@env{LC_@var{foo}}}, and @env{LANG}, 760in that order. 761The first of these variables that is set specifies the locale. 762For example, if @env{LC_ALL} is not set, 763but @env{LC_MESSAGES} is set to @samp{pt_BR}, 764then the Brazilian Portuguese locale is used 765for the @code{LC_MESSAGES} category. 766The @samp{C} locale is used if none of these environment variables are set, 767if the locale catalog is not installed, 768or if @command{grep} was not compiled 769with national language support (NLS). 770 771Many of the environment variables in the following list let you 772control highlighting using 773Select Graphic Rendition (SGR) 774commands interpreted by the terminal or terminal emulator. 775(See the 776section 777in the documentation of your text terminal 778for permitted values and their meanings as character attributes.) 779These substring values are integers in decimal representation 780and can be concatenated with semicolons. 781@command{grep} takes care of assembling the result 782into a complete SGR sequence (@samp{\33[}...@samp{m}). 783Common values to concatenate include 784@samp{1} for bold, 785@samp{4} for underline, 786@samp{5} for blink, 787@samp{7} for inverse, 788@samp{39} for default foreground color, 789@samp{30} to @samp{37} for foreground colors, 790@samp{90} to @samp{97} for 16-color mode foreground colors, 791@samp{38;5;0} to @samp{38;5;255} 792for 88-color and 256-color modes foreground colors, 793@samp{49} for default background color, 794@samp{40} to @samp{47} for background colors, 795@samp{100} to @samp{107} for 16-color mode background colors, 796and @samp{48;5;0} to @samp{48;5;255} 797for 88-color and 256-color modes background colors. 798 799The two-letter names used in the @env{GREP_COLORS} environment variable 800(and some of the others) refer to terminal ``capabilities,'' the ability 801of a terminal to highlight text, or change its color, and so on. 802These capabilities are stored in an online database and accessed by 803the @code{terminfo} library. 804 805@cindex environment variables 806 807@table @env 808 809@item GREP_OPTIONS 810@vindex GREP_OPTIONS @r{environment variable} 811@cindex default options environment variable 812This variable specifies default options to be placed in front of any 813explicit options. 814For example, if @code{GREP_OPTIONS} is 815@samp{--binary-files=without-match --directories=skip}, @command{grep} 816behaves as if the two options @samp{--binary-files=without-match} and 817@samp{--directories=skip} had been specified before 818any explicit options. 819Option specifications are separated by 820whitespace. 821A backslash escapes the next character, so it can be used to 822specify an option containing whitespace or a backslash. 823 824The @code{GREP_OPTIONS} value does not affect whether @command{grep} 825without file operands searches standard input or the working 826directory; that is affected only by command-line options. For 827example, the command @samp{grep PAT} searches standard input and the 828command @samp{grep -r PAT} searches the working directory, regardless 829of whether @code{GREP_OPTIONS} contains @option{-r}. 830 831@item GREP_COLOR 832@vindex GREP_COLOR @r{environment variable} 833@cindex highlight markers 834This variable specifies the color used to highlight matched (non-empty) text. 835It is deprecated in favor of @env{GREP_COLORS}, but still supported. 836The @samp{mt}, @samp{ms}, and @samp{mc} capabilities of @env{GREP_COLORS} 837have priority over it. 838It can only specify the color used to highlight 839the matching non-empty text in any matching line 840(a selected line when the @option{-v} command-line option is omitted, 841or a context line when @option{-v} is specified). 842The default is @samp{01;31}, 843which means a bold red foreground text on the terminal's default background. 844 845@item GREP_COLORS 846@vindex GREP_COLORS @r{environment variable} 847@cindex highlight markers 848This variable specifies the colors and other attributes 849used to highlight various parts of the output. 850Its value is a colon-separated list of @code{terminfo} capabilities 851that defaults to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36} 852with the @samp{rv} and @samp{ne} boolean capabilities omitted (i.e., false). 853Supported capabilities are as follows. 854 855@table @code 856@item sl= 857@vindex sl GREP_COLORS @r{capability} 858SGR substring for whole selected lines 859(i.e., 860matching lines when the @option{-v} command-line option is omitted, 861or non-matching lines when @option{-v} is specified). 862If however the boolean @samp{rv} capability 863and the @option{-v} command-line option are both specified, 864it applies to context matching lines instead. 865The default is empty (i.e., the terminal's default color pair). 866 867@item cx= 868@vindex cx GREP_COLORS @r{capability} 869SGR substring for whole context lines 870(i.e., 871non-matching lines when the @option{-v} command-line option is omitted, 872or matching lines when @option{-v} is specified). 873If however the boolean @samp{rv} capability 874and the @option{-v} command-line option are both specified, 875it applies to selected non-matching lines instead. 876The default is empty (i.e., the terminal's default color pair). 877 878@item rv 879@vindex rv GREP_COLORS @r{capability} 880Boolean value that reverses (swaps) the meanings of 881the @samp{sl=} and @samp{cx=} capabilities 882when the @option{-v} command-line option is specified. 883The default is false (i.e., the capability is omitted). 884 885@item mt=01;31 886@vindex mt GREP_COLORS @r{capability} 887SGR substring for matching non-empty text in any matching line 888(i.e., 889a selected line when the @option{-v} command-line option is omitted, 890or a context line when @option{-v} is specified). 891Setting this is equivalent to setting both @samp{ms=} and @samp{mc=} 892at once to the same value. 893The default is a bold red text foreground over the current line background. 894 895@item ms=01;31 896@vindex ms GREP_COLORS @r{capability} 897SGR substring for matching non-empty text in a selected line. 898(This is used only when the @option{-v} command-line option is omitted.) 899The effect of the @samp{sl=} (or @samp{cx=} if @samp{rv}) capability 900remains active when this takes effect. 901The default is a bold red text foreground over the current line background. 902 903@item mc=01;31 904@vindex mc GREP_COLORS @r{capability} 905SGR substring for matching non-empty text in a context line. 906(This is used only when the @option{-v} command-line option is specified.) 907The effect of the @samp{cx=} (or @samp{sl=} if @samp{rv}) capability 908remains active when this takes effect. 909The default is a bold red text foreground over the current line background. 910 911@item fn=35 912@vindex fn GREP_COLORS @r{capability} 913SGR substring for file names prefixing any content line. 914The default is a magenta text foreground over the terminal's default background. 915 916@item ln=32 917@vindex ln GREP_COLORS @r{capability} 918SGR substring for line numbers prefixing any content line. 919The default is a green text foreground over the terminal's default background. 920 921@item bn=32 922@vindex bn GREP_COLORS @r{capability} 923SGR substring for byte offsets prefixing any content line. 924The default is a green text foreground over the terminal's default background. 925 926@item se=36 927@vindex fn GREP_COLORS @r{capability} 928SGR substring for separators that are inserted 929between selected line fields (@samp{:}), 930between context line fields (@samp{-}), 931and between groups of adjacent lines 932when nonzero context is specified (@samp{--}). 933The default is a cyan text foreground over the terminal's default background. 934 935@item ne 936@vindex ne GREP_COLORS @r{capability} 937Boolean value that prevents clearing to the end of line 938using Erase in Line (EL) to Right (@samp{\33[K}) 939each time a colorized item ends. 940This is needed on terminals on which EL is not supported. 941It is otherwise useful on terminals 942for which the @code{back_color_erase} 943(@code{bce}) boolean @code{terminfo} capability does not apply, 944when the chosen highlight colors do not affect the background, 945or when EL is too slow or causes too much flicker. 946The default is false (i.e., the capability is omitted). 947@end table 948 949Note that boolean capabilities have no @samp{=}... part. 950They are omitted (i.e., false) by default and become true when specified. 951 952 953@item LC_ALL 954@itemx LC_COLLATE 955@itemx LANG 956@vindex LC_ALL @r{environment variable} 957@vindex LC_COLLATE @r{environment variable} 958@vindex LANG @r{environment variable} 959@cindex character type 960@cindex national language support 961@cindex NLS 962These variables specify the locale for the @code{LC_COLLATE} category, 963which determines the collating sequence 964used to interpret range expressions like @samp{[a-z]}. 965 966@item LC_ALL 967@itemx LC_CTYPE 968@itemx LANG 969@vindex LC_ALL @r{environment variable} 970@vindex LC_CTYPE @r{environment variable} 971@vindex LANG @r{environment variable} 972These variables specify the locale for the @code{LC_CTYPE} category, 973which determines the type of characters, 974e.g., which characters are whitespace. 975 976@item LC_ALL 977@itemx LC_MESSAGES 978@itemx LANG 979@vindex LC_ALL @r{environment variable} 980@vindex LC_MESSAGES @r{environment variable} 981@vindex LANG @r{environment variable} 982@cindex language of messages 983@cindex message language 984@cindex national language support 985@cindex translation of message language 986These variables specify the locale for the @code{LC_MESSAGES} category, 987which determines the language that @command{grep} uses for messages. 988The default @samp{C} locale uses American English messages. 989 990@item POSIXLY_CORRECT 991@vindex POSIXLY_CORRECT @r{environment variable} 992If set, @command{grep} behaves as POSIX requires; otherwise, 993@command{grep} behaves more like other GNU programs. 994POSIX 995requires that options that 996follow file names must be treated as file names; 997by default, 998such options are permuted to the front of the operand list 999and are treated as options. 1000Also, @code{POSIXLY_CORRECT} disables special handling of an 1001invalid bracket expression. @xref{invalid-bracket-expr}. 1002 1003@item _@var{N}_GNU_nonoption_argv_flags_ 1004@vindex _@var{N}_GNU_nonoption_argv_flags_ @r{environment variable} 1005(Here @code{@var{N}} is @command{grep}'s numeric process ID.) 1006If the @var{i}th character of this environment variable's value is @samp{1}, 1007do not consider the @var{i}th operand of @command{grep} to be an option, 1008even if it appears to be one. 1009A shell can put this variable in the environment for each command it runs, 1010specifying which operands are the results of file name wildcard expansion 1011and therefore should not be treated as options. 1012This behavior is available only with the GNU C library, 1013and only when @code{POSIXLY_CORRECT} is not set. 1014 1015@end table 1016 1017 1018@node Exit Status 1019@section Exit Status 1020@cindex exit status 1021@cindex return status 1022 1023Normally, the exit status is 0 if selected lines are found and 1 otherwise. 1024But the exit status is 2 if an error occurred, unless the @option{-q} or 1025@option{--quiet} or @option{--silent} option is used and a selected line 1026is found. 1027Note, however, that POSIX only mandates, 1028for programs such as @command{grep}, @command{cmp}, and @command{diff}, 1029that the exit status in case of error be greater than 1; 1030it is therefore advisable, for the sake of portability, 1031to use logic that tests for this general condition 1032instead of strict equality with@ 2. 1033 1034 1035@node grep Programs 1036@section @command{grep} Programs 1037@cindex @command{grep} programs 1038@cindex variants of @command{grep} 1039 1040@command{grep} searches the named input files 1041for lines containing a match to the given pattern. 1042By default, @command{grep} prints the matching lines. 1043A file named @file{-} stands for standard input. 1044If no input is specified, @command{grep} searches the working 1045directory @file{.} if given a command-line option specifying 1046recursion; otherwise, @command{grep} searches standard input. 1047There are four major variants of @command{grep}, 1048controlled by the following options. 1049 1050@table @option 1051 1052@item -G 1053@itemx --basic-regexp 1054@opindex -G 1055@opindex --basic-regexp 1056@cindex matching basic regular expressions 1057Interpret the pattern as a basic regular expression (BRE). 1058This is the default. 1059 1060@item -E 1061@itemx --extended-regexp 1062@opindex -E 1063@opindex --extended-regexp 1064@cindex matching extended regular expressions 1065Interpret the pattern as an extended regular expression (ERE). 1066(@option{-E} is specified by POSIX.) 1067 1068@item -F 1069@itemx --fixed-strings 1070@opindex -F 1071@opindex --fixed-strings 1072@cindex matching fixed strings 1073Interpret the pattern as a list of fixed strings, separated 1074by newlines, any of which is to be matched. 1075(@option{-F} is specified by POSIX.) 1076 1077@item -P 1078@itemx --perl-regexp 1079@opindex -P 1080@opindex --perl-regexp 1081@cindex matching Perl regular expressions 1082Interpret the pattern as a Perl regular expression. 1083This is highly experimental and 1084@samp{grep@ -P} may warn of unimplemented features. 1085 1086@end table 1087 1088In addition, 1089two variant programs @command{egrep} and @command{fgrep} are available. 1090@command{egrep} is the same as @samp{grep@ -E}. 1091@command{fgrep} is the same as @samp{grep@ -F}. 1092Direct invocation as either 1093@command{egrep} or @command{fgrep} is deprecated, 1094but is provided to allow historical applications 1095that rely on them to run unmodified. 1096 1097 1098@node Regular Expressions 1099@chapter Regular Expressions 1100@cindex regular expressions 1101 1102A @dfn{regular expression} is a pattern that describes a set of strings. 1103Regular expressions are constructed analogously to arithmetic expressions, 1104by using various operators to combine smaller expressions. 1105@command{grep} understands 1106three different versions of regular expression syntax: 1107``basic,'' (BRE) ``extended'' (ERE) and ``perl''. 1108In GNU @command{grep}, 1109there is no difference in available functionality between the basic and 1110extended syntaxes. 1111In other implementations, basic regular expressions are less powerful. 1112The following description applies to extended regular expressions; 1113differences for basic regular expressions are summarized afterwards. 1114Perl regular expressions give additional functionality, and are 1115documented in the @i{pcresyntax}(3) and @i{pcrepattern}(3) manual pages, 1116but may not be available on every system. 1117 1118@menu 1119* Fundamental Structure:: 1120* Character Classes and Bracket Expressions:: 1121* The Backslash Character and Special Expressions:: 1122* Anchoring:: 1123* Back-references and Subexpressions:: 1124* Basic vs Extended:: 1125@end menu 1126 1127@node Fundamental Structure 1128@section Fundamental Structure 1129 1130The fundamental building blocks are the regular expressions that match 1131a single character. 1132Most characters, including all letters and digits, 1133are regular expressions that match themselves. 1134Any meta-character 1135with special meaning may be quoted by preceding it with a backslash. 1136 1137A regular expression may be followed by one of several 1138repetition operators: 1139 1140@table @samp 1141 1142@item . 1143@opindex . 1144@cindex dot 1145@cindex period 1146The period @samp{.} matches any single character. 1147 1148@item ? 1149@opindex ? 1150@cindex question mark 1151@cindex match expression at most once 1152The preceding item is optional and will be matched at most once. 1153 1154@item * 1155@opindex * 1156@cindex asterisk 1157@cindex match expression zero or more times 1158The preceding item will be matched zero or more times. 1159 1160@item + 1161@opindex + 1162@cindex plus sign 1163@cindex match expression one or more times 1164The preceding item will be matched one or more times. 1165 1166@item @{@var{n}@} 1167@opindex @{@var{n}@} 1168@cindex braces, one argument 1169@cindex match expression @var{n} times 1170The preceding item is matched exactly @var{n} times. 1171 1172@item @{@var{n},@} 1173@opindex @{@var{n},@} 1174@cindex braces, second argument omitted 1175@cindex match expression @var{n} or more times 1176The preceding item is matched @var{n} or more times. 1177 1178@item @{,@var{m}@} 1179@opindex @{,@var{m}@} 1180@cindex braces, first argument omitted 1181@cindex match expression at most @var{m} times 1182The preceding item is matched at most @var{m} times. 1183 1184@item @{@var{n},@var{m}@} 1185@opindex @{@var{n},@var{m}@} 1186@cindex braces, two arguments 1187@cindex match expression from @var{n} to @var{m} times 1188The preceding item is matched at least @var{n} times, but not more than 1189@var{m} times. 1190 1191@end table 1192 1193The empty regular expression matches the empty string. 1194Two regular expressions may be concatenated; 1195the resulting regular expression 1196matches any string formed by concatenating two substrings 1197that respectively match the concatenated expressions. 1198 1199Two regular expressions may be joined by the infix operator @samp{|}; 1200the resulting regular expression 1201matches any string matching either alternate expression. 1202 1203Repetition takes precedence over concatenation, 1204which in turn takes precedence over alternation. 1205A whole expression may be enclosed in parentheses 1206to override these precedence rules and form a subexpression. 1207 1208@node Character Classes and Bracket Expressions 1209@section Character Classes and Bracket Expressions 1210 1211@cindex bracket expression 1212@cindex character class 1213A @dfn{bracket expression} is a list of characters enclosed by @samp{[} and 1214@samp{]}. 1215It matches any single character in that list; 1216if the first character of the list is the caret @samp{^}, 1217then it matches any character @strong{not} in the list. 1218For example, the regular expression 1219@samp{[0123456789]} matches any single digit. 1220 1221@cindex range expression 1222Within a bracket expression, a @dfn{range expression} consists of two 1223characters separated by a hyphen. 1224It matches any single character that 1225sorts between the two characters, inclusive, using the locale's 1226collating sequence and character set. 1227For example, in the default C 1228locale, @samp{[a-d]} is equivalent to @samp{[abcd]}. 1229Many locales sort 1230characters in dictionary order, and in these locales @samp{[a-d]} is 1231typically not equivalent to @samp{[abcd]}; 1232it might be equivalent to @samp{[aBbCcDd]}, for example. 1233To obtain the traditional interpretation 1234of bracket expressions, you can use the @samp{C} locale by setting the 1235@env{LC_ALL} environment variable to the value @samp{C}. 1236 1237Finally, certain named classes of characters are predefined within 1238bracket expressions, as follows. 1239Their interpretation depends on the @code{LC_CTYPE} locale; 1240for example, @samp{[[:alnum:]]} means the character class of numbers and letters 1241in the current locale. 1242 1243@cindex classes of characters 1244@cindex character classes 1245@table @samp 1246 1247@item [:alnum:] 1248@opindex alnum @r{character class} 1249@cindex alphanumeric characters 1250Alphanumeric characters: 1251@samp{[:alpha:]} and @samp{[:digit:]}; in the @samp{C} locale and ASCII character encoding, this is the same as @samp{[0-9A-Za-z]}. 1252 1253@item [:alpha:] 1254@opindex alpha @r{character class} 1255@cindex alphabetic characters 1256Alphabetic characters: 1257@samp{[:lower:]} and @samp{[:upper:]}; in the @samp{C} locale and ASCII character encoding, this is the same as @samp{[A-Za-z]}. 1258 1259@item [:blank:] 1260@opindex blank @r{character class} 1261@cindex blank characters 1262Blank characters: 1263space and tab. 1264 1265@item [:cntrl:] 1266@opindex cntrl @r{character class} 1267@cindex control characters 1268Control characters. 1269In ASCII, these characters have octal codes 000 1270through 037, and 177 (@code{DEL}). 1271In other character sets, these are 1272the equivalent characters, if any. 1273 1274@item [:digit:] 1275@opindex digit @r{character class} 1276@cindex digit characters 1277@cindex numeric characters 1278Digits: @code{0 1 2 3 4 5 6 7 8 9}. 1279 1280@item [:graph:] 1281@opindex graph @r{character class} 1282@cindex graphic characters 1283Graphical characters: 1284@samp{[:alnum:]} and @samp{[:punct:]}. 1285 1286@item [:lower:] 1287@opindex lower @r{character class} 1288@cindex lower-case letters 1289Lower-case letters; in the @samp{C} locale and ASCII character 1290encoding, this is 1291@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}. 1292 1293@item [:print:] 1294@opindex print @r{character class} 1295@cindex printable characters 1296Printable characters: 1297@samp{[:alnum:]}, @samp{[:punct:]}, and space. 1298 1299@item [:punct:] 1300@opindex punct @r{character class} 1301@cindex punctuation characters 1302Punctuation characters; in the @samp{C} locale and ASCII character 1303encoding, this is 1304@code{!@: " # $ % & ' ( ) * + , - .@: / : ; < = > ?@: @@ [ \ ] ^ _ ` @{ | @} ~}. 1305 1306@item [:space:] 1307@opindex space @r{character class} 1308@cindex space characters 1309@cindex whitespace characters 1310Space characters: in the @samp{C} locale, this is 1311tab, newline, vertical tab, form feed, carriage return, and space. 1312@xref{Usage}, for more discussion of matching newlines. 1313 1314@item [:upper:] 1315@opindex upper @r{character class} 1316@cindex upper-case letters 1317Upper-case letters: in the @samp{C} locale and ASCII character 1318encoding, this is 1319@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}. 1320 1321@item [:xdigit:] 1322@opindex xdigit @r{character class} 1323@cindex xdigit class 1324@cindex hexadecimal digits 1325Hexadecimal digits: 1326@code{0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f}. 1327 1328@end table 1329Note that the brackets in these class names are 1330part of the symbolic names, and must be included in addition to 1331the brackets delimiting the bracket expression. 1332 1333@anchor{invalid-bracket-expr} 1334If you mistakenly omit the outer brackets, and search for say, @samp{[:upper:]}, 1335GNU @command{grep} prints a diagnostic and exits with status 2, on 1336the assumption that you did not intend to search for the nominally 1337equivalent regular expression: @samp{[:epru]}. 1338Set the @code{POSIXLY_CORRECT} environment variable to disable this feature. 1339 1340Most meta-characters lose their special meaning inside bracket expressions. 1341 1342@table @samp 1343@item ] 1344ends the bracket expression if it's not the first list item. 1345So, if you want to make the @samp{]} character a list item, 1346you must put it first. 1347 1348@item [. 1349represents the open collating symbol. 1350 1351@item .] 1352represents the close collating symbol. 1353 1354@item [= 1355represents the open equivalence class. 1356 1357@item =] 1358represents the close equivalence class. 1359 1360@item [: 1361represents the open character class symbol, and should be followed by a valid character class name. 1362 1363@item :] 1364represents the close character class symbol. 1365 1366@item - 1367represents the range if it's not first or last in a list or the ending point 1368of a range. 1369 1370@item ^ 1371represents the characters not in the list. 1372If you want to make the @samp{^} 1373character a list item, place it anywhere but first. 1374 1375@end table 1376 1377@node The Backslash Character and Special Expressions 1378@section The Backslash Character and Special Expressions 1379@cindex backslash 1380 1381The @samp{\} character, 1382when followed by certain ordinary characters, 1383takes a special meaning: 1384 1385@table @samp 1386 1387@item \b 1388Match the empty string at the edge of a word. 1389 1390@item \B 1391Match the empty string provided it's not at the edge of a word. 1392 1393@item \< 1394Match the empty string at the beginning of word. 1395 1396@item \> 1397Match the empty string at the end of word. 1398 1399@item \w 1400Match word constituent, it is a synonym for @samp{[_[:alnum:]]}. 1401 1402@item \W 1403Match non-word constituent, it is a synonym for @samp{[^_[:alnum:]]}. 1404 1405@item \s 1406Match whitespace, it is a synonym for @samp{[[:space:]]}. 1407 1408@item \S 1409Match non-whitespace, it is a synonym for @samp{[^[:space:]]}. 1410 1411@end table 1412 1413For example, @samp{\brat\b} matches the separate word @samp{rat}, 1414@samp{\Brat\B} matches @samp{crate} but not @samp{furry rat}. 1415 1416@node Anchoring 1417@section Anchoring 1418@cindex anchoring 1419 1420The caret @samp{^} and the dollar sign @samp{$} are meta-characters that 1421respectively match the empty string at the beginning and end of a line. 1422They are termed @dfn{anchors}, since they force the match to be ``anchored'' 1423to beginning or end of a line, respectively. 1424 1425@node Back-references and Subexpressions 1426@section Back-references and Subexpressions 1427@cindex subexpression 1428@cindex back-reference 1429 1430The back-reference @samp{\@var{n}}, where @var{n} is a single digit, matches 1431the substring previously matched by the @var{n}th parenthesized subexpression 1432of the regular expression. 1433For example, @samp{(a)\1} matches @samp{aa}. 1434When used with alternation, if the group does not participate in the match then 1435the back-reference makes the whole match fail. 1436For example, @samp{a(.)|b\1} 1437will not match @samp{ba}. 1438When multiple regular expressions are given with 1439@option{-e} or from a file (@samp{-f @var{file}}), 1440back-references are local to each expression. 1441 1442@node Basic vs Extended 1443@section Basic vs Extended Regular Expressions 1444@cindex basic regular expressions 1445 1446In basic regular expressions the meta-characters @samp{?}, @samp{+}, 1447@samp{@{}, @samp{|}, @samp{(}, and @samp{)} lose their special meaning; 1448instead use the backslashed versions @samp{\?}, @samp{\+}, @samp{\@{}, 1449@samp{\|}, @samp{\(}, and @samp{\)}. 1450 1451@cindex interval specifications 1452Traditional @command{egrep} did not support the @samp{@{} meta-character, 1453and some @command{egrep} implementations support @samp{\@{} instead, so 1454portable scripts should avoid @samp{@{} in @samp{grep@ -E} patterns and 1455should use @samp{[@{]} to match a literal @samp{@{}. 1456 1457GNU @command{grep@ -E} attempts to support traditional usage by 1458assuming that @samp{@{} is not special if it would be the start of an 1459invalid interval specification. 1460For example, the command 1461@samp{grep@ -E@ '@{1'} searches for the two-character string @samp{@{1} 1462instead of reporting a syntax error in the regular expression. 1463POSIX allows this behavior as an extension, but portable scripts 1464should avoid it. 1465 1466 1467@node Usage 1468@chapter Usage 1469 1470@cindex usage, examples 1471Here is an example command that invokes GNU @command{grep}: 1472 1473@example 1474grep -i 'hello.*world' menu.h main.c 1475@end example 1476 1477@noindent 1478This lists all lines in the files @file{menu.h} and @file{main.c} that 1479contain the string @samp{hello} followed by the string @samp{world}; 1480this is because @samp{.*} matches zero or more characters within a line. 1481@xref{Regular Expressions}. 1482The @option{-i} option causes @command{grep} 1483to ignore case, causing it to match the line @samp{Hello, world!}, which 1484it would not otherwise match. 1485@xref{Invoking}, for more details about 1486how to invoke @command{grep}. 1487 1488@cindex using @command{grep}, Q&A 1489@cindex FAQ about @command{grep} usage 1490Here are some common questions and answers about @command{grep} usage. 1491 1492@enumerate 1493 1494@item 1495How can I list just the names of matching files? 1496 1497@example 1498grep -l 'main' *.c 1499@end example 1500 1501@noindent 1502lists the names of all C files in the current directory whose contents 1503mention @samp{main}. 1504 1505@item 1506How do I search directories recursively? 1507 1508@example 1509grep -r 'hello' /home/gigi 1510@end example 1511 1512@noindent 1513searches for @samp{hello} in all files 1514under the @file{/home/gigi} directory. 1515For more control over which files are searched, 1516use @command{find}, @command{grep}, and @command{xargs}. 1517For example, the following command searches only C files: 1518 1519@example 1520find /home/gigi -name '*.c' -print0 | xargs -0r grep -H 'hello' 1521@end example 1522 1523This differs from the command: 1524 1525@example 1526grep -H 'hello' *.c 1527@end example 1528 1529which merely looks for @samp{hello} in all files in the current 1530directory whose names end in @samp{.c}. 1531The @samp{find ...} command line above is more similar to the command: 1532 1533@example 1534grep -rH --include='*.c' 'hello' /home/gigi 1535@end example 1536 1537@item 1538What if a pattern has a leading @samp{-}? 1539 1540@example 1541grep -e '--cut here--' * 1542@end example 1543 1544@noindent 1545searches for all lines matching @samp{--cut here--}. 1546Without @option{-e}, 1547@command{grep} would attempt to parse @samp{--cut here--} as a list of 1548options. 1549 1550@item 1551Suppose I want to search for a whole word, not a part of a word? 1552 1553@example 1554grep -w 'hello' * 1555@end example 1556 1557@noindent 1558searches only for instances of @samp{hello} that are entire words; 1559it does not match @samp{Othello}. 1560For more control, use @samp{\<} and 1561@samp{\>} to match the start and end of words. 1562For example: 1563 1564@example 1565grep 'hello\>' * 1566@end example 1567 1568@noindent 1569searches only for words ending in @samp{hello}, so it matches the word 1570@samp{Othello}. 1571 1572@item 1573How do I output context around the matching lines? 1574 1575@example 1576grep -C 2 'hello' * 1577@end example 1578 1579@noindent 1580prints two lines of context around each matching line. 1581 1582@item 1583How do I force @command{grep} to print the name of the file? 1584 1585Append @file{/dev/null}: 1586 1587@example 1588grep 'eli' /etc/passwd /dev/null 1589@end example 1590 1591gets you: 1592 1593@example 1594/etc/passwd:eli:x:2098:1000:Eli Smith:/home/eli:/bin/bash 1595@end example 1596 1597Alternatively, use @option{-H}, which is a GNU extension: 1598 1599@example 1600grep -H 'eli' /etc/passwd 1601@end example 1602 1603@item 1604Why do people use strange regular expressions on @command{ps} output? 1605 1606@example 1607ps -ef | grep '[c]ron' 1608@end example 1609 1610If the pattern had been written without the square brackets, it would 1611have matched not only the @command{ps} output line for @command{cron}, 1612but also the @command{ps} output line for @command{grep}. 1613Note that on some platforms, 1614@command{ps} limits the output to the width of the screen; 1615@command{grep} does not have any limit on the length of a line 1616except the available memory. 1617 1618@item 1619Why does @command{grep} report ``Binary file matches''? 1620 1621If @command{grep} listed all matching ``lines'' from a binary file, it 1622would probably generate output that is not useful, and it might even 1623muck up your display. 1624So GNU @command{grep} suppresses output from 1625files that appear to be binary files. 1626To force GNU @command{grep} 1627to output lines even from files that appear to be binary, use the 1628@option{-a} or @samp{--binary-files=text} option. 1629To eliminate the 1630``Binary file matches'' messages, use the @option{-I} or 1631@samp{--binary-files=without-match} option. 1632 1633@item 1634Why doesn't @samp{grep -lv} print non-matching file names? 1635 1636@samp{grep -lv} lists the names of all files containing one or more 1637lines that do not match. 1638To list the names of all files that contain no 1639matching lines, use the @option{-L} or @option{--files-without-match} 1640option. 1641 1642@item 1643I can do ``OR'' with @samp{|}, but what about ``AND''? 1644 1645@example 1646grep 'paul' /etc/motd | grep 'franc,ois' 1647@end example 1648 1649@noindent 1650finds all lines that contain both @samp{paul} and @samp{franc,ois}. 1651 1652@item 1653Why does the empty pattern match every input line? 1654 1655The @command{grep} command searches for lines that contain strings 1656that match a pattern. Every line contains the empty string, so an 1657empty pattern causes @command{grep} to find a match on each line. It 1658is not the only such pattern: @samp{^}, @samp{$}, @samp{.*}, and many 1659other patterns cause @command{grep} to match every line. 1660 1661To match empty lines, use the pattern @samp{^$}. To match blank 1662lines, use the pattern @samp{^[[:blank:]]*$}. To match no lines at 1663all, use the command @samp{grep -f /dev/null}. 1664 1665@item 1666How can I search in both standard input and in files? 1667 1668Use the special file name @samp{-}: 1669 1670@example 1671cat /etc/passwd | grep 'alain' - /etc/motd 1672@end example 1673 1674@item 1675@cindex palindromes 1676How to express palindromes in a regular expression? 1677 1678It can be done by using back-references; 1679for example, 1680a palindrome of 4 characters can be written with a BRE: 1681 1682@example 1683grep -w -e '\(.\)\(.\).\2\1' file 1684@end example 1685 1686It matches the word ``radar'' or ``civic.'' 1687 1688Guglielmo Bondioni proposed a single RE 1689that finds all palindromes up to 19 characters long 1690using @w{9 subexpressions} and @w{9 back-references}: 1691 1692@smallexample 1693grep -E -e '^(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?).?\9\8\7\6\5\4\3\2\1$' file 1694@end smallexample 1695 1696Note this is done by using GNU ERE extensions; 1697it might not be portable to other implementations of @command{grep}. 1698 1699@item 1700Why is this back-reference failing? 1701 1702@example 1703echo 'ba' | grep -E '(a)\1|b\1' 1704@end example 1705 1706This gives no output, because the first alternate @samp{(a)\1} does not match, 1707as there is no @samp{aa} in the input, so the @samp{\1} in the second alternate 1708has nothing to refer back to, meaning it will never match anything. 1709(The second alternate in this example can only match 1710if the first alternate has matched---making the second one superfluous.) 1711 1712@item 1713How can I match across lines? 1714 1715Standard grep cannot do this, as it is fundamentally line-based. 1716Therefore, merely using the @code{[:space:]} character class does not 1717match newlines in the way you might expect. However, if your grep is 1718compiled with Perl patterns enabled, the Perl @samp{s} 1719modifier (which makes @code{.} match newlines) can be used: 1720 1721@example 1722printf 'foo\nbar\n' | grep -P '(?s)foo.*?bar' 1723@end example 1724 1725With the GNU @command{grep} option @code{-z} (@pxref{File and 1726Directory Selection}), the input is terminated by null bytes. Thus, 1727you can match newlines in the input, but the output will be the whole 1728file, so this is really only useful to determine if the pattern is 1729present: 1730 1731@example 1732printf 'foo\nbar\n' | grep -z -q 'foo[[:space:]]\+bar' 1733@end example 1734 1735Failing either of those options, you need to transform the input 1736before giving it to @command{grep}, or turn to @command{awk}, 1737@command{sed}, @command{perl}, or many other utilities that are 1738designed to operate across lines. 1739 1740@item 1741What do @command{grep}, @command{fgrep}, and @command{egrep} stand for? 1742 1743The name @command{grep} comes from the way line editing was done on Unix. 1744For example, 1745@command{ed} uses the following syntax 1746to print a list of matching lines on the screen: 1747 1748@example 1749global/regular expression/print 1750g/re/p 1751@end example 1752 1753@command{fgrep} stands for Fixed @command{grep}; 1754@command{egrep} stands for Extended @command{grep}. 1755 1756@end enumerate 1757 1758 1759@node Reporting Bugs 1760@chapter Reporting bugs 1761 1762@cindex bugs, reporting 1763Email bug reports to @email{bug-grep@@gnu.org}, 1764a mailing list whose web page is 1765@url{http://lists.gnu.org/mailman/listinfo/bug-grep}. 1766The Savannah bug tracker for @command{grep} is located at 1767@url{http://savannah.gnu.org/bugs/?group=grep}. 1768 1769@section Known Bugs 1770@cindex Bugs, known 1771 1772Large repetition counts in the @samp{@{n,m@}} construct may cause 1773@command{grep} to use lots of memory. 1774In addition, certain other 1775obscure regular expressions require exponential time and 1776space, and may cause @command{grep} to run out of memory. 1777 1778Back-references are very slow, and may require exponential time. 1779 1780 1781@node Copying 1782@chapter Copying 1783@cindex copying 1784 1785GNU @command{grep} is licensed under the GNU GPL, which makes it @dfn{free 1786software}. 1787 1788The ``free'' in ``free software'' refers to liberty, not price. As 1789some GNU project advocates like to point out, think of ``free speech'' 1790rather than ``free beer''. In short, you have the right (freedom) to 1791run and change @command{grep} and distribute it to other people, and---if you 1792want---charge money for doing either. The important restriction is 1793that you have to grant your recipients the same rights and impose the 1794same restrictions. 1795 1796This general method of licensing software is sometimes called 1797@dfn{open source}. The GNU project prefers the term ``free software'' 1798for reasons outlined at 1799@url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}. 1800 1801This manual is free documentation in the same sense. The 1802documentation license is included below. The license for the program 1803is available with the source code, or at 1804@url{http://www.gnu.org/licenses/gpl.html}. 1805 1806@menu 1807* GNU Free Documentation License:: 1808@end menu 1809 1810@node GNU Free Documentation License 1811@section GNU Free Documentation License 1812 1813@include fdl.texi 1814 1815 1816@node Index 1817@unnumbered Index 1818 1819@printindex cp 1820 1821@bye 1822