Debian Codegraph @

upstream/mageia-cauldron/man1/grep.1

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