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