1.\" $NetBSD: grep.1,v 1.2 2011/02/16 01:31:33 joerg Exp $ 2.\" $FreeBSD$ 3.\" $OpenBSD: grep.1,v 1.38 2010/04/05 06:30:59 jmc Exp $ 4.\" Copyright (c) 1980, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)grep.1 8.3 (Berkeley) 4/18/94 32.\" 33.Dd December 18, 2022 34.Dt GREP 1 35.Os 36.Sh NAME 37.Nm grep , 38.Nm egrep , 39.Nm fgrep , 40.Nm rgrep 41.Nd file pattern searcher 42.Sh SYNOPSIS 43.Nm grep 44.Bk -words 45.Op Fl abcdDEFGHhIiLlmnOopqRSsUVvwxz 46.Op Fl A Ar num 47.Op Fl B Ar num 48.Op Fl C Ar num 49.Op Fl e Ar pattern 50.Op Fl f Ar file 51.Op Fl Fl binary-files= Ns Ar value 52.Op Fl Fl color Ns Op Cm = Ns Ar when 53.Op Fl Fl colour Ns Op Cm = Ns Ar when 54.Op Fl Fl context= Ns Ar num 55.Op Fl Fl label 56.Op Fl Fl line-buffered 57.Op Fl Fl null 58.Op Ar pattern 59.Op Ar 60.Ek 61.Sh DESCRIPTION 62The 63.Nm grep 64utility searches any given input files, 65selecting lines that match one or more patterns. 66By default, a pattern matches an input line if the regular expression 67(RE) in the pattern matches the input line 68without its trailing newline. 69An empty expression matches every line. 70Each input line that matches at least one of the patterns is written 71to the standard output. 72.Pp 73.Nm grep 74is used for simple patterns and 75basic regular expressions 76.Pq BREs ; 77.Nm egrep 78can handle extended regular expressions 79.Pq EREs . 80See 81.Xr re_format 7 82for more information on regular expressions. 83.Nm fgrep 84is quicker than both 85.Nm grep 86and 87.Nm egrep , 88but can only handle fixed patterns 89(i.e., it does not interpret regular expressions). 90Patterns may consist of one or more lines, 91allowing any of the pattern lines to match a portion of the input. 92.Pp 93The following options are available: 94.Bl -tag -width indent 95.It Fl A Ar num , Fl Fl after-context= Ns Ar num 96Print 97.Ar num 98lines of trailing context after each match. 99See also the 100.Fl B 101and 102.Fl C 103options. 104.It Fl a , Fl Fl text 105Treat all files as ASCII text. 106Normally 107.Nm 108will simply print 109.Dq Binary file ... matches 110if files contain binary characters. 111Use of this option forces 112.Nm 113to output lines matching the specified pattern. 114.It Fl B Ar num , Fl Fl before-context= Ns Ar num 115Print 116.Ar num 117lines of leading context before each match. 118See also the 119.Fl A 120and 121.Fl C 122options. 123.It Fl b , Fl Fl byte-offset 124The offset in bytes of a matched pattern is 125displayed in front of the respective matched line. 126.It Fl C Ar num , Fl Fl context= Ns Ar num 127Print 128.Ar num 129lines of leading and trailing context surrounding each match. 130See also the 131.Fl A 132and 133.Fl B 134options. 135.It Fl c , Fl Fl count 136Only a count of selected lines is written to standard output. 137.It Fl Fl colour= Ns Oo Ar when Oc , Fl Fl color= Ns Oo Ar when Oc 138Mark up the matching text with the expression stored in the 139.Ev GREP_COLOR 140environment variable. 141The possible values of 142.Ar when 143are 144.Dq Cm never , 145.Dq Cm always 146and 147.Dq Cm auto . 148.It Fl D Ar action , Fl Fl devices= Ns Ar action 149Specify the demanded 150.Ar action 151for devices, FIFOs and sockets. 152The default 153.Ar action 154is 155.Dq Cm read , 156which means, that they are read as if they were normal files. 157If the 158.Ar action 159is set to 160.Dq Cm skip , 161devices are silently skipped. 162.It Fl d Ar action , Fl Fl directories= Ns Ar action 163Specify the demanded 164.Ar action 165for directories. 166It is 167.Dq Cm read 168by default, which means that the directories 169are read in the same manner as normal files. 170Other possible values are 171.Dq Cm skip 172to silently ignore the directories, and 173.Dq Cm recurse 174to read them recursively, which has the same effect as the 175.Fl R 176and 177.Fl r 178option. 179.It Fl E , Fl Fl extended-regexp 180Interpret 181.Ar pattern 182as an extended regular expression 183(i.e., force 184.Nm grep 185to behave as 186.Nm egrep ) . 187.It Fl e Ar pattern , Fl Fl regexp= Ns Ar pattern 188Specify a 189.Ar pattern 190used during the search of the input: 191an input line is selected if it matches any of the specified patterns. 192This option is most useful when multiple 193.Fl e 194options are used to specify multiple patterns, 195or when a 196.Ar pattern 197begins with a dash 198.Pq Sq - . 199.It Fl Fl exclude Ar pattern 200If specified, it excludes files matching the given 201filename 202.Ar pattern 203from the search. 204Note that 205.Fl Fl exclude 206and 207.Fl Fl include 208patterns are processed in the order given. 209If a name matches multiple patterns, the latest matching rule wins. 210If no 211.Fl Fl include 212pattern is specified, all files are searched that are 213not excluded. 214Patterns are matched to the full path specified, 215not only to the filename component. 216.It Fl Fl exclude-dir Ar pattern 217If 218.Fl R 219is specified, it excludes directories matching the 220given filename 221.Ar pattern 222from the search. 223Note that 224.Fl Fl exclude-dir 225and 226.Fl Fl include-dir 227patterns are processed in the order given. 228If a name matches multiple patterns, the latest matching rule wins. 229If no 230.Fl Fl include-dir 231pattern is specified, all directories are searched that are 232not excluded. 233.It Fl F , Fl Fl fixed-strings 234Interpret 235.Ar pattern 236as a set of fixed strings 237(i.e., force 238.Nm grep 239to behave as 240.Nm fgrep ) . 241.It Fl f Ar file , Fl Fl file= Ns Ar file 242Read one or more newline separated patterns from 243.Ar file . 244Empty pattern lines match every input line. 245Newlines are not considered part of a pattern. 246If 247.Ar file 248is empty, nothing is matched. 249.It Fl G , Fl Fl basic-regexp 250Interpret 251.Ar pattern 252as a basic regular expression 253(i.e., force 254.Nm grep 255to behave as traditional 256.Nm grep ) . 257.It Fl H 258Always print filename headers with output lines. 259.It Fl h , Fl Fl no-filename 260Never print filename headers 261.Pq i.e., filenames 262with output lines. 263.It Fl Fl help 264Print a brief help message. 265.It Fl I 266Ignore binary files. 267This option is equivalent to the 268.Dq Fl Fl binary-files= Ns Cm without-match 269option. 270.It Fl i , Fl Fl ignore-case 271Perform case insensitive matching. 272By default, 273.Nm grep 274is case sensitive. 275.It Fl Fl include Ar pattern 276If specified, only files matching the given filename 277.Ar pattern 278are searched. 279Note that 280.Fl Fl include 281and 282.Fl Fl exclude 283patterns are processed in the order given. 284If a name matches multiple patterns, the latest matching rule wins. 285Patterns are matched to the full path specified, 286not only to the filename component. 287.It Fl Fl include-dir Ar pattern 288If 289.Fl R 290is specified, only directories matching the given filename 291.Ar pattern 292are searched. 293Note that 294.Fl Fl include-dir 295and 296.Fl Fl exclude-dir 297patterns are processed in the order given. 298If a name matches multiple patterns, the latest matching rule wins. 299.It Fl L , Fl Fl files-without-match 300Only the names of files not containing selected lines are written to 301standard output. 302Pathnames are listed once per file searched. 303If the standard input is searched, the string 304.Dq (standard input) 305is written unless a 306.Fl Fl label 307is specified. 308.It Fl l , Fl Fl files-with-matches 309Only the names of files containing selected lines are written to 310standard output. 311.Nm grep 312will only search a file until a match has been found, 313making searches potentially less expensive. 314Pathnames are listed once per file searched. 315If the standard input is searched, the string 316.Dq (standard input) 317is written unless a 318.Fl Fl label 319is specified. 320.It Fl Fl label 321Label to use in place of 322.Dq (standard input) 323for a file name where a file name would normally be printed. 324This option applies to 325.Fl H , 326.Fl L , 327and 328.Fl l . 329.It Fl Fl mmap 330Use 331.Xr mmap 2 332instead of 333.Xr read 2 334to read input, which can result in better performance under some 335circumstances but can cause undefined behaviour. 336.It Fl m Ar num , Fl Fl max-count= Ns Ar num 337Stop reading the file after 338.Ar num 339matches. 340.It Fl n , Fl Fl line-number 341Each output line is preceded by its relative line number in the file, 342starting at line 1. 343The line number counter is reset for each file processed. 344This option is ignored if 345.Fl c , 346.Fl L , 347.Fl l , 348or 349.Fl q 350is 351specified. 352.It Fl Fl null 353Prints a zero-byte after the file name. 354.It Fl O 355If 356.Fl R 357is specified, follow symbolic links only if they were explicitly listed 358on the command line. 359The default is not to follow symbolic links. 360.It Fl o , Fl Fl only-matching 361Prints only the matching part of the lines. 362.It Fl p 363If 364.Fl R 365is specified, no symbolic links are followed. 366This is the default. 367.It Fl q , Fl Fl quiet , Fl Fl silent 368Quiet mode: 369suppress normal output. 370.Nm grep 371will only search a file until a match has been found, 372making searches potentially less expensive. 373.It Fl R , Fl r , Fl Fl recursive 374Recursively search subdirectories listed. 375(i.e., force 376.Nm grep 377to behave as 378.Nm rgrep ) . 379.It Fl S 380If 381.Fl R 382is specified, all symbolic links are followed. 383The default is not to follow symbolic links. 384.It Fl s , Fl Fl no-messages 385Silent mode. 386Nonexistent and unreadable files are ignored 387(i.e., their error messages are suppressed). 388.It Fl U , Fl Fl binary 389Search binary files, but do not attempt to print them. 390.It Fl u 391This option has no effect and is provided only for compatibility with GNU grep. 392.It Fl V , Fl Fl version 393Display version information and exit. 394.It Fl v , Fl Fl invert-match 395Selected lines are those 396.Em not 397matching any of the specified patterns. 398.It Fl w , Fl Fl word-regexp 399The expression is searched for as a word (as if surrounded by 400.Sq [[:<:]] 401and 402.Sq [[:>:]] ; 403see 404.Xr re_format 7 ) . 405This option has no effect if 406.Fl x 407is also specified. 408.It Fl x , Fl Fl line-regexp 409Only input lines selected against an entire fixed string or regular 410expression are considered to be matching lines. 411.It Fl y 412Equivalent to 413.Fl i . 414Obsoleted. 415.It Fl z , Fl Fl null-data 416Treat input and output data as sequences of lines terminated by a 417zero-byte instead of a newline. 418.It Fl Fl binary-files= Ns Ar value 419Controls searching and printing of binary files. 420Options are: 421.Bl -tag -compact -width "binary (default)" 422.It Cm binary No (default) 423Search binary files but do not print them. 424.It Cm without-match 425Do not search binary files. 426.It Cm text 427Treat all files as text. 428.El 429.It Fl Fl line-buffered 430Force output to be line buffered. 431By default, output is line buffered when standard output is a terminal 432and block buffered otherwise. 433.El 434.Pp 435If no file arguments are specified, the standard input is used. 436Additionally, 437.Dq Cm - 438may be used in place of a file name, anywhere that a file name is accepted, to 439read from standard input. 440This includes both 441.Fl f 442and file arguments. 443.Sh ENVIRONMENT 444The following environment variables affect the execution of 445.Nm : 446.Bl -tag -width "GREP_OPTIONS" 447.It Ev GREP_COLOR 448This variable specifies the color used to highlight matched (non-empty) text. 449.It Ev GREP_OPTIONS 450This variable specifies default options 451to be placed in front of any explicit options. 452It may cause problems with portable scripts. 453.It Ev TERM 454This variable specifies the type name of the terminal, console or display-device 455type to be used. 456See 457.Xr term 7 . 458.El 459.Sh EXIT STATUS 460The 461.Nm grep 462utility exits with one of the following values: 463.Pp 464.Bl -tag -width flag -compact 465.It Li 0 466One or more lines were selected. 467.It Li 1 468No lines were selected. 469.It Li \*(Gt1 470An error occurred. 471.El 472.Sh EXAMPLES 473.Bl -dash 474.It 475Find all occurrences of the pattern 476.Sq patricia 477in a file: 478.Pp 479.Dl $ grep 'patricia' myfile 480.It 481Same as above but looking only for complete words: 482.Pp 483.Dl $ grep -w 'patricia' myfile 484.It 485Count occurrences of the exact pattern 486.Sq FOO 487: 488.Pp 489.Dl $ grep -c FOO myfile 490.It 491Same as above but ignoring case: 492.Pp 493.Dl $ grep -c -i FOO myfile 494.It 495Find all occurrences of the pattern 496.Ql .Pp 497at the beginning of a line: 498.Pp 499.Dl $ grep '^\e.Pp' myfile 500.Pp 501The apostrophes ensure the entire expression is evaluated by 502.Nm grep 503instead of by the user's shell. 504The caret 505.Ql ^ 506matches the null string at the beginning of a line, 507and the 508.Ql \e 509escapes the 510.Ql \&. , 511which would otherwise match any character. 512.It 513Find all lines in a file which do not contain the words 514.Sq foo 515or 516.Sq bar : 517.Pp 518.Dl $ grep -v -e 'foo' -e 'bar' myfile 519.It 520Peruse the file 521.Sq calendar 522looking for either 19, 20, or 25 using extended regular expressions: 523.Pp 524.Dl $ egrep '19|20|25' calendar 525.It 526Show matching lines and the name of the 527.Sq *.h 528files which contain the pattern 529.Sq FIXME . 530Do the search recursively from the 531.Pa /usr/src/sys/arm 532directory 533.Pp 534.Dl $ grep -H -R FIXME --include="*.h" /usr/src/sys/arm/ 535.It 536Same as above but show only the name of the matching file: 537.Pp 538.Dl $ grep -l -R FIXME --include="*.h" /usr/src/sys/arm/ 539.It 540Show lines containing the text 541.Sq foo . 542The matching part of the output is colored and every line is prefixed with 543the line number and the offset in the file for those lines that matched. 544.Pp 545.Dl $ grep -b --colour -n foo myfile 546.It 547Show lines that match the extended regular expression patterns read from the 548standard input: 549.Pp 550.Dl $ echo -e 'Free\enBSD\enAll.*reserved' | grep -E -f - myfile 551.It 552Show lines from the output of the 553.Xr pciconf 8 554command matching the specified extended regular expression along with 555three lines of leading context and one line of trailing context: 556.Pp 557.Dl $ pciconf -lv | grep -B3 -A1 -E 'class.*=.*storage' 558.It 559Suppress any output and use the exit status to show an appropriate message: 560.Pp 561.Dl $ grep -q foo myfile && echo File matches 562.El 563.Sh SEE ALSO 564.Xr ed 1 , 565.Xr ex 1 , 566.Xr sed 1 , 567.Xr zgrep 1 , 568.Xr re_format 7 569.Sh STANDARDS 570The 571.Nm 572utility is compliant with the 573.St -p1003.1-2008 574specification. 575.Pp 576The flags 577.Op Fl AaBbCDdGHhILmopRSUVw 578are extensions to that specification, and the behaviour of the 579.Fl f 580flag when used with an empty pattern file is left undefined. 581.Pp 582All long options are provided for compatibility with 583GNU versions of this utility. 584.Pp 585Historic versions of the 586.Nm grep 587utility also supported the flags 588.Op Fl ruy . 589This implementation supports those options; 590however, their use is strongly discouraged. 591.Sh HISTORY 592The 593.Nm grep 594command first appeared in 595.At v6 . 596