commands/grep/grep.1

   1 .\"     $OpenBSD: grep.1,v 1.35 2007/05/31 19:20:10 jmc 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: May 31 2007 $
  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 abcEFGHhIiLlnoPqRSsUVvwxZ
  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 -binary-files Ns = Ns Ar value
  48 .Op Fl -context Ns Op = Ns Ar num
  49 .Op Fl -line-buffered
  50 .Op Ar pattern
  51 .Op Ar
  52 .Ek
  53 .Sh DESCRIPTION
  54 The
  55 .Nm grep
  56 utility searches any given input files,
  57 selecting lines that match one or more patterns.
  58 By default, a pattern matches an input line if the regular expression
  59 (RE) in the pattern matches the input line
  60 without its trailing newline.
  61 An empty expression matches every line.
  62 Each input line that matches at least one of the patterns is written
  63 to the standard output.
  64 .Pp
  65 .Nm grep
  66 is used for simple patterns and
  67 basic regular expressions
  68 .Pq BREs ;
  69 .Nm egrep
  70 can handle extended regular expressions
  71 .Pq EREs .
  72 See
  73 .Xr re_format 7
  74 for more information on regular expressions.
  75 .Nm fgrep
  76 is quicker than both
  77 .Nm grep
  78 and
  79 .Nm egrep ,
  80 but can only handle fixed patterns
  81 (i.e. it does not interpret regular expressions).
  82 Patterns may consist of one or more lines,
  83 allowing any of the pattern lines to match a portion of the input.
  84 .Pp
  85 .Nm zgrep ,
  86 .Nm zegrep ,
  87 and
  88 .Nm zfgrep
  89 act like
  90 .Nm grep ,
  91 .Nm egrep ,
  92 and
  93 .Nm fgrep ,
  94 respectively, but accept input files compressed with the
  95 .Xr compress 1
  96 or
  97 .Xr gzip 1
  98 compression utilities.
  99 .Pp
 100 The following options are available:
 101 .Bl -tag -width indent
 102 .It Fl A Ar num
 103 Print
 104 .Ar num
 105 lines of trailing context after each match.
 106 See also the
 107 .Fl B
 108 and
 109 .Fl C
 110 options.
 111 .It Fl a
 112 Treat all files as ASCII text.
 113 Normally
 114 .Nm
 115 will simply print
 116 .Dq Binary file ... matches
 117 if files contain binary characters.
 118 Use of this option forces
 119 .Nm
 120 to output lines matching the specified pattern.
 121 .It Fl B Ar num
 122 Print
 123 .Ar num
 124 lines of leading context before each match.
 125 See also the
 126 .Fl A
 127 and
 128 .Fl C
 129 options.
 130 .It Fl b
 131 The offset in bytes of a matched pattern is
 132 displayed in front of the respective matched line.
 133 .It Fl C Ns Op Ar num
 134 Print
 135 .Ar num
 136 lines of leading and trailing context surrounding each match.
 137 The default is 2 and is equivalent to
 138 .Fl A
 139 .Ar 2
 140 .Fl B
 141 .Ar 2 .
 142 Note:
 143 no whitespace may be given between the option and its argument.
 144 .It Fl c
 145 Only a count of selected lines is written to standard output.
 146 .It Fl E
 147 Interpret
 148 .Ar pattern
 149 as an extended regular expression
 150 (i.e. force
 151 .Nm grep
 152 to behave as
 153 .Nm egrep ) .
 154 .It Fl e Ar pattern
 155 Specify a pattern used during the search of the input:
 156 an input line is selected if it matches any of the specified patterns.
 157 This option is most useful when multiple
 158 .Fl e
 159 options are used to specify multiple patterns,
 160 or when a pattern begins with a dash
 161 .Pq Sq - .
 162 .It Fl F
 163 Interpret
 164 .Ar pattern
 165 as a set of fixed strings
 166 (i.e. force
 167 .Nm grep
 168 to behave as
 169 .Nm fgrep ) .
 170 .It Fl f Ar file
 171 Read one or more newline separated patterns from
 172 .Ar file .
 173 Empty pattern lines match every input line.
 174 Newlines are not considered part of a pattern.
 175 If
 176 .Ar file
 177 is empty, nothing is matched.
 178 .It Fl G
 179 Interpret
 180 .Ar pattern
 181 as a basic regular expression
 182 (i.e. force
 183 .Nm grep
 184 to behave as traditional
 185 .Nm grep ) .
 186 .It Fl H
 187 If
 188 .Fl R
 189 is specified, follow symbolic links only if they were explicitly listed
 190 on the command line.
 191 The default is not to follow symbolic links.
 192 .It Fl h
 193 Never print filename headers
 194 .Pq i.e. filenames
 195 with output lines.
 196 .It Fl I
 197 Ignore binary files.
 198 .It Fl i
 199 Perform case insensitive matching.
 200 By default,
 201 .Nm grep
 202 is case sensitive.
 203 .It Fl L
 204 Only the names of files not containing selected lines are written to
 205 standard output.
 206 Pathnames are listed once per file searched.
 207 If the standard input is searched, the string
 208 .Dq (standard input)
 209 is written.
 210 .It Fl l
 211 Only the names of files containing selected lines are written to
 212 standard output.
 213 .Nm grep
 214 will only search a file until a match has been found,
 215 making searches potentially less expensive.
 216 Pathnames are listed once per file searched.
 217 If the standard input is searched, the string
 218 .Dq (standard input)
 219 is written.
 220 .It Fl n
 221 Each output line is preceded by its relative line number in the file,
 222 starting at line 1.
 223 The line number counter is reset for each file processed.
 224 This option is ignored if
 225 .Fl c ,
 226 .Fl L ,
 227 .Fl l ,
 228 or
 229 .Fl q
 230 is
 231 specified.
 232 .It Fl o
 233 Always print filename headers with output lines.
 234 .It Fl P
 235 If
 236 .Fl R
 237 is specified, no symbolic links are followed.
 238 This is the default.
 239 .It Fl q
 240 Quiet mode:
 241 suppress normal output.
 242 .Nm grep
 243 will only search a file until a match has been found,
 244 making searches potentially less expensive.
 245 .It Fl R
 246 Recursively search subdirectories listed.
 247 .It Fl S
 248 If
 249 .Fl R
 250 is specified, all symbolic links are followed.
 251 The default is not to follow symbolic links.
 252 .It Fl s
 253 Silent mode.
 254 Nonexistent and unreadable files are ignored
 255 (i.e. their error messages are suppressed).
 256 .It Fl U
 257 Search binary files, but do not attempt to print them.
 258 .It Fl V
 259 Display version information.
 260 All other options are ignored.
 261 .It Fl v
 262 Selected lines are those
 263 .Em not
 264 matching any of the specified patterns.
 265 .It Fl w
 266 The expression is searched for as a word (as if surrounded by
 267 .Sq [[:<:]]
 268 and
 269 .Sq [[:>:]] ;
 270 see
 271 .Xr re_format 7 ) .
 272 .It Fl x
 273 Only input lines selected against an entire fixed string or regular
 274 expression are considered to be matching lines.
 275 .It Fl Z
 276 Force
 277 .Nm grep
 278 to behave as
 279 .Nm zgrep .
 280 .It Fl Fl binary-files Ns = Ns Ar value
 281 Controls searching and printing of binary files.
 282 Options are
 283 .Ar binary ,
 284 the default: search binary files but do not print them;
 285 .Ar without-match :
 286 do not search binary files;
 287 and
 288 .Ar text :
 289 treat all files as text.
 290 .Sm off
 291 .It Fl Fl context Op = Ar num
 292 .Sm on
 293 Print
 294 .Ar num
 295 lines of leading and trailing context.
 296 The default is 2.
 297 .It Fl Fl line-buffered
 298 Force output to be line buffered.
 299 By default, output is line buffered when standard output is a terminal
 300 and block buffered otherwise.
 301 .Pp
 302 .El
 303 If no file arguments are specified, the standard input is used.
 304 .Sh RETURN VALUES
 305 The
 306 .Nm grep
 307 utility exits with one of the following values:
 308 .Pp
 309 .Bl -tag -width flag -compact
 310 .It Li 0
 311 One or more lines were selected.
 312 .It Li 1
 313 No lines were selected.
 314 .It Li \*(Gt1
 315 An error occurred.
 316 .El
 317 .Sh EXAMPLES
 318 To find all occurrences of the word
 319 .Sq patricia
 320 in a file:
 321 .Pp
 322 .Dl $ grep 'patricia' myfile
 323 .Pp
 324 To find all occurrences of the pattern
 325 .Ql .Pp
 326 at the beginning of a line:
 327 .Pp
 328 .Dl $ grep '^\e.Pp' myfile
 329 .Pp
 330 The apostrophes ensure the entire expression is evaluated by
 331 .Nm grep
 332 instead of by the user's shell.
 333 The caret
 334 .Ql ^
 335 matches the null string at the beginning of a line,
 336 and the
 337 .Ql \e
 338 escapes the
 339 .Ql \&. ,
 340 which would otherwise match any character.
 341 .Pp
 342 To find all lines in a file which do not contain the words
 343 .Sq foo
 344 or
 345 .Sq bar :
 346 .Pp
 347 .Dl $ grep -v -e 'foo' -e 'bar' myfile
 348 .Pp
 349 A simple example of an extended regular expression:
 350 .Pp
 351 .Dl $ egrep '19|20|25' calendar
 352 .Pp
 353 Peruses the file
 354 .Sq calendar
 355 looking for either 19, 20, or 25.
 356 .Sh SEE ALSO
 357 .Xr ed 1 ,
 358 .Xr ex 1 ,
 359 .Xr gzip 1 ,
 360 .Xr sed 1 ,
 361 .Xr re_format 7
 362 .Sh STANDARDS
 363 The
 364 .Nm
 365 utility is compliant with the
 366 .St -p1003.1-2008
 367 specification.
 368 .Pp
 369 The flags
 370 .Op Fl AaBbCGHhILoPRSUVwZ
 371 are extensions to that specification, and the behaviour of the
 372 .Fl f
 373 flag when used with an empty pattern file is left undefined.
 374 .Pp
 375 All long options are provided for compatibility with
 376 GNU versions of this utility.
 377 .Pp
 378 Historic versions of the
 379 .Nm grep
 380 utility also supported the flags
 381 .Op Fl ruy .
 382 This implementation supports those options;
 383 however, their use is strongly discouraged.
 384 .Sh HISTORY
 385 The
 386 .Nm grep
 387 command first appeared in
 388 .At v6 .