usr.bin/grep/grep.1

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