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 May 7, 2018 34.Dt GREP 1 35.Os 36.Sh NAME 37.Nm grep , egrep , fgrep , 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 Ns Op Ar num 46.Op Fl e Ar pattern 47.Op Fl f Ar file 48.Op Fl Fl binary-files Ns = Ns Ar value 49.Op Fl Fl color Ns Op = Ns Ar when 50.Op Fl Fl colour Ns Op = Ns Ar when 51.Op Fl Fl context Ns Op = 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 = 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 = 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 Ns Op Ar num , Fl Fl context Ns = Ns Ar num 124Print 125.Ar num 126lines of leading and trailing context surrounding each match. 127The default is 2 and is equivalent to 128.Fl A 129.Ar 2 130.Fl B 131.Ar 2 . 132Note: 133no whitespace may be given between the option and its argument. 134.It Fl c , Fl Fl count 135Only a count of selected lines is written to standard output. 136.It Fl Fl colour Ns = Ns Op Ar when , Fl Fl color Ns = Ns Op Ar when 137Mark up the matching text with the expression stored in 138.Ev GREP_COLOR 139environment variable. 140The possible values of when can be `never', `always' or `auto'. 141.It Fl D Ar action , Fl Fl devices Ns = Ns Ar action 142Specify the demanded action for devices, FIFOs and sockets. 143The default action is `read', which means, that they are read 144as if they were normal files. 145If the action is set to `skip', devices will be silently skipped. 146.It Fl d Ar action , Fl Fl directories Ns = Ns Ar action 147Specify the demanded action for directories. 148It is `read' by default, which means that the directories 149are read in the same manner as normal files. 150Other possible values are `skip' to silently ignore the 151directories, and `recurse' to read them recursively, which 152has the same effect as the 153.Fl R 154and 155.Fl r 156option. 157.It Fl E , Fl Fl extended-regexp 158Interpret 159.Ar pattern 160as an extended regular expression 161(i.e. force 162.Nm grep 163to behave as 164.Nm egrep ) . 165.It Fl e Ar pattern , Fl Fl regexp Ns = Ns Ar pattern 166Specify a pattern used during the search of the input: 167an input line is selected if it matches any of the specified patterns. 168This option is most useful when multiple 169.Fl e 170options are used to specify multiple patterns, 171or when a pattern begins with a dash 172.Pq Sq - . 173.It Fl Fl exclude 174If specified, it excludes files matching the given 175filename pattern from the search. 176Note that 177.Fl Fl exclude 178and 179.Fl Fl include 180patterns are processed in the order given. 181If a name patches multiple patterns, the latest matching rule wins. 182If no 183.Fl Fl include 184pattern is specified, all files are searched that are 185not excluded. 186Patterns are matched to the full path specified, 187not only to the filename component. 188.It Fl Fl exclude-dir 189If 190.Fl R 191is specified, it excludes directories matching the 192given filename pattern from the search. 193Note that 194.Fl Fl exclude-dir 195and 196.Fl Fl include-dir 197patterns are processed in the order given. 198If a name patches multiple patterns, the latest matching rule wins. 199If no 200.Fl Fl include-dir 201pattern is specified, all directories are searched that are 202not excluded. 203.It Fl F , Fl Fl fixed-strings 204Interpret 205.Ar pattern 206as a set of fixed strings 207(i.e. force 208.Nm grep 209to behave as 210.Nm fgrep ) . 211.It Fl f Ar file , Fl Fl file Ns = Ns Ar file 212Read one or more newline separated patterns from 213.Ar file . 214Empty pattern lines match every input line. 215Newlines are not considered part of a pattern. 216If 217.Ar file 218is empty, nothing is matched. 219.It Fl G , Fl Fl basic-regexp 220Interpret 221.Ar pattern 222as a basic regular expression 223(i.e. force 224.Nm grep 225to behave as traditional 226.Nm grep ) . 227.It Fl H 228Always print filename headers with output lines. 229.It Fl h , Fl Fl no-filename 230Never print filename headers 231.Pq i.e. filenames 232with output lines. 233.It Fl Fl help 234Print a brief help message. 235.It Fl I 236Ignore binary files. 237This option is equivalent to 238.Fl Fl binary-file Ns = Ns Ar without-match 239option. 240.It Fl i , Fl Fl ignore-case 241Perform case insensitive matching. 242By default, 243.Nm grep 244is case sensitive. 245.It Fl Fl include 246If specified, only files matching the 247given filename pattern are searched. 248Note that 249.Fl Fl include 250and 251.Fl Fl exclude 252patterns are processed in the order given. 253If a name patches multiple patterns, the latest matching rule wins. 254Patterns are matched to the full path specified, 255not only to the filename component. 256.It Fl Fl include-dir 257If 258.Fl R 259is specified, only directories matching the 260given filename pattern are searched. 261Note that 262.Fl Fl include-dir 263and 264.Fl Fl exclude-dir 265patterns are processed in the order given. 266If a name patches multiple patterns, the latest matching rule wins. 267.It Fl L , Fl Fl files-without-match 268Only the names of files not containing selected lines are written to 269standard output. 270Pathnames are listed once per file searched. 271If the standard input is searched, the string 272.Dq (standard input) 273is written unless a 274.Fl Fl label 275is specified. 276.It Fl l , Fl Fl files-with-matches 277Only the names of files containing selected lines are written to 278standard output. 279.Nm grep 280will only search a file until a match has been found, 281making searches potentially less expensive. 282Pathnames are listed once per file searched. 283If the standard input is searched, the string 284.Dq (standard input) 285is written unless a 286.Fl Fl label 287is specified. 288.It Fl Fl label 289Label to use in place of 290.Dq (standard input) 291for a file name where a file name would normally be printed. 292This option applies to 293.Fl H , 294.Fl L , 295and 296.Fl l . 297.It Fl Fl mmap 298Use 299.Xr mmap 2 300instead of 301.Xr read 2 302to read input, which can result in better performance under some 303circumstances but can cause undefined behaviour. 304.It Fl m Ar num, Fl Fl max-count Ns = Ns Ar num 305Stop reading the file after 306.Ar num 307matches. 308.It Fl n , Fl Fl line-number 309Each output line is preceded by its relative line number in the file, 310starting at line 1. 311The line number counter is reset for each file processed. 312This option is ignored if 313.Fl c , 314.Fl L , 315.Fl l , 316or 317.Fl q 318is 319specified. 320.It Fl Fl null 321Prints a zero-byte after the file name. 322.It Fl O 323If 324.Fl R 325is specified, follow symbolic links only if they were explicitly listed 326on the command line. 327The default is not to follow symbolic links. 328.It Fl o, Fl Fl only-matching 329Prints only the matching part of the lines. 330.It Fl p 331If 332.Fl R 333is specified, no symbolic links are followed. 334This is the default. 335.It Fl q , Fl Fl quiet , Fl Fl silent 336Quiet mode: 337suppress normal output. 338.Nm grep 339will only search a file until a match has been found, 340making searches potentially less expensive. 341.It Fl R , Fl r , Fl Fl recursive 342Recursively search subdirectories listed. 343(i.e. force 344.Nm grep 345to behave as 346.Nm rgrep ) . 347.It Fl S 348If 349.Fl R 350is specified, all symbolic links are followed. 351The default is not to follow symbolic links. 352.It Fl s , Fl Fl no-messages 353Silent mode. 354Nonexistent and unreadable files are ignored 355(i.e. their error messages are suppressed). 356.It Fl U , Fl Fl binary 357Search binary files, but do not attempt to print them. 358.It Fl u 359This option has no effect and is provided only for compatibility with GNU grep. 360.It Fl V , Fl Fl version 361Display version information and exit. 362.It Fl v , Fl Fl invert-match 363Selected lines are those 364.Em not 365matching any of the specified patterns. 366.It Fl w , Fl Fl word-regexp 367The expression is searched for as a word (as if surrounded by 368.Sq [[:<:]] 369and 370.Sq [[:>:]] ; 371see 372.Xr re_format 7 ) . 373.It Fl x , Fl Fl line-regexp 374Only input lines selected against an entire fixed string or regular 375expression are considered to be matching lines. 376.It Fl y 377Equivalent to 378.Fl i . 379Obsoleted. 380.It Fl z , Fl Fl null-data 381Treat input and output data as sequences of lines terminated by a 382zero-byte instead of a newline. 383.It Fl Fl binary-files Ns = Ns Ar value 384Controls searching and printing of binary files. 385Options are 386.Ar binary , 387the default: search binary files but do not print them; 388.Ar without-match : 389do not search binary files; 390and 391.Ar text : 392treat all files as text. 393.Sm off 394.It Fl Fl context Op = Ar num 395.Sm on 396Print 397.Ar num 398lines of leading and trailing context. 399The default is 2. 400.It Fl Fl line-buffered 401Force output to be line buffered. 402By default, output is line buffered when standard output is a terminal 403and block buffered otherwise. 404.El 405.Pp 406If no file arguments are specified, the standard input is used. 407Additionally, 408.Dq - 409may be used in place of a file name, anywhere that a file name is accepted, to 410read from standard input. 411This includes both 412.Fl f 413and file arguments. 414.Sh EXIT STATUS 415The 416.Nm grep 417utility exits with one of the following values: 418.Pp 419.Bl -tag -width flag -compact 420.It Li 0 421One or more lines were selected. 422.It Li 1 423No lines were selected. 424.It Li \*(Gt1 425An error occurred. 426.El 427.Sh EXAMPLES 428To find all occurrences of the word 429.Sq patricia 430in a file: 431.Pp 432.Dl $ grep 'patricia' myfile 433.Pp 434To find all occurrences of the pattern 435.Ql .Pp 436at the beginning of a line: 437.Pp 438.Dl $ grep '^\e.Pp' myfile 439.Pp 440The apostrophes ensure the entire expression is evaluated by 441.Nm grep 442instead of by the user's shell. 443The caret 444.Ql ^ 445matches the null string at the beginning of a line, 446and the 447.Ql \e 448escapes the 449.Ql \&. , 450which would otherwise match any character. 451.Pp 452To find all lines in a file which do not contain the words 453.Sq foo 454or 455.Sq bar : 456.Pp 457.Dl $ grep -v -e 'foo' -e 'bar' myfile 458.Pp 459A simple example of an extended regular expression: 460.Pp 461.Dl $ egrep '19|20|25' calendar 462.Pp 463Peruses the file 464.Sq calendar 465looking for either 19, 20, or 25. 466.Sh SEE ALSO 467.Xr ed 1 , 468.Xr ex 1 , 469.Xr sed 1 , 470.Xr re_format 7 471.Sh STANDARDS 472The 473.Nm 474utility is compliant with the 475.St -p1003.1-2008 476specification. 477.Pp 478The flags 479.Op Fl AaBbCDdGHhILmoPRSUVw 480are extensions to that specification, and the behaviour of the 481.Fl f 482flag when used with an empty pattern file is left undefined. 483.Pp 484All long options are provided for compatibility with 485GNU versions of this utility. 486.Pp 487Historic versions of the 488.Nm grep 489utility also supported the flags 490.Op Fl ruy . 491This implementation supports those options; 492however, their use is strongly discouraged. 493.Sh HISTORY 494The 495.Nm grep 496command first appeared in 497.At v6 . 498