Debian Codegraph @

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