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