1.\" $OpenBSD: grep.1,v 1.53 2023/11/15 00:50:43 millert Exp $ 2.\" Copyright (c) 1980, 1990, 1993 3.\" The Regents of the University of California. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. Neither the name of the University nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" @(#)grep.1 8.3 (Berkeley) 4/18/94 30.\" 31.Dd $Mdocdate: November 15 2023 $ 32.Dt GREP 1 33.Os 34.Sh NAME 35.Nm grep , egrep , fgrep , 36.Nm zgrep , zegrep , zfgrep 37.Nd file pattern searcher 38.Sh SYNOPSIS 39.Nm grep 40.Bk -words 41.Op Fl abcEFGHhIiLlnoqRsUVvwxZ 42.Op Fl A Ar num 43.Op Fl B Ar num 44.Op Fl C Ns Op Ar num 45.Op Fl e Ar pattern 46.Op Fl f Ar file 47.Op Fl m Ar num 48.Op Fl -binary-files Ns = Ns Ar value 49.Op Fl -context Ns Op = Ns Ar num 50.Op Fl -label Ns = Ns Ar name 51.Op Fl -line-buffered 52.Op Fl -null 53.Op Ar pattern 54.Op Ar 55.Ek 56.Sh DESCRIPTION 57The 58.Nm grep 59utility searches any given input files, 60selecting lines that match one or more patterns. 61By default, a pattern matches an input line if the regular expression 62(RE) in the pattern matches the input line 63without its trailing newline. 64An empty expression matches every line. 65Each input line that matches at least one of the patterns is written 66to the standard output. 67If no file arguments are specified, the standard input is used. 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 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 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 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 135Each output line is preceded by its position (in bytes) in the file. 136If option 137.Fl o 138is also specified, the position of the matched pattern is displayed. 139.It Fl C Ns Oo Ar num Oc , Fl -context Ns Op = 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 151Only a count of selected lines is written to standard output. 152.It Fl E 153Interpret 154.Ar pattern 155as an extended regular expression 156(i.e. force 157.Nm grep 158to behave as 159.Nm egrep ) . 160.It Fl e Ar pattern 161Specify a pattern used during the search of the input: 162an input line is selected if it matches any of the specified patterns. 163This option is most useful when multiple 164.Fl e 165options are used to specify multiple patterns, 166or when a pattern begins with a dash 167.Pq Sq - . 168.It Fl F 169Interpret 170.Ar pattern 171as a set of fixed strings 172(i.e. force 173.Nm grep 174to behave as 175.Nm fgrep ) . 176.It Fl f Ar file 177Read one or more newline separated patterns from 178.Ar file . 179Empty pattern lines match every input line. 180Newlines are not considered part of a pattern. 181If 182.Ar file 183is empty, nothing is matched. 184.It Fl G 185Interpret 186.Ar pattern 187as a basic regular expression 188(i.e. force 189.Nm grep 190to behave as traditional 191.Nm grep ) . 192.It Fl H 193Always print filename headers 194.Pq i.e. filenames 195with output lines. 196.It Fl h 197Never print filename headers 198.Pq i.e. filenames 199with output lines. 200.It Fl I 201Ignore binary files. 202.It Fl i 203Perform case insensitive matching. 204By default, 205.Nm grep 206is case sensitive. 207.It Fl L 208Only the names of files not containing selected lines are written to 209standard output. 210Pathnames are listed once per file searched. 211If the standard input is searched, the string 212.Dq (standard input) 213is written. 214.It Fl l 215Only the names of files containing selected lines are written to 216standard output. 217.Nm grep 218will only search a file until a match has been found, 219making searches potentially less expensive. 220Pathnames are listed once per file searched. 221If the standard input is searched, the string 222.Dq (standard input) 223is written. 224.It Fl m Ar num 225Stop after finding at least one match on 226.Ar num 227different lines. 228.It Fl n 229Each output line is preceded by its relative line number in the file, 230starting at line 1. 231The line number counter is reset for each file processed. 232This option is ignored if 233.Fl c , 234.Fl L , 235.Fl l , 236or 237.Fl q 238is 239specified. 240.It Fl o 241Print each match, but only the match, not the entire line. 242.It Fl q 243Quiet mode: 244suppress normal output. 245.Nm grep 246will only search a file until a match has been found, 247making searches potentially less expensive. 248.It Fl R 249Recursively search subdirectories listed. 250If no 251.Ar file 252is given, 253.Nm 254searches the current working directory. 255.It Fl s 256Silent mode. 257Nonexistent and unreadable files are ignored 258(i.e. their error messages are suppressed). 259.It Fl U 260Search binary files, but do not attempt to print them. 261.It Fl V 262Display version information. 263All other options are ignored. 264.It Fl v 265Selected lines are those 266.Em not 267matching any of the specified patterns. 268.It Fl w 269The expression is searched for as a word (as if surrounded by 270.Sq [[:<:]] 271and 272.Sq [[:>:]] ; 273see 274.Xr re_format 7 ) . 275.It Fl x 276Only input lines selected against an entire fixed string or regular 277expression are considered to be matching lines. 278.It Fl Z 279Force 280.Nm grep 281to behave as 282.Nm zgrep . 283.It Fl -binary-files Ns = Ns Ar value 284Controls searching and printing of binary files. 285Options are 286.Ar binary , 287the default: search binary files but do not print them; 288.Ar without-match : 289do not search binary files; 290and 291.Ar text : 292treat all files as text. 293.It Fl -label Ns = Ns Ar name 294Print 295.Ar name 296instead of the filename before lines. 297.It Fl -line-buffered 298Force output to be line buffered. 299By default, output is line buffered when standard output is a terminal 300and block buffered otherwise. 301.It Fl -null 302Output a zero byte instead of the character that normally follows a 303file name. 304This option makes the output unambiguous, even in the presence of file 305names containing unusual characters like newlines. 306This is similar to the 307.Fl print0 308primary in 309.Xr find 1 . 310.El 311.Sh EXIT STATUS 312The 313.Nm grep 314utility exits with one of the following values: 315.Pp 316.Bl -tag -width Ds -offset indent -compact 317.It Li 0 318One or more lines were selected. 319.It Li 1 320No lines were selected. 321.It Li >1 322An error occurred. 323.El 324.Sh EXAMPLES 325To find all occurrences of the word 326.Sq patricia 327in a file: 328.Pp 329.Dl $ grep 'patricia' myfile 330.Pp 331To find all occurrences of the pattern 332.Ql .Pp 333at the beginning of a line: 334.Pp 335.Dl $ grep '^\e.Pp' myfile 336.Pp 337The apostrophes ensure the entire expression is evaluated by 338.Nm grep 339instead of by the user's shell. 340The caret 341.Ql ^ 342matches the null string at the beginning of a line, 343and the 344.Ql \e 345escapes the 346.Ql \&. , 347which would otherwise match any character. 348.Pp 349To find all lines in a file which do not contain the words 350.Sq foo 351or 352.Sq bar : 353.Pp 354.Dl $ grep -v -e 'foo' -e 'bar' myfile 355.Pp 356A simple example of an extended regular expression: 357.Pp 358.Dl $ egrep '19|20|25' calendar 359.Pp 360Peruses the file 361.Sq calendar 362looking for either 19, 20, or 25. 363.Sh SEE ALSO 364.Xr ed 1 , 365.Xr ex 1 , 366.Xr gzip 1 , 367.Xr sed 1 , 368.Xr re_format 7 369.Sh STANDARDS 370The 371.Nm 372utility is compliant with the 373.St -p1003.1-2008 374specification. 375.Pp 376The flags 377.Op Fl AaBbCGHhILmoRUVwZ 378are extensions to that specification, and the behaviour of the 379.Fl f 380flag when used with an empty pattern file is left undefined. 381.Pp 382All long options are provided for compatibility with 383GNU versions of this utility. 384.Pp 385Historic versions of the 386.Nm grep 387utility also supported the flags 388.Op Fl ruy . 389This implementation supports those options; 390however, their use is strongly discouraged. 391.Sh HISTORY 392The 393.Nm grep 394command first appeared in 395.At v4 . 396