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, 2017 34.Dt GREP 1 35.Os 36.Sh NAME 37.Nm grep , egrep , fgrep , rgrep , 38.Nm zgrep , zegrep , zfgrep 39.Nd file pattern searcher 40.Sh SYNOPSIS 41.Nm grep 42.Bk -words 43.Op Fl abcdDEFGHhIiJLlmnOopqRSsUVvwxZz 44.Op Fl A Ar num 45.Op Fl B Ar num 46.Op Fl C Ns Op Ar num 47.Op Fl e Ar pattern 48.Op Fl f Ar file 49.Op Fl Fl binary-files Ns = Ns Ar value 50.Op Fl Fl color Ns Op = Ns Ar when 51.Op Fl Fl colour Ns Op = Ns Ar when 52.Op Fl Fl context Ns Op = Ns Ar num 53.Op Fl Fl label 54.Op Fl Fl line-buffered 55.Op Fl Fl null 56.Op Ar pattern 57.Op Ar 58.Ek 59.Sh DESCRIPTION 60The 61.Nm grep 62utility searches any given input files, 63selecting lines that match one or more patterns. 64By default, a pattern matches an input line if the regular expression 65(RE) in the pattern matches the input line 66without its trailing newline. 67An empty expression matches every line. 68Each input line that matches at least one of the patterns is written 69to the standard output. 70.Pp 71.Nm grep 72is used for simple patterns and 73basic regular expressions 74.Pq BREs ; 75.Nm egrep 76can handle extended regular expressions 77.Pq EREs . 78See 79.Xr re_format 7 80for more information on regular expressions. 81.Nm fgrep 82is quicker than both 83.Nm grep 84and 85.Nm egrep , 86but can only handle fixed patterns 87(i.e. it does not interpret regular expressions). 88Patterns may consist of one or more lines, 89allowing any of the pattern lines to match a portion of the input. 90.Pp 91.Nm zgrep , 92.Nm zegrep , 93and 94.Nm zfgrep 95act like 96.Nm grep , 97.Nm egrep , 98and 99.Nm fgrep , 100respectively, but accept input files compressed with the 101.Xr compress 1 102or 103.Xr gzip 1 104compression utilities. 105.Pp 106The following options are available: 107.Bl -tag -width indent 108.It Fl A Ar num , Fl Fl after-context Ns = Ns Ar num 109Print 110.Ar num 111lines of trailing context after each match. 112See also the 113.Fl B 114and 115.Fl C 116options. 117.It Fl a , Fl Fl text 118Treat all files as ASCII text. 119Normally 120.Nm 121will simply print 122.Dq Binary file ... matches 123if files contain binary characters. 124Use of this option forces 125.Nm 126to output lines matching the specified pattern. 127.It Fl B Ar num , Fl Fl before-context Ns = Ns Ar num 128Print 129.Ar num 130lines of leading context before each match. 131See also the 132.Fl A 133and 134.Fl C 135options. 136.It Fl b , Fl Fl byte-offset 137The offset in bytes of a matched pattern is 138displayed in front of the respective matched line. 139.It Fl C Ns Op Ar num , Fl Fl context Ns = Ns Ar num 140Print 141.Ar num 142lines of leading and trailing context surrounding each match. 143The default is 2 and is equivalent to 144.Fl A 145.Ar 2 146.Fl B 147.Ar 2 . 148Note: 149no whitespace may be given between the option and its argument. 150.It Fl c , Fl Fl count 151Only a count of selected lines is written to standard output. 152.It Fl Fl colour Ns = Ns Op Ar when , Fl Fl color Ns = Ns Op Ar when 153Mark up the matching text with the expression stored in 154.Ev GREP_COLOR 155environment variable. 156The possible values of when can be `never', `always' or `auto'. 157.It Fl D Ar action , Fl Fl devices Ns = Ns Ar action 158Specify the demanded action for devices, FIFOs and sockets. 159The default action is `read', which means, that they are read 160as if they were normal files. 161If the action is set to `skip', devices will be silently skipped. 162.It Fl d Ar action , Fl Fl directories Ns = Ns Ar action 163Specify the demanded action for directories. 164It is `read' by default, which means that the directories 165are read in the same manner as normal files. 166Other possible values are `skip' to silently ignore the 167directories, and `recurse' to read them recursively, which 168has the same effect as the 169.Fl R 170and 171.Fl r 172option. 173.It Fl E , Fl Fl extended-regexp 174Interpret 175.Ar pattern 176as an extended regular expression 177(i.e. force 178.Nm grep 179to behave as 180.Nm egrep ) . 181.It Fl e Ar pattern , Fl Fl regexp Ns = Ns Ar pattern 182Specify a pattern used during the search of the input: 183an input line is selected if it matches any of the specified patterns. 184This option is most useful when multiple 185.Fl e 186options are used to specify multiple patterns, 187or when a pattern begins with a dash 188.Pq Sq - . 189.It Fl Fl exclude 190If specified, it excludes files matching the given 191filename pattern from the search. 192Note that 193.Fl Fl exclude 194patterns take priority over 195.Fl Fl include 196patterns, and if no 197.Fl Fl include 198pattern is specified, all files are searched that are 199not excluded. 200Patterns are matched to the full path specified, 201not only to the filename component. 202.It Fl Fl exclude-dir 203If 204.Fl R 205is specified, it excludes directories matching the 206given filename pattern from the search. 207Note that 208.Fl Fl exclude-dir 209patterns take priority over 210.Fl Fl include-dir 211patterns, and if no 212.Fl Fl include-dir 213pattern is specified, all directories are searched that are 214not excluded. 215.It Fl F , Fl Fl fixed-strings 216Interpret 217.Ar pattern 218as a set of fixed strings 219(i.e. force 220.Nm grep 221to behave as 222.Nm fgrep ) . 223.It Fl f Ar file , Fl Fl file Ns = Ns Ar file 224Read one or more newline separated patterns from 225.Ar file . 226Empty pattern lines match every input line. 227Newlines are not considered part of a pattern. 228If 229.Ar file 230is empty, nothing is matched. 231.It Fl G , Fl Fl basic-regexp 232Interpret 233.Ar pattern 234as a basic regular expression 235(i.e. force 236.Nm grep 237to behave as traditional 238.Nm grep ) . 239.It Fl H 240Always print filename headers with output lines. 241.It Fl h , Fl Fl no-filename 242Never print filename headers 243.Pq i.e. filenames 244with output lines. 245.It Fl Fl help 246Print a brief help message. 247.It Fl I 248Ignore binary files. 249This option is equivalent to 250.Fl Fl binary-file Ns = Ns Ar without-match 251option. 252.It Fl i , Fl Fl ignore-case 253Perform case insensitive matching. 254By default, 255.Nm grep 256is case sensitive. 257.It Fl Fl include 258If specified, only files matching the 259given filename pattern are searched. 260Note that 261.Fl Fl exclude 262patterns take priority over 263.Fl Fl include 264patterns. 265Patterns are matched to the full path specified, 266not only to the filename component. 267.It Fl Fl include-dir 268If 269.Fl R 270is specified, only directories matching the 271given filename pattern are searched. 272Note that 273.Fl Fl exclude-dir 274patterns take priority over 275.Fl Fl include-dir 276patterns. 277.It Fl J, Fl Fl bz2decompress 278Decompress the 279.Xr bzip2 1 280compressed file before looking for the text. 281.It Fl L , Fl Fl files-without-match 282Only the names of files not containing selected lines are written to 283standard output. 284Pathnames are listed once per file searched. 285If the standard input is searched, the string 286.Dq (standard input) 287is written. 288.It Fl l , Fl Fl files-with-matches 289Only the names of files containing selected lines are written to 290standard output. 291.Nm grep 292will only search a file until a match has been found, 293making searches potentially less expensive. 294Pathnames are listed once per file searched. 295If the standard input is searched, the string 296.Dq (standard input) 297is written. 298.It Fl Fl mmap 299Use 300.Xr mmap 2 301instead of 302.Xr read 2 303to read input, which can result in better performance under some 304circumstances but can cause undefined behaviour. 305.It Fl m Ar num, Fl Fl max-count Ns = Ns Ar num 306Stop reading the file after 307.Ar num 308matches. 309.It Fl n , Fl Fl line-number 310Each output line is preceded by its relative line number in the file, 311starting at line 1. 312The line number counter is reset for each file processed. 313This option is ignored if 314.Fl c , 315.Fl L , 316.Fl l , 317or 318.Fl q 319is 320specified. 321.It Fl Fl null 322Prints a zero-byte after the file name. 323.It Fl O 324If 325.Fl R 326is specified, follow symbolic links only if they were explicitly listed 327on the command line. 328The default is not to follow symbolic links. 329.It Fl o, Fl Fl only-matching 330Prints only the matching part of the lines. 331.It Fl p 332If 333.Fl R 334is specified, no symbolic links are followed. 335This is the default. 336.It Fl q , Fl Fl quiet , Fl Fl silent 337Quiet mode: 338suppress normal output. 339.Nm grep 340will only search a file until a match has been found, 341making searches potentially less expensive. 342.It Fl R , Fl r , Fl Fl recursive 343Recursively search subdirectories listed. 344(i.e. force 345.Nm grep 346to behave as 347.Nm rgrep ) . 348.It Fl S 349If 350.Fl R 351is specified, all symbolic links are followed. 352The default is not to follow symbolic links. 353.It Fl s , Fl Fl no-messages 354Silent mode. 355Nonexistent and unreadable files are ignored 356(i.e. their error messages are suppressed). 357.It Fl U , Fl Fl binary 358Search binary files, but do not attempt to print them. 359.It Fl u 360This option has no effect and is provided only for compatibility with GNU grep. 361.It Fl V , Fl Fl version 362Display version information and exit. 363.It Fl v , Fl Fl invert-match 364Selected lines are those 365.Em not 366matching any of the specified patterns. 367.It Fl w , Fl Fl word-regexp 368The expression is searched for as a word (as if surrounded by 369.Sq [[:<:]] 370and 371.Sq [[:>:]] ; 372see 373.Xr re_format 7 ) . 374.It Fl x , Fl Fl line-regexp 375Only input lines selected against an entire fixed string or regular 376expression are considered to be matching lines. 377.It Fl y 378Equivalent to 379.Fl i . 380Obsoleted. 381.It Fl z , Fl Fl null-data 382Treat input and output data as sequences of lines terminated by a 383zero-byte instead of a newline. 384.It Fl Z , Fl Fl decompress 385Force 386.Nm grep 387to behave as 388.Nm zgrep . 389.It Fl Fl binary-files Ns = Ns Ar value 390Controls searching and printing of binary files. 391Options are 392.Ar binary , 393the default: search binary files but do not print them; 394.Ar without-match : 395do not search binary files; 396and 397.Ar text : 398treat all files as text. 399.Sm off 400.It Fl Fl context Op = Ar num 401.Sm on 402Print 403.Ar num 404lines of leading and trailing context. 405The default is 2. 406.It Fl Fl line-buffered 407Force output to be line buffered. 408By default, output is line buffered when standard output is a terminal 409and block buffered otherwise. 410.El 411.Pp 412If no file arguments are specified, the standard input is used. 413.Sh EXIT STATUS 414The 415.Nm grep 416utility exits with one of the following values: 417.Pp 418.Bl -tag -width flag -compact 419.It Li 0 420One or more lines were selected. 421.It Li 1 422No lines were selected. 423.It Li \*(Gt1 424An error occurred. 425.El 426.Sh EXAMPLES 427To find all occurrences of the word 428.Sq patricia 429in a file: 430.Pp 431.Dl $ grep 'patricia' myfile 432.Pp 433To find all occurrences of the pattern 434.Ql .Pp 435at the beginning of a line: 436.Pp 437.Dl $ grep '^\e.Pp' myfile 438.Pp 439The apostrophes ensure the entire expression is evaluated by 440.Nm grep 441instead of by the user's shell. 442The caret 443.Ql ^ 444matches the null string at the beginning of a line, 445and the 446.Ql \e 447escapes the 448.Ql \&. , 449which would otherwise match any character. 450.Pp 451To find all lines in a file which do not contain the words 452.Sq foo 453or 454.Sq bar : 455.Pp 456.Dl $ grep -v -e 'foo' -e 'bar' myfile 457.Pp 458A simple example of an extended regular expression: 459.Pp 460.Dl $ egrep '19|20|25' calendar 461.Pp 462Peruses the file 463.Sq calendar 464looking for either 19, 20, or 25. 465.Sh SEE ALSO 466.Xr ed 1 , 467.Xr ex 1 , 468.Xr gzip 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 AaBbCDdGHhIJLmoPRSUVwZ 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