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