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 April 17, 2021 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-file= 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 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