usr.bin/grep/grep.1

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