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 July 28, 2010 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.Bk -words 43.Op Fl abcdDEFGHhIiJLlmnOopqRSsUVvwxZ 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.It Fl S 345If 346.Fl R 347is specified, all symbolic links are followed. 348The default is not to follow symbolic links. 349.It Fl s , Fl Fl no-messages 350Silent mode. 351Nonexistent and unreadable files are ignored 352(i.e. their error messages are suppressed). 353.It Fl U , Fl Fl binary 354Search binary files, but do not attempt to print them. 355.It Fl u 356This option has no effect and is provided only for compatibility with GNU grep. 357.It Fl V , Fl Fl version 358Display version information and exit. 359.It Fl v , Fl Fl invert-match 360Selected lines are those 361.Em not 362matching any of the specified patterns. 363.It Fl w , Fl Fl word-regexp 364The expression is searched for as a word (as if surrounded by 365.Sq [[:<:]] 366and 367.Sq [[:>:]] ; 368see 369.Xr re_format 7 ) . 370.It Fl x , Fl Fl line-regexp 371Only input lines selected against an entire fixed string or regular 372expression are considered to be matching lines. 373.It Fl y 374Equivalent to 375.Fl i . 376Obsoleted. 377.It Fl Z , Fl z , Fl Fl decompress 378Force 379.Nm grep 380to behave as 381.Nm zgrep . 382.It Fl Fl binary-files Ns = Ns Ar value 383Controls searching and printing of binary files. 384Options are 385.Ar binary , 386the default: search binary files but do not print them; 387.Ar without-match : 388do not search binary files; 389and 390.Ar text : 391treat all files as text. 392.Sm off 393.It Fl Fl context Op = Ar num 394.Sm on 395Print 396.Ar num 397lines of leading and trailing context. 398The default is 2. 399.It Fl Fl line-buffered 400Force output to be line buffered. 401By default, output is line buffered when standard output is a terminal 402and block buffered otherwise. 403.El 404.Pp 405If no file arguments are specified, the standard input is used. 406.Sh EXIT STATUS 407The 408.Nm grep 409utility exits with one of the following values: 410.Pp 411.Bl -tag -width flag -compact 412.It Li 0 413One or more lines were selected. 414.It Li 1 415No lines were selected. 416.It Li \*(Gt1 417An error occurred. 418.El 419.Sh EXAMPLES 420To find all occurrences of the word 421.Sq patricia 422in a file: 423.Pp 424.Dl $ grep 'patricia' myfile 425.Pp 426To find all occurrences of the pattern 427.Ql .Pp 428at the beginning of a line: 429.Pp 430.Dl $ grep '^\e.Pp' myfile 431.Pp 432The apostrophes ensure the entire expression is evaluated by 433.Nm grep 434instead of by the user's shell. 435The caret 436.Ql ^ 437matches the null string at the beginning of a line, 438and the 439.Ql \e 440escapes the 441.Ql \&. , 442which would otherwise match any character. 443.Pp 444To find all lines in a file which do not contain the words 445.Sq foo 446or 447.Sq bar : 448.Pp 449.Dl $ grep -v -e 'foo' -e 'bar' myfile 450.Pp 451A simple example of an extended regular expression: 452.Pp 453.Dl $ egrep '19|20|25' calendar 454.Pp 455Peruses the file 456.Sq calendar 457looking for either 19, 20, or 25. 458.Sh SEE ALSO 459.Xr ed 1 , 460.Xr ex 1 , 461.Xr gzip 1 , 462.Xr sed 1 , 463.Xr re_format 7 464.Sh STANDARDS 465The 466.Nm 467utility is compliant with the 468.St -p1003.1-2008 469specification. 470.Pp 471The flags 472.Op Fl AaBbCDdGHhIJLmoPRSUVwZ 473are extensions to that specification, and the behaviour of the 474.Fl f 475flag when used with an empty pattern file is left undefined. 476.Pp 477All long options are provided for compatibility with 478GNU versions of this utility. 479.Pp 480Historic versions of the 481.Nm grep 482utility also supported the flags 483.Op Fl ruy . 484This implementation supports those options; 485however, their use is strongly discouraged. 486.Sh HISTORY 487The 488.Nm grep 489command first appeared in 490.At v6 . 491