Debian Codegraph @

upstream/debian-trixie/man1/grep.1

raw
1 .\" GNU grep man page
2 .de dT
3 .ds Dt \\$2
4 ..
5 .dT Time-stamp: "2019-12-29"
6 .\" Update the above date whenever a change to either this file or
7 .\" grep.c's 'usage' function results in a nontrivial change to the man page.
8 .\" In Emacs, you can update the date by running 'M-x time-stamp'
9 .\" after you make a change that you decide is nontrivial.
10 .\" It is no big deal to forget to update the date.
11 .
12 .TH GREP 1 \*(Dt "GNU grep 3.11" "User Commands"
13 .
14 .if !\w|\*(lq| \{\
15 .\" groff an-old.tmac does not seem to be in use, so define lq and rq.
16 . ie \n(.g \{\
17 . ds lq \(lq\"
18 . ds rq \(rq\"
19 . \}
20 . el \{\
21 . ds lq ``
22 . ds rq ''
23 . \}
24 .\}
25 .
26 .if !\w|\*(la| \{\
27 .\" groff an-ext.tmac does not seem to be in use, so define the parts of
28 .\" it that are used below. For a copy of groff an-ext.tmac, please see:
29 .\" https://git.savannah.gnu.org/cgit/groff.git/plain/tmac/an-ext.tmac
30 .\" --- Start of lines taken from groff an-ext.tmac
31 .
32 .\" Check whether we are using grohtml.
33 .nr mH 0
34 .if \n(.g \
35 . if '\*(.T'html' \
36 . nr mH 1
37 .
38 .
39 .\" Map mono-width fonts to standard fonts for groff's TTY device.
40 .if n \{\
41 . do ftr CR R
42 . do ftr CI I
43 . do ftr CB B
44 .\}
45 .
46 .\" groff has glyph entities for angle brackets.
47 .ie \n(.g \{\
48 . ds la \(la\"
49 . ds ra \(ra\"
50 .\}
51 .el \{\
52 . ds la <\"
53 . ds ra >\"
54 . \" groff's man macros control hyphenation with this register.
55 . nr HY 1
56 .\}
57 .
58 .\" Start URL.
59 .de UR
60 . ds m1 \\$1\"
61 . nh
62 . if \\n(mH \{\
63 . \" Start diversion in a new environment.
64 . do ev URL-div
65 . do di URL-div
66 . \}
67 ..
68 .
69 .
70 .\" End URL.
71 .de UE
72 . ie \\n(mH \{\
73 . br
74 . di
75 . ev
76 .
77 . \" Has there been one or more input lines for the link text?
78 . ie \\n(dn \{\
79 . do HTML-NS "<a href=""\\*(m1"">"
80 . \" Yes, strip off final newline of diversion and emit it.
81 . do chop URL-div
82 . do URL-div
83 \c
84 . do HTML-NS </a>
85 . \}
86 . el \
87 . do HTML-NS "<a href=""\\*(m1"">\\*(m1</a>"
88 \&\\$*\"
89 . \}
90 . el \
91 \\*(la\\*(m1\\*(ra\\$*\"
92 .
93 . hy \\n(HY
94 ..
95 .
96 .
97 .\" Start email address.
98 .de MT
99 . ds m1 \\$1\"
100 . nh
101 . if \\n(mH \{\
102 . \" Start diversion in a new environment.
103 . do ev URL-div
104 . do di URL-div
105 . \}
106 ..
107 .
108 .
109 .\" End email address.
110 .de ME
111 . ie \\n(mH \{\
112 . br
113 . di
114 . ev
115 .
116 . \" Has there been one or more input lines for the link text?
117 . ie \\n(dn \{\
118 . do HTML-NS "<a href=""mailto:\\*(m1"">"
119 . \" Yes, strip off final newline of diversion and emit it.
120 . do chop URL-div
121 . do URL-div
122 \c
123 . do HTML-NS </a>
124 . \}
125 . el \
126 . do HTML-NS "<a href=""mailto:\\*(m1"">\\*(m1</a>"
127 \&\\$*\"
128 . \}
129 . el \
130 \\*(la\\*(m1\\*(ra\\$*\"
131 .
132 . hy \\n(HY
133 ..
134 .\" --- End of lines taken from groff an-ext.tmac
135 .\}
136 .
137 .hy 0
138 .
139 .SH NAME
140 grep, egrep, fgrep, rgrep \- print lines that match patterns
141 .
142 .SH SYNOPSIS
143 .B grep
144 .RI [ OPTION .\|.\|.]\&
145 .I PATTERNS
146 .RI [ FILE .\|.\|.]
147 .br
148 .B grep
149 .RI [ OPTION .\|.\|.]\&
150 .B \-e
151 .I PATTERNS
152 \&.\|.\|.\&
153 .RI [ FILE .\|.\|.]
154 .br
155 .B grep
156 .RI [ OPTION .\|.\|.]\&
157 .B \-f
158 .I PATTERN_FILE
159 \&.\|.\|.\&
160 .RI [ FILE .\|.\|.]
161 .
162 .SH DESCRIPTION
163 .B grep
164 searches for
165 .I PATTERNS
166 in each
167 .IR FILE .
168 .I PATTERNS
169 is one or more patterns separated by newline characters, and
170 .B grep
171 prints each line that matches a pattern.
172 Typically
173 .I PATTERNS
174 should be quoted when
175 .B grep
176 is used in a shell command.
177 .PP
178 A
179 .I FILE
180 of
181 .RB "\*(lq" \- "\*(rq"
182 stands for standard input.
183 If no
184 .I FILE
185 is given, recursive searches examine the working directory,
186 and nonrecursive searches read standard input.
187 .PP
188 Debian also includes the variant programs
189 .BR egrep ,
190 .B fgrep
191 and
192 .BR rgrep .
193 These programs are the same as
194 .BR "grep\ \-E" ,
195 .BR "grep\ \-F" ,
196 and
197 .BR "grep\ \-r" ,
198 respectively.
199 These variants are deprecated upstream, but Debian provides for backward
200 compatibility. For portability reasons, it is recommended to avoid the variant
201 programs, and use
202 .B grep
203 with the related option instead.
204 .
205 .SH OPTIONS
206 .SS "Generic Program Information"
207 .TP
208 .B \-\^\-help
209 Output a usage message and exit.
210 .TP
211 .BR \-V ", " \-\^\-version
212 Output the version number of
213 .B grep
214 and exit.
215 .SS "Pattern Syntax"
216 .TP
217 .BR \-E ", " \-\^\-extended\-regexp
218 Interpret
219 .I PATTERNS
220 as extended regular expressions (EREs, see below).
221 .TP
222 .BR \-F ", " \-\^\-fixed\-strings
223 Interpret
224 .I PATTERNS
225 as fixed strings, not regular expressions.
226 .TP
227 .BR \-G ", " \-\^\-basic\-regexp
228 Interpret
229 .I PATTERNS
230 as basic regular expressions (BREs, see below).
231 This is the default.
232 .TP
233 .BR \-P ", " \-\^\-perl\-regexp
234 Interpret
235 .I PATTERNS
236 as Perl-compatible regular expressions (PCREs).
237 This option is experimental when combined with the
238 .B \-z
239 .RB ( \-\^\-null\-data )
240 option, and
241 .B "grep \-P"
242 may warn of unimplemented features.
243 .SS "Matching Control"
244 .TP
245 .BI \-e " PATTERNS" "\fR,\fP \-\^\-regexp=" PATTERNS
246 Use
247 .I PATTERNS
248 as the patterns.
249 If this option is used multiple times or is combined with the
250 .B \-f
251 .RB ( \-\^\-file )
252 option, search for all patterns given.
253 This option can be used to protect a pattern beginning with \*(lq\-\*(rq.
254 .TP
255 .BI \-f " FILE" "\fR,\fP \-\^\-file=" FILE
256 Obtain patterns from
257 .IR FILE ,
258 one per line.
259 If this option is used multiple times or is combined with the
260 .B \-e
261 .RB ( \-\^\-regexp )
262 option, search for all patterns given.
263 The empty file contains zero patterns, and therefore matches nothing.
264 If
265 .IR FILE
266 is
267 .B \-
268 , read patterns from standard input.
269 .TP
270 .BR \-i ", " \-\^\-ignore\-case
271 Ignore case distinctions in patterns and input data,
272 so that characters that differ only in case
273 match each other.
274 .TP
275 .B \-\^\-no\-ignore\-case
276 Do not ignore case distinctions in patterns and input data.
277 This is the default.
278 This option is useful for passing to shell scripts that already use
279 .BR \-i ,
280 to cancel its effects because the two options override each other.
281 .TP
282 .BR \-v ", " \-\^\-invert\-match
283 Invert the sense of matching, to select non-matching lines.
284 .TP
285 .BR \-w ", " \-\^\-word\-regexp
286 Select only those lines containing matches that form whole words.
287 The test is that the matching substring must either be at the
288 beginning of the line, or preceded by a non-word constituent
289 character.
290 Similarly, it must be either at the end of the line
291 or followed by a non-word constituent character.
292 Word-constituent characters are letters, digits, and the underscore.
293 This option has no effect if
294 .B \-x
295 is also specified.
296 .TP
297 .BR \-x ", " \-\^\-line\-regexp
298 Select only those matches that exactly match the whole line.
299 For a regular expression pattern, this is like parenthesizing the
300 pattern and then surrounding it with
301 .B ^
302 and
303 .BR $ .
304 .SS "General Output Control"
305 .TP
306 .BR \-c ", " \-\^\-count
307 Suppress normal output; instead print a count of
308 matching lines for each input file.
309 With the
310 .BR \-v ", " \-\^\-invert\-match
311 option (see above), count non-matching lines.
312 .TP
313 .BR \-\^\-color [ =\fIWHEN\fP "], " \-\^\-colour [ =\fIWHEN\fP ]
314 Surround the matched (non-empty) strings, matching lines, context lines,
315 file names, line numbers, byte offsets, and separators (for fields and
316 groups of context lines) with escape sequences to display them in color
317 on the terminal.
318 The colors are defined by the environment variable
319 .BR GREP_COLORS .
320 .I WHEN
321 is
322 .BR never ", " always ", or " auto .
323 .TP
324 .BR \-L ", " \-\^\-files\-without\-match
325 Suppress normal output; instead print the name
326 of each input file from which no output would
327 normally have been printed.
328 .TP
329 .BR \-l ", " \-\^\-files\-with\-matches
330 Suppress normal output; instead print
331 the name of each input file from which output
332 would normally have been printed.
333 Scanning each input file stops upon first match.
334 .TP
335 .BI \-m " NUM" "\fR,\fP \-\^\-max\-count=" NUM
336 Stop reading a file after
337 .I NUM
338 matching lines.
339 If
340 .I NUM
341 is zero,
342 .B grep
343 stops right away without reading input.
344 A
345 .I NUM
346 of \-1 is treated as infinity and
347 .B grep
348 does not stop; this is the default.
349 If the input is standard input from a regular file,
350 and
351 .I NUM
352 matching lines are output,
353 .B grep
354 ensures that the standard input is positioned to just after the last
355 matching line before exiting, regardless of the presence of trailing
356 context lines.
357 This enables a calling process to resume a search.
358 When
359 .B grep
360 stops after
361 .I NUM
362 matching lines, it outputs any trailing context lines.
363 When the
364 .B \-c
365 or
366 .B \-\^\-count
367 option is also used,
368 .B grep
369 does not output a count greater than
370 .IR NUM .
371 When the
372 .B \-v
373 or
374 .B \-\^\-invert\-match
375 option is also used,
376 .B grep
377 stops after outputting
378 .I NUM
379 non-matching lines.
380 .TP
381 .BR \-o ", " \-\^\-only\-matching
382 Print only the matched (non-empty) parts of a matching line,
383 with each such part on a separate output line.
384 .TP
385 .BR \-q ", " \-\^\-quiet ", " \-\^\-silent
386 Quiet; do not write anything to standard output.
387 Exit immediately with zero status if any match is found,
388 even if an error was detected.
389 Also see the
390 .B \-s
391 or
392 .B \-\^\-no\-messages
393 option.
394 .TP
395 .BR \-s ", " \-\^\-no\-messages
396 Suppress error messages about nonexistent or unreadable files.
397 .SS "Output Line Prefix Control"
398 .TP
399 .BR \-b ", " \-\^\-byte\-offset
400 Print the 0-based byte offset within the input file
401 before each line of output.
402 If
403 .B \-o
404 .RB ( \-\^\-only\-matching )
405 is specified,
406 print the offset of the matching part itself.
407 .TP
408 .BR \-H ", " \-\^\-with\-filename
409 Print the file name for each match.
410 This is the default when there is more than one file to search.
411 This is a GNU extension.
412 .TP
413 .BR \-h ", " \-\^\-no\-filename
414 Suppress the prefixing of file names on output.
415 This is the default when there is only one file
416 (or only standard input) to search.
417 .TP
418 .BI \-\^\-label= LABEL
419 Display input actually coming from standard input as input coming from file
420 .IR LABEL .
421 This can be useful for commands that transform a file's contents
422 before searching,
423 e.g.,
424 .BR "gzip \-cd foo.gz | grep \-\^\-label=foo \-H 'some pattern'" .
425 See also the
426 .B \-H
427 option.
428 .TP
429 .BR \-n ", " \-\^\-line\-number
430 Prefix each line of output with the 1-based line number
431 within its input file.
432 .TP
433 .BR \-T ", " \-\^\-initial\-tab
434 Make sure that the first character of actual line content lies on a
435 tab stop, so that the alignment of tabs looks normal.
436 This is useful with options that prefix their output to the actual content:
437 .BR \-H , \-n ,
438 and
439 .BR \-b .
440 In order to improve the probability that lines
441 from a single file will all start at the same column,
442 this also causes the line number and byte offset (if present)
443 to be printed in a minimum size field width.
444 .TP
445 .BR \-Z ", " \-\^\-null
446 Output a zero byte (the ASCII
447 .B NUL
448 character) instead of the character that normally follows a file name.
449 For example,
450 .B "grep \-lZ"
451 outputs a zero byte after each file name instead of the usual newline.
452 This option makes the output unambiguous, even in the presence of file
453 names containing unusual characters like newlines.
454 This option can be used with commands like
455 .BR "find \-print0" ,
456 .BR "perl \-0" ,
457 .BR "sort \-z" ,
458 and
459 .B "xargs \-0"
460 to process arbitrary file names,
461 even those that contain newline characters.
462 .SS "Context Line Control"
463 .TP
464 .BI \-A " NUM" "\fR,\fP \-\^\-after\-context=" NUM
465 Print
466 .I NUM
467 lines of trailing context after matching lines.
468 Places a line containing a group separator
469 .RB ( \-\^\- )
470 between contiguous groups of matches.
471 With the
472 .B \-o
473 or
474 .B \-\^\-only\-matching
475 option, this has no effect and a warning is given.
476 .TP
477 .BI \-B " NUM" "\fR,\fP \-\^\-before\-context=" NUM
478 Print
479 .I NUM
480 lines of leading context before matching lines.
481 Places a line containing a group separator
482 .RB ( \-\^\- )
483 between contiguous groups of matches.
484 With the
485 .B \-o
486 or
487 .B \-\^\-only\-matching
488 option, this has no effect and a warning is given.
489 .TP
490 .BI \-C " NUM" "\fR,\fP \-" NUM "\fR,\fP \-\^\-context=" NUM
491 Print
492 .I NUM
493 lines of output context.
494 Places a line containing a group separator
495 .RB ( \-\^\- )
496 between contiguous groups of matches.
497 With the
498 .B \-o
499 or
500 .B \-\^\-only\-matching
501 option, this has no effect and a warning is given.
502 .TP
503 .BI \-\^\-group\-separator= SEP
504 When
505 .BR \-A ,
506 .BR \-B ,
507 or
508 .B \-C
509 are in use, print
510 .I SEP
511 instead of
512 .B \-\^\-
513 between groups of lines.
514 .TP
515 .B \-\^\-no\-group\-separator
516 When
517 .BR \-A ,
518 .BR \-B ,
519 or
520 .B \-C
521 are in use, do not print a separator between groups of lines.
522 .SS "File and Directory Selection"
523 .TP
524 .BR \-a ", " \-\^\-text
525 Process a binary file as if it were text; this is equivalent to the
526 .B \-\^\-binary\-files=text
527 option.
528 .TP
529 .BI \-\^\-binary\-files= TYPE
530 If a file's data or metadata
531 indicate that the file contains binary data,
532 assume that the file is of type
533 .IR TYPE .
534 Non-text bytes indicate binary data; these are either output bytes that are
535 improperly encoded for the current locale, or null input bytes when the
536 .B \-z
537 option is not given.
538 .IP
539 By default,
540 .I TYPE
541 is
542 .BR binary ,
543 and
544 .B grep
545 suppresses output after null input binary data is discovered,
546 and suppresses output lines that contain improperly encoded data.
547 When some output is suppressed,
548 .B grep
549 follows any output
550 with a message to standard error saying that a binary file matches.
551 .IP
552 If
553 .I TYPE
554 is
555 .BR without\-match ,
556 when
557 .B grep
558 discovers null input binary data it assumes that the rest of the file
559 does not match; this is equivalent to the
560 .B \-I
561 option.
562 .IP
563 If
564 .I TYPE
565 is
566 .BR text ,
567 .B grep
568 processes a binary file as if it were text; this is equivalent to the
569 .B \-a
570 option.
571 .IP
572 When
573 .I type
574 is
575 .BR binary ,
576 .B grep
577 may treat non-text bytes as line terminators even without the
578 .B \-z
579 option. This means choosing
580 .B binary
581 versus
582 .B text
583 can affect whether a pattern matches a file. For
584 example, when
585 .I type
586 is
587 .B binary
588 the pattern
589 .B q$ might
590 match
591 .B q
592 immediately followed by a null byte, even though this
593 is not matched when
594 .I type
595 is
596 .BR text .
597 Conversely, when
598 .I type
599 is
600 .B binary
601 the pattern
602 .B .\&
603 (period) might not match a null byte.
604 .IP
605 .I Warning:
606 The
607 .B \-a
608 option might output binary garbage,
609 which can have nasty side effects if the output is a terminal and if the
610 terminal driver interprets some of it as commands.
611 On the other hand, when reading files whose text encodings are
612 unknown, it can be helpful to use
613 .B \-a
614 or to set
615 .B LC_ALL='C'
616 in the environment, in order to find more matches even if the matches
617 are unsafe for direct display.
618 .TP
619 .BI \-D " ACTION" "\fR,\fP \-\^\-devices=" ACTION
620 If an input file is a device, FIFO or socket, use
621 .I ACTION
622 to process it.
623 By default,
624 .I ACTION
625 is
626 .BR read ,
627 which means that devices are read just as if they were ordinary files.
628 If
629 .I ACTION
630 is
631 .BR skip ,
632 devices are silently skipped.
633 .TP
634 .BI \-d " ACTION" "\fR,\fP \-\^\-directories=" ACTION
635 If an input file is a directory, use
636 .I ACTION
637 to process it.
638 By default,
639 .I ACTION
640 is
641 .BR read ,
642 i.e., read directories just as if they were ordinary files.
643 If
644 .I ACTION
645 is
646 .BR skip ,
647 silently skip directories.
648 If
649 .I ACTION
650 is
651 .BR recurse ,
652 read all files under each directory, recursively,
653 following symbolic links only if they are on the command line.
654 This is equivalent to the
655 .B \-r
656 option.
657 .TP
658 .BI \-\^\-exclude= GLOB
659 Skip any command-line file with a name suffix that matches the pattern
660 .IR GLOB ,
661 using wildcard matching; a name suffix is either the whole
662 name, or a trailing part that starts with a non-slash character
663 immediately after a slash
664 .RB ( / )
665 in the name.
666 When searching recursively, skip any subfile whose base name matches
667 .IR GLOB ;
668 the base name is the part after the last slash.
669 A pattern can use
670 .BR * ,
671 .BR ? ,
672 and
673 .BR [ .\|.\|. ]\&
674 as wildcards, and
675 .B \e
676 to quote a wildcard or backslash character literally.
677 .TP
678 .BI \-\^\-exclude\-from= FILE
679 Skip files whose base name matches any of the file-name globs read from
680 .I FILE
681 (using wildcard matching as described under
682 .BR \-\^\-exclude ).
683 .TP
684 .BI \-\^\-exclude\-dir= GLOB
685 Skip any command-line directory with a name suffix that matches the
686 pattern
687 .IR GLOB .
688 When searching recursively, skip any subdirectory
689 whose base name matches
690 .IR GLOB .
691 Ignore any redundant trailing slashes in
692 .IR GLOB .
693 .TP
694 .BR \-I
695 Process a binary file as if it did not contain matching data; this is
696 equivalent to the
697 .B \-\^\-binary\-files=without\-match
698 option.
699 .TP
700 .BI \-\^\-include= GLOB
701 Search only files whose base name matches
702 .I GLOB
703 (using wildcard matching as described under
704 .BR \-\^\-exclude ).
705 If contradictory
706 .B \-\^\-include
707 and
708 .B \-\^\-exclude
709 options are given, the last matching one wins.
710 If no
711 .B \-\^\-include
712 or
713 .B \-\^\-exclude
714 options match, a file is included unless the first such option is
715 .BR \-\^\-include .
716 .TP
717 .BR \-r ", " \-\^\-recursive
718 Read all files under each directory, recursively,
719 following symbolic links only if they are on the command line.
720 Note that if no file operand is given,
721 .B grep
722 searches the working directory.
723 This is equivalent to the
724 .B "\-d recurse"
725 option.
726 .TP
727 .BR \-R ", " \-\^\-dereference\-recursive
728 Read all files under each directory, recursively.
729 Follow all symbolic links, unlike
730 .BR \-r .
731 .SS "Other Options"
732 .TP
733 .B \-\^\-line\-buffered
734 Use line buffering on output.
735 This can cause a performance penalty.
736 .TP
737 .BR \-U ", " \-\^\-binary
738 Treat the file(s) as binary.
739 By default, under MS-DOS and MS-Windows,
740 .B grep
741 guesses whether a file is text or binary as described for the
742 .B \-\^\-binary\-files
743 option.
744 If
745 .B grep
746 decides the file is a text file, it strips the CR characters from the
747 original file contents (to make regular expressions with
748 .B ^
749 and
750 .B $
751 work correctly).
752 Specifying
753 .B \-U
754 overrules this guesswork, causing all files to be read and passed to the
755 matching mechanism verbatim; if the file is a text file with CR/LF
756 pairs at the end of each line, this will cause some regular
757 expressions to fail.
758 This option has no effect on platforms
759 other than MS-DOS and MS-Windows.
760 .TP
761 .BR \-z ", " \-\^\-null\-data
762 Treat input and output data as sequences of lines, each terminated by
763 a zero byte (the ASCII NUL character) instead of a newline.
764 Like the
765 .B \-Z
766 or
767 .B \-\^\-null
768 option, this option can be used with commands like
769 .B sort -z
770 to process arbitrary file names.
771 .
772 .SH "REGULAR EXPRESSIONS"
773 A regular expression is a pattern that describes a set of strings.
774 Regular expressions are constructed analogously to arithmetic
775 expressions, by using various operators to combine smaller expressions.
776 .PP
777 .B grep
778 understands three different versions of regular expression syntax:
779 \*(lqbasic\*(rq (BRE), \*(lqextended\*(rq (ERE) and \*(lqperl\*(rq (PCRE).
780 In GNU
781 .BR grep ,
782 basic and extended regular expressions are merely different notations
783 for the same pattern-matching functionality.
784 In other implementations, basic regular expressions are ordinarily
785 less powerful than extended, though occasionally it is the other way around.
786 The following description applies to extended regular expressions;
787 differences for basic regular expressions are summarized afterwards.
788 Perl-compatible regular expressions have different functionality, and are
789 documented in
790 .BR pcre2syntax (3)
791 and
792 .BR pcre2pattern (3),
793 but work only if PCRE support is enabled.
794 .PP
795 The fundamental building blocks are the regular expressions
796 that match a single character.
797 Most characters, including all letters and digits,
798 are regular expressions that match themselves.
799 Any meta-character with special meaning
800 may be quoted by preceding it with a backslash.
801 .PP
802 The period
803 .B .\&
804 matches any single character.
805 It is unspecified whether it matches an encoding error.
806 .SS "Character Classes and Bracket Expressions"
807 A
808 .I "bracket expression"
809 is a list of characters enclosed by
810 .B [
811 and
812 .BR ] .
813 It matches any single
814 character in that list.
815 If the first character of the list
816 is the caret
817 .B ^
818 then it matches any character
819 .I not
820 in the list; it is unspecified whether it matches an encoding error.
821 For example, the regular expression
822 .B [0123456789]
823 matches any single digit.
824 .PP
825 Within a bracket expression, a
826 .I "range expression"
827 consists of two characters separated by a hyphen.
828 It matches any single character that sorts between the two characters,
829 inclusive, using the locale's collating sequence and character set.
830 For example, in the default C locale,
831 .B [a\-d]
832 is equivalent to
833 .BR [abcd] .
834 Many locales sort characters in dictionary order, and in these locales
835 .B [a\-d]
836 is typically not equivalent to
837 .BR [abcd] ;
838 it might be equivalent to
839 .BR [aBbCcDd] ,
840 for example.
841 To obtain the traditional interpretation of bracket expressions,
842 you can use the C locale by setting the
843 .B LC_ALL
844 environment variable to the value
845 .BR C .
846 .PP
847 Finally, certain named classes of characters are predefined within
848 bracket expressions, as follows.
849 Their names are self explanatory, and they are
850 .BR [:alnum:] ,
851 .BR [:alpha:] ,
852 .BR [:blank:] ,
853 .BR [:cntrl:] ,
854 .BR [:digit:] ,
855 .BR [:graph:] ,
856 .BR [:lower:] ,
857 .BR [:print:] ,
858 .BR [:punct:] ,
859 .BR [:space:] ,
860 .BR [:upper:] ,
861 and
862 .BR [:xdigit:] .
863 For example,
864 .B [[:alnum:]]
865 means the character class of numbers and
866 letters in the current locale.
867 In the C locale and ASCII
868 character set encoding, this is the same as
869 .BR [0\-9A\-Za\-z] .
870 (Note that the brackets in these class names are part of the symbolic
871 names, and must be included in addition to the brackets delimiting
872 the bracket expression.)
873 Most meta-characters lose their special meaning inside bracket expressions.
874 To include a literal
875 .B ]
876 place it first in the list.
877 Similarly, to include a literal
878 .B ^
879 place it anywhere but first.
880 Finally, to include a literal
881 .B \-
882 place it last.
883 .SS Anchoring
884 The caret
885 .B ^
886 and the dollar sign
887 .B $
888 are meta-characters that respectively match the empty string at the
889 beginning and end of a line.
890 .SS "The Backslash Character and Special Expressions"
891 The symbols
892 .B \e<
893 and
894 .B \e>
895 respectively match the empty string at the beginning and end of a word.
896 The symbol
897 .B \eb
898 matches the empty string at the edge of a word,
899 and
900 .B \eB
901 matches the empty string provided it's
902 .I not
903 at the edge of a word.
904 The symbol
905 .B \ew
906 is a synonym for
907 .B [_[:alnum:]]
908 and
909 .B \eW
910 is a synonym for
911 .BR [^_[:alnum:]] .
912 .SS Repetition
913 A regular expression may be followed by one of several repetition operators:
914 .PD 0
915 .TP
916 .B ?
917 The preceding item is optional and matched at most once.
918 .TP
919 .B *
920 The preceding item will be matched zero or more times.
921 .TP
922 .B +
923 The preceding item will be matched one or more times.
924 .TP
925 .BI { n }
926 The preceding item is matched exactly
927 .I n
928 times.
929 .TP
930 .BI { n ,}
931 The preceding item is matched
932 .I n
933 or more times.
934 .TP
935 .BI {, m }
936 The preceding item is matched at most
937 .I m
938 times.
939 This is a GNU extension.
940 .TP
941 .BI { n , m }
942 The preceding item is matched at least
943 .I n
944 times, but not more than
945 .I m
946 times.
947 .PD
948 .SS Concatenation
949 Two regular expressions may be concatenated; the resulting
950 regular expression matches any string formed by concatenating
951 two substrings that respectively match the concatenated
952 expressions.
953 .SS Alternation
954 Two regular expressions may be joined by the infix operator
955 .BR | ;
956 the resulting regular expression matches any string matching
957 either alternate expression.
958 .SS Precedence
959 Repetition takes precedence over concatenation, which in turn
960 takes precedence over alternation.
961 A whole expression may be enclosed in parentheses
962 to override these precedence rules and form a subexpression.
963 .SS "Back-references and Subexpressions"
964 The back-reference
965 .BI \e n\c
966 \&, where
967 .I n
968 is a single digit, matches the substring
969 previously matched by the
970 .IR n th
971 parenthesized subexpression of the regular expression.
972 .SS "Basic vs Extended Regular Expressions"
973 In basic regular expressions the meta-characters
974 .BR ? ,
975 .BR + ,
976 .BR { ,
977 .BR | ,
978 .BR ( ,
979 and
980 .BR )
981 lose their special meaning; instead use the backslashed
982 versions
983 .BR \e? ,
984 .BR \e+ ,
985 .BR \e{ ,
986 .BR \e| ,
987 .BR \e( ,
988 and
989 .BR \e) .
990 .
991 .SH "EXIT STATUS"
992 Normally the exit status is 0 if a line is selected, 1 if no lines
993 were selected, and 2 if an error occurred. However, if the
994 .B \-q
995 or
996 .B \-\^\-quiet
997 or
998 .B \-\^\-silent
999 is used and a line is selected, the exit status is 0 even if an error
1000 occurred.
1001 .
1002 .SH ENVIRONMENT
1003 The behavior of
1004 .B grep
1005 is affected by the following environment variables.
1006 .PP
1007 The locale for category
1008 .BI LC_ foo
1009 is specified by examining the three environment variables
1010 .BR LC_ALL ,
1011 .BR LC_\fIfoo\fP ,
1012 .BR LANG ,
1013 in that order.
1014 The first of these variables that is set specifies the locale.
1015 For example, if
1016 .B LC_ALL
1017 is not set, but
1018 .B LC_MESSAGES
1019 is set to
1020 .BR pt_BR ,
1021 then the Brazilian Portuguese locale is used for the
1022 .B LC_MESSAGES
1023 category.
1024 The C locale is used if none of these environment variables are set,
1025 if the locale catalog is not installed, or if
1026 .B grep
1027 was not compiled with national language support (NLS).
1028 The shell command
1029 .B "locale \-a"
1030 lists locales that are currently available.
1031 .TP
1032 .B GREP_COLORS
1033 Controls how the
1034 .B \-\^\-color
1035 option highlights output.
1036 Its value is a colon-separated list of capabilities
1037 that defaults to
1038 .B ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36
1039 with the
1040 .B rv
1041 and
1042 .B ne
1043 boolean capabilities omitted (i.e., false).
1044 Supported capabilities are as follows.
1045 .RS
1046 .TP
1047 .B sl=
1048 SGR substring for whole selected lines
1049 (i.e.,
1050 matching lines when the
1051 .B \-v
1052 command-line option is omitted,
1053 or non-matching lines when
1054 .B \-v
1055 is specified).
1056 If however the boolean
1057 .B rv
1058 capability
1059 and the
1060 .B \-v
1061 command-line option are both specified,
1062 it applies to context matching lines instead.
1063 The default is empty (i.e., the terminal's default color pair).
1064 .TP
1065 .B cx=
1066 SGR substring for whole context lines
1067 (i.e.,
1068 non-matching lines when the
1069 .B \-v
1070 command-line option is omitted,
1071 or matching lines when
1072 .B \-v
1073 is specified).
1074 If however the boolean
1075 .B rv
1076 capability
1077 and the
1078 .B \-v
1079 command-line option are both specified,
1080 it applies to selected non-matching lines instead.
1081 The default is empty (i.e., the terminal's default color pair).
1082 .TP
1083 .B rv
1084 Boolean value that reverses (swaps) the meanings of
1085 the
1086 .B sl=
1087 and
1088 .B cx=
1089 capabilities
1090 when the
1091 .B \-v
1092 command-line option is specified.
1093 The default is false (i.e., the capability is omitted).
1094 .TP
1095 .B mt=01;31
1096 SGR substring for matching non-empty text in any matching line
1097 (i.e.,
1098 a selected line when the
1099 .B \-v
1100 command-line option is omitted,
1101 or a context line when
1102 .B \-v
1103 is specified).
1104 Setting this is equivalent to setting both
1105 .B ms=
1106 and
1107 .B mc=
1108 at once to the same value.
1109 The default is a bold red text foreground over the current line background.
1110 .TP
1111 .B ms=01;31
1112 SGR substring for matching non-empty text in a selected line.
1113 (This is only used when the
1114 .B \-v
1115 command-line option is omitted.)
1116 The effect of the
1117 .B sl=
1118 (or
1119 .B cx=
1120 if
1121 .BR rv )
1122 capability remains active when this kicks in.
1123 The default is a bold red text foreground over the current line background.
1124 .TP
1125 .B mc=01;31
1126 SGR substring for matching non-empty text in a context line.
1127 (This is only used when the
1128 .B \-v
1129 command-line option is specified.)
1130 The effect of the
1131 .B cx=
1132 (or
1133 .B sl=
1134 if
1135 .BR rv )
1136 capability remains active when this kicks in.
1137 The default is a bold red text foreground over the current line background.
1138 .TP
1139 .B fn=35
1140 SGR substring for file names prefixing any content line.
1141 The default is a magenta text foreground over the terminal's default background.
1142 .TP
1143 .B ln=32
1144 SGR substring for line numbers prefixing any content line.
1145 The default is a green text foreground over the terminal's default background.
1146 .TP
1147 .B bn=32
1148 SGR substring for byte offsets prefixing any content line.
1149 The default is a green text foreground over the terminal's default background.
1150 .TP
1151 .B se=36
1152 SGR substring for separators that are inserted
1153 between selected line fields
1154 .RB ( : ),
1155 between context line fields,
1156 .RB ( \- ),
1157 and between groups of adjacent lines when nonzero context is specified
1158 .RB ( \-\^\- ).
1159 The default is a cyan text foreground over the terminal's default background.
1160 .TP
1161 .B ne
1162 Boolean value that prevents clearing to the end of line
1163 using Erase in Line (EL) to Right
1164 .RB ( \e33[K )
1165 each time a colorized item ends.
1166 This is needed on terminals on which EL is not supported.
1167 It is otherwise useful on terminals
1168 for which the
1169 .B back_color_erase
1170 .RB ( bce )
1171 boolean terminfo capability does not apply,
1172 when the chosen highlight colors do not affect the background,
1173 or when EL is too slow or causes too much flicker.
1174 The default is false (i.e., the capability is omitted).
1175 .PP
1176 Note that boolean capabilities have no
1177 .BR = .\|.\|.\&
1178 part.
1179 They are omitted (i.e., false) by default and become true when specified.
1180 .PP
1181 See the Select Graphic Rendition (SGR) section
1182 in the documentation of the text terminal that is used
1183 for permitted values and their meaning as character attributes.
1184 These substring values are integers in decimal representation
1185 and can be concatenated with semicolons.
1186 .B grep
1187 takes care of assembling the result
1188 into a complete SGR sequence
1189 .RB ( \e33[ .\|.\|. m ).
1190 Common values to concatenate include
1191 .B 1
1192 for bold,
1193 .B 4
1194 for underline,
1195 .B 5
1196 for blink,
1197 .B 7
1198 for inverse,
1199 .B 39
1200 for default foreground color,
1201 .B 30
1202 to
1203 .B 37
1204 for foreground colors,
1205 .B 90
1206 to
1207 .B 97
1208 for 16-color mode foreground colors,
1209 .B 38;5;0
1210 to
1211 .B 38;5;255
1212 for 88-color and 256-color modes foreground colors,
1213 .B 49
1214 for default background color,
1215 .B 40
1216 to
1217 .B 47
1218 for background colors,
1219 .B 100
1220 to
1221 .B 107
1222 for 16-color mode background colors, and
1223 .B 48;5;0
1224 to
1225 .B 48;5;255
1226 for 88-color and 256-color modes background colors.
1227 .RE
1228 .TP
1229 \fBLC_ALL\fP, \fBLC_COLLATE\fP, \fBLANG\fP
1230 These variables specify the locale for the
1231 .B LC_COLLATE
1232 category,
1233 which determines the collating sequence
1234 used to interpret range expressions like
1235 .BR [a\-z] .
1236 .TP
1237 \fBLC_ALL\fP, \fBLC_CTYPE\fP, \fBLANG\fP
1238 These variables specify the locale for the
1239 .B LC_CTYPE
1240 category,
1241 which determines the type of characters,
1242 e.g., which characters are whitespace.
1243 This category also determines the character encoding, that is, whether
1244 text is encoded in UTF-8, ASCII, or some other encoding. In the C or
1245 POSIX locale, all characters are encoded as a single byte and every
1246 byte is a valid character.
1247 .TP
1248 \fBLC_ALL\fP, \fBLC_MESSAGES\fP, \fBLANG\fP
1249 These variables specify the locale for the
1250 .B LC_MESSAGES
1251 category,
1252 which determines the language that
1253 .B grep
1254 uses for messages.
1255 The default C locale uses American English messages.
1256 .TP
1257 .B POSIXLY_CORRECT
1258 If set,
1259 .B grep
1260 behaves as POSIX requires; otherwise,
1261 .B grep
1262 behaves more like other GNU programs.
1263 POSIX requires that options that follow file names must be
1264 treated as file names; by default, such options are permuted to the
1265 front of the operand list and are treated as options.
1266 Also, POSIX requires that unrecognized options be diagnosed as
1267 \*(lqillegal\*(rq, but since they are not really against the law the default
1268 is to diagnose them as \*(lqinvalid\*(rq.
1269 .
1270 .SH NOTES
1271 This man page is maintained only fitfully;
1272 the full documentation is often more up-to-date.
1273 .
1274 .SH COPYRIGHT
1275 Copyright 1998-2000, 2002, 2005-2023 Free Software Foundation, Inc.
1276 .PP
1277 This is free software;
1278 see the source for copying conditions.
1279 There is NO warranty;
1280 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
1281 .
1282 .SH BUGS
1283 .SS "Reporting Bugs"
1284 Email bug reports to
1285 .MT [email protected]
1286 the bug-reporting address
1287 .ME .
1288 An
1289 .UR https://lists.gnu.org/mailman/listinfo/bug-grep
1290 email archive
1291 .UE
1292 and a
1293 .UR https://debbugs.gnu.org/cgi/pkgreport.cgi?package=grep
1294 bug tracker
1295 .UE
1296 are available.
1297 .SS "Known Bugs"
1298 Large repetition counts in the
1299 .BI { n , m }
1300 construct may cause
1301 .B grep
1302 to use lots of memory.
1303 In addition,
1304 certain other obscure regular expressions require exponential time
1305 and space, and may cause
1306 .B grep
1307 to run out of memory.
1308 .PP
1309 Back-references are very slow, and may require exponential time.
1310 .
1311 .SH EXAMPLE
1312 The following example outputs the location and contents of any line
1313 containing \*(lqf\*(rq and ending in \*(lq.c\*(rq,
1314 within all files in the current directory whose names
1315 contain \*(lqg\*(rq and end in \*(lq.h\*(rq.
1316 The
1317 .B \-n
1318 option outputs line numbers, the
1319 .B \-\-
1320 argument treats expansions of \*(lq*g*.h\*(rq starting with \*(lq\-\*(rq
1321 as file names not options,
1322 and the empty file /dev/null causes file names to be output
1323 even if only one file name happens to be of the form \*(lq*g*.h\*(rq.
1324 .PP
1325 .in +2n
1326 .EX
1327 $ \fBgrep\fP \-n \-\- 'f.*\e.c$' *g*.h /dev/null
1328 argmatch.h:1:/* definitions and prototypes for argmatch.c
1329 .EE
1330 .in
1331 .PP
1332 The only line that matches is line 1 of argmatch.h.
1333 Note that the regular expression syntax used in the pattern differs
1334 from the globbing syntax that the shell uses to match file names.
1335 .
1336 .SH "SEE ALSO"
1337 .SS "Regular Manual Pages"
1338 .BR awk (1),
1339 .BR cmp (1),
1340 .BR diff (1),
1341 .BR find (1),
1342 .BR perl (1),
1343 .BR sed (1),
1344 .BR sort (1),
1345 .BR xargs (1),
1346 .BR read (2),
1347 .BR pcre2 (3),
1348 .BR pcre2syntax (3),
1349 .BR pcre2pattern (3),
1350 .BR terminfo (5),
1351 .BR glob (7),
1352 .BR regex (7)
1353 .SS "Full Documentation"
1354 A
1355 .UR https://www.gnu.org/software/grep/manual/
1356 complete manual
1357 .UE
1358 is available.
1359 If the
1360 .B info
1361 and
1362 .B grep
1363 programs are properly installed at your site, the command
1364 .IP
1365 .B info grep
1366 .PP
1367 should give you access to the complete manual.
1368 .
1369 .\" Work around problems with some troff -man implementations.
1370 .br
1371 .
1372 .\" Format for Emacs-maintained Dt string defined at this file's start.
1373 .\" Local variables:
1374 .\" time-stamp-format: "%:y-%02m-%02d"
1375 .\" End: