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 November 19, 2020 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 Ns Op 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 Op Cm = 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 Ns Oo Ar num Oc , Fl Fl context Ns Oo = Ns Ar num Oc 127Print 128.Ar num 129lines of leading and trailing context surrounding each match. 130The default value of 131.Ar num 132is 133.Dq 2 134and is equivalent to 135.Dq Fl A Ar 2 Fl B Ar 2 . 136Note: 137no whitespace may be given between the option and its argument. 138.It Fl c , Fl Fl count 139Only a count of selected lines is written to standard output. 140.It Fl Fl colour= Ns Oo Ar when Oc , Fl Fl color= Ns Oo Ar when Oc 141Mark up the matching text with the expression stored in the 142.Ev GREP_COLOR 143environment variable. 144The possible values of 145.Ar when 146are 147.Dq Cm never , 148.Dq Cm always 149and 150.Dq Cm auto . 151.It Fl D Ar action , Fl Fl devices= Ns Ar action 152Specify the demanded 153.Ar action 154for devices, FIFOs and sockets. 155The default 156.Ar action 157is 158.Dq Cm read , 159which means, that they are read as if they were normal files. 160If the 161.Ar action 162is set to 163.Dq Cm skip , 164devices are silently skipped. 165.It Fl d Ar action , Fl Fl directories= Ns Ar action 166Specify the demanded 167.Ar action 168for directories. 169It is 170.Dq Cm read 171by default, which means that the directories 172are read in the same manner as normal files. 173Other possible values are 174.Dq Cm skip 175to silently ignore the directories, and 176.Dq Cm recurse 177to read them recursively, which has the same effect as the 178.Fl R 179and 180.Fl r 181option. 182.It Fl E , Fl Fl extended-regexp 183Interpret 184.Ar pattern 185as an extended regular expression 186(i.e., force 187.Nm grep 188to behave as 189.Nm egrep ) . 190.It Fl e Ar pattern , Fl Fl regexp= Ns Ar pattern 191Specify a 192.Ar pattern 193used during the search of the input: 194an input line is selected if it matches any of the specified patterns. 195This option is most useful when multiple 196.Fl e 197options are used to specify multiple patterns, 198or when a 199.Ar pattern 200begins with a dash 201.Pq Sq - . 202.It Fl Fl exclude Ar pattern 203If specified, it excludes files matching the given 204filename 205.Ar pattern 206from the search. 207Note that 208.Fl Fl exclude 209and 210.Fl Fl include 211patterns are processed in the order given. 212If a name matches multiple patterns, the latest matching rule wins. 213If no 214.Fl Fl include 215pattern is specified, all files are searched that are 216not excluded. 217Patterns are matched to the full path specified, 218not only to the filename component. 219.It Fl Fl exclude-dir Ar pattern 220If 221.Fl R 222is specified, it excludes directories matching the 223given filename 224.Ar pattern 225from the search. 226Note that 227.Fl Fl exclude-dir 228and 229.Fl Fl include-dir 230patterns are processed in the order given. 231If a name matches multiple patterns, the latest matching rule wins. 232If no 233.Fl Fl include-dir 234pattern is specified, all directories are searched that are 235not excluded. 236.It Fl F , Fl Fl fixed-strings 237Interpret 238.Ar pattern 239as a set of fixed strings 240(i.e., force 241.Nm grep 242to behave as 243.Nm fgrep ) . 244.It Fl f Ar file , Fl Fl file= Ns Ar file 245Read one or more newline separated patterns from 246.Ar file . 247Empty pattern lines match every input line. 248Newlines are not considered part of a pattern. 249If 250.Ar file 251is empty, nothing is matched. 252.It Fl G , Fl Fl basic-regexp 253Interpret 254.Ar pattern 255as a basic regular expression 256(i.e., force 257.Nm grep 258to behave as traditional 259.Nm grep ) . 260.It Fl H 261Always print filename headers with output lines. 262.It Fl h , Fl Fl no-filename 263Never print filename headers 264.Pq i.e., filenames 265with output lines. 266.It Fl Fl help 267Print a brief help message. 268.It Fl I 269Ignore binary files. 270This option is equivalent to the 271.Dq Fl Fl binary-file= Ns Cm without-match 272option. 273.It Fl i , Fl Fl ignore-case 274Perform case insensitive matching. 275By default, 276.Nm grep 277is case sensitive. 278.It Fl Fl include Ar pattern 279If specified, only files matching the given filename 280.Ar pattern 281are searched. 282Note that 283.Fl Fl include 284and 285.Fl Fl exclude 286patterns are processed in the order given. 287If a name matches multiple patterns, the latest matching rule wins. 288Patterns are matched to the full path specified, 289not only to the filename component. 290.It Fl Fl include-dir Ar pattern 291If 292.Fl R 293is specified, only directories matching the given filename 294.Ar pattern 295are searched. 296Note that 297.Fl Fl include-dir 298and 299.Fl Fl exclude-dir 300patterns are processed in the order given. 301If a name matches multiple patterns, the latest matching rule wins. 302.It Fl L , Fl Fl files-without-match 303Only the names of files not containing selected lines are written to 304standard output. 305Pathnames are listed once per file searched. 306If the standard input is searched, the string 307.Dq (standard input) 308is written unless a 309.Fl Fl label 310is specified. 311.It Fl l , Fl Fl files-with-matches 312Only the names of files containing selected lines are written to 313standard output. 314.Nm grep 315will only search a file until a match has been found, 316making searches potentially less expensive. 317Pathnames are listed once per file searched. 318If the standard input is searched, the string 319.Dq (standard input) 320is written unless a 321.Fl Fl label 322is specified. 323.It Fl Fl label 324Label to use in place of 325.Dq (standard input) 326for a file name where a file name would normally be printed. 327This option applies to 328.Fl H , 329.Fl L , 330and 331.Fl l . 332.It Fl Fl mmap 333Use 334.Xr mmap 2 335instead of 336.Xr read 2 337to read input, which can result in better performance under some 338circumstances but can cause undefined behaviour. 339.It Fl m Ar num , Fl Fl max-count= Ns Ar num 340Stop reading the file after 341.Ar num 342matches. 343.It Fl n , Fl Fl line-number 344Each output line is preceded by its relative line number in the file, 345starting at line 1. 346The line number counter is reset for each file processed. 347This option is ignored if 348.Fl c , 349.Fl L , 350.Fl l , 351or 352.Fl q 353is 354specified. 355.It Fl Fl null 356Prints a zero-byte after the file name. 357.It Fl O 358If 359.Fl R 360is specified, follow symbolic links only if they were explicitly listed 361on the command line. 362The default is not to follow symbolic links. 363.It Fl o , Fl Fl only-matching 364Prints only the matching part of the lines. 365.It Fl p 366If 367.Fl R 368is specified, no symbolic links are followed. 369This is the default. 370.It Fl q , Fl Fl quiet , Fl Fl silent 371Quiet mode: 372suppress normal output. 373.Nm grep 374will only search a file until a match has been found, 375making searches potentially less expensive. 376.It Fl R , Fl r , Fl Fl recursive 377Recursively search subdirectories listed. 378(i.e., force 379.Nm grep 380to behave as 381.Nm rgrep ) . 382.It Fl S 383If 384.Fl R 385is specified, all symbolic links are followed. 386The default is not to follow symbolic links. 387.It Fl s , Fl Fl no-messages 388Silent mode. 389Nonexistent and unreadable files are ignored 390(i.e., their error messages are suppressed). 391.It Fl U , Fl Fl binary 392Search binary files, but do not attempt to print them. 393.It Fl u 394This option has no effect and is provided only for compatibility with GNU grep. 395.It Fl V , Fl Fl version 396Display version information and exit. 397.It Fl v , Fl Fl invert-match 398Selected lines are those 399.Em not 400matching any of the specified patterns. 401.It Fl w , Fl Fl word-regexp 402The expression is searched for as a word (as if surrounded by 403.Sq [[:<:]] 404and 405.Sq [[:>:]] ; 406see 407.Xr re_format 7 ) . 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 EXIT STATUS 444The 445.Nm grep 446utility exits with one of the following values: 447.Pp 448.Bl -tag -width flag -compact 449.It Li 0 450One or more lines were selected. 451.It Li 1 452No lines were selected. 453.It Li \*(Gt1 454An error occurred. 455.El 456.Sh EXAMPLES 457.Bl -dash 458.It 459Find all occurrences of the pattern 460.Sq patricia 461in a file: 462.Pp 463.Dl $ grep 'patricia' myfile 464.It 465Same as above but looking only for complete words: 466.Pp 467.Dl $ grep -w 'patricia' myfile 468.It 469Count occurrences of the exact pattern 470.Sq FOO 471: 472.Pp 473.Dl $ grep -c FOO myfile 474.It 475Same as above but ignoring case: 476.Pp 477.Dl $ grep -c -i FOO myfile 478.It 479Find all occurrences of the pattern 480.Ql .Pp 481at the beginning of a line: 482.Pp 483.Dl $ grep '^\e.Pp' myfile 484.Pp 485The apostrophes ensure the entire expression is evaluated by 486.Nm grep 487instead of by the user's shell. 488The caret 489.Ql ^ 490matches the null string at the beginning of a line, 491and the 492.Ql \e 493escapes the 494.Ql \&. , 495which would otherwise match any character. 496.It 497Find all lines in a file which do not contain the words 498.Sq foo 499or 500.Sq bar : 501.Pp 502.Dl $ grep -v -e 'foo' -e 'bar' myfile 503.It 504Peruse the file 505.Sq calendar 506looking for either 19, 20, or 25 using extended regular expressions: 507.Pp 508.Dl $ egrep '19|20|25' calendar 509.It 510Show matching lines and the name of the 511.Sq *.h 512files which contain the pattern 513.Sq FIXME . 514Do the search recursively from the 515.Pa /usr/src/sys/arm 516directory 517.Pp 518.Dl $ grep -H -R FIXME --include=*.h /usr/src/sys/arm/ 519.It 520Same as above but show only the name of the matching file: 521.Pp 522.Dl $ grep -l -R FIXME --include=*.h /usr/src/sys/arm/ 523.It 524Show lines containing the text 525.Sq foo . 526The matching part of the output is colored and every line is prefixed with 527the line number and the offset in the file for those lines that matched. 528.Pp 529.Dl $ grep -b --colour -n foo myfile 530.It 531Show lines that match the extended regular expression patterns read from the 532standard input: 533.Pp 534.Dl $ echo -e 'Free\enBSD\enAll.*reserved' | grep -E -f - myfile 535.It 536Show lines from the output of the 537.Xr pciconf 8 538command matching the specified extended regular expression along with 539three lines of leading context and one line of trailing context: 540.Pp 541.Dl $ pciconf -lv | grep -B3 -A1 -E 'class.*=.*storage' 542.It 543Suppress any output and use the exit status to show an appropriate message: 544.Pp 545.Dl $ grep -q foo myfile && echo File matches 546.El 547.Sh SEE ALSO 548.Xr ed 1 , 549.Xr ex 1 , 550.Xr sed 1 , 551.Xr zgrep 1 , 552.Xr re_format 7 553.Sh STANDARDS 554The 555.Nm 556utility is compliant with the 557.St -p1003.1-2008 558specification. 559.Pp 560The flags 561.Op Fl AaBbCDdGHhILmoPRSUVw 562are extensions to that specification, and the behaviour of the 563.Fl f 564flag when used with an empty pattern file is left undefined. 565.Pp 566All long options are provided for compatibility with 567GNU versions of this utility. 568.Pp 569Historic versions of the 570.Nm grep 571utility also supported the flags 572.Op Fl ruy . 573This implementation supports those options; 574however, their use is strongly discouraged. 575.Sh HISTORY 576The 577.Nm grep 578command first appeared in 579.At v6 . 580