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