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 May 7, 2018
  34 .Dt GREP 1
  35 .Os
  36 .Sh NAME
  37 .Nm grep , egrep , fgrep , rgrep ,
  38 .Nd file pattern searcher
  39 .Sh SYNOPSIS
  40 .Nm grep
  41 .Bk -words
  42 .Op Fl abcdDEFGHhIiLlmnOopqRSsUVvwxz
  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 The following options are available:
  91 .Bl -tag -width indent
  92 .It Fl A Ar num , Fl Fl after-context Ns = Ns Ar num
  93 Print
  94 .Ar num
  95 lines of trailing context after each match.
  96 See also the
  97 .Fl B
  98 and
  99 .Fl C
 100 options.
 101 .It Fl a , Fl Fl text
 102 Treat all files as ASCII text.
 103 Normally
 104 .Nm
 105 will simply print
 106 .Dq Binary file ... matches
 107 if files contain binary characters.
 108 Use of this option forces
 109 .Nm
 110 to output lines matching the specified pattern.
 111 .It Fl B Ar num , Fl Fl before-context Ns = Ns Ar num
 112 Print
 113 .Ar num
 114 lines of leading context before each match.
 115 See also the
 116 .Fl A
 117 and
 118 .Fl C
 119 options.
 120 .It Fl b , Fl Fl byte-offset
 121 The offset in bytes of a matched pattern is
 122 displayed in front of the respective matched line.
 123 .It Fl C Ns Op Ar num , Fl Fl context Ns = Ns Ar num
 124 Print
 125 .Ar num
 126 lines of leading and trailing context surrounding each match.
 127 The default is 2 and is equivalent to
 128 .Fl A
 129 .Ar 2
 130 .Fl B
 131 .Ar 2 .
 132 Note:
 133 no whitespace may be given between the option and its argument.
 134 .It Fl c , Fl Fl count
 135 Only a count of selected lines is written to standard output.
 136 .It Fl Fl colour Ns = Ns Op Ar when , Fl Fl color Ns = Ns Op Ar when
 137 Mark up the matching text with the expression stored in
 138 .Ev GREP_COLOR
 139 environment variable.
 140 The possible values of when can be `never', `always' or `auto'.
 141 .It Fl D Ar action , Fl Fl devices Ns = Ns Ar action
 142 Specify the demanded action for devices, FIFOs and sockets.
 143 The default action is `read', which means, that they are read
 144 as if they were normal files.
 145 If the action is set to `skip', devices will be silently skipped.
 146 .It Fl d Ar action , Fl Fl directories Ns = Ns Ar action
 147 Specify the demanded action for directories.
 148 It is `read' by default, which means that the directories
 149 are read in the same manner as normal files.
 150 Other possible values are `skip' to silently ignore the
 151 directories, and `recurse' to read them recursively, which
 152 has the same effect as the
 153 .Fl R
 154 and
 155 .Fl r
 156 option.
 157 .It Fl E , Fl Fl extended-regexp
 158 Interpret
 159 .Ar pattern
 160 as an extended regular expression
 161 (i.e. force
 162 .Nm grep
 163 to behave as
 164 .Nm egrep ) .
 165 .It Fl e Ar pattern , Fl Fl regexp Ns = Ns Ar pattern
 166 Specify a pattern used during the search of the input:
 167 an input line is selected if it matches any of the specified patterns.
 168 This option is most useful when multiple
 169 .Fl e
 170 options are used to specify multiple patterns,
 171 or when a pattern begins with a dash
 172 .Pq Sq - .
 173 .It Fl Fl exclude
 174 If specified, it excludes files matching the given
 175 filename pattern from the search.
 176 Note that
 177 .Fl Fl exclude
 178 and
 179 .Fl Fl include
 180 patterns are processed in the order given.
 181 If a name patches multiple patterns, the latest matching rule wins.
 182 If no
 183 .Fl Fl include
 184 pattern is specified, all files are searched that are
 185 not excluded.
 186 Patterns are matched to the full path specified,
 187 not only to the filename component.
 188 .It Fl Fl exclude-dir
 189 If
 190 .Fl R
 191 is specified, it excludes directories matching the
 192 given filename pattern from the search.
 193 Note that
 194 .Fl Fl exclude-dir
 195 and
 196 .Fl Fl include-dir
 197 patterns are processed in the order given.
 198 If a name patches multiple patterns, the latest matching rule wins.
 199 If no
 200 .Fl Fl include-dir
 201 pattern is specified, all directories are searched that are
 202 not excluded.
 203 .It Fl F , Fl Fl fixed-strings
 204 Interpret
 205 .Ar pattern
 206 as a set of fixed strings
 207 (i.e. force
 208 .Nm grep
 209 to behave as
 210 .Nm fgrep ) .
 211 .It Fl f Ar file , Fl Fl file Ns = Ns Ar file
 212 Read one or more newline separated patterns from
 213 .Ar file .
 214 Empty pattern lines match every input line.
 215 Newlines are not considered part of a pattern.
 216 If
 217 .Ar file
 218 is empty, nothing is matched.
 219 .It Fl G , Fl Fl basic-regexp
 220 Interpret
 221 .Ar pattern
 222 as a basic regular expression
 223 (i.e. force
 224 .Nm grep
 225 to behave as traditional
 226 .Nm grep ) .
 227 .It Fl H
 228 Always print filename headers with output lines.
 229 .It Fl h , Fl Fl no-filename
 230 Never print filename headers
 231 .Pq i.e. filenames
 232 with output lines.
 233 .It Fl Fl help
 234 Print a brief help message.
 235 .It Fl I
 236 Ignore binary files.
 237 This option is equivalent to
 238 .Fl Fl binary-file Ns = Ns Ar without-match
 239 option.
 240 .It Fl i , Fl Fl ignore-case
 241 Perform case insensitive matching.
 242 By default,
 243 .Nm grep
 244 is case sensitive.
 245 .It Fl Fl include
 246 If specified, only files matching the
 247 given filename pattern are searched.
 248 Note that
 249 .Fl Fl include
 250 and
 251 .Fl Fl exclude
 252 patterns are processed in the order given.
 253 If a name patches multiple patterns, the latest matching rule wins.
 254 Patterns are matched to the full path specified,
 255 not only to the filename component.
 256 .It Fl Fl include-dir
 257 If
 258 .Fl R
 259 is specified, only directories matching the
 260 given filename pattern are searched.
 261 Note that
 262 .Fl Fl include-dir
 263 and
 264 .Fl Fl exclude-dir
 265 patterns are processed in the order given.
 266 If a name patches multiple patterns, the latest matching rule wins.
 267 .It Fl L , Fl Fl files-without-match
 268 Only the names of files not containing selected lines are written to
 269 standard output.
 270 Pathnames are listed once per file searched.
 271 If the standard input is searched, the string
 272 .Dq (standard input)
 273 is written unless a
 274 .Fl Fl label
 275 is specified.
 276 .It Fl l , Fl Fl files-with-matches
 277 Only the names of files containing selected lines are written to
 278 standard output.
 279 .Nm grep
 280 will only search a file until a match has been found,
 281 making searches potentially less expensive.
 282 Pathnames are listed once per file searched.
 283 If the standard input is searched, the string
 284 .Dq (standard input)
 285 is written unless a
 286 .Fl Fl label
 287 is specified.
 288 .It Fl Fl label
 289 Label to use in place of
 290 .Dq (standard input)
 291 for a file name where a file name would normally be printed.
 292 This option applies to
 293 .Fl H ,
 294 .Fl L ,
 295 and
 296 .Fl l .
 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 (i.e. force
 344 .Nm grep
 345 to behave as
 346 .Nm rgrep ) .
 347 .It Fl S
 348 If
 349 .Fl R
 350 is specified, all symbolic links are followed.
 351 The default is not to follow symbolic links.
 352 .It Fl s , Fl Fl no-messages
 353 Silent mode.
 354 Nonexistent and unreadable files are ignored
 355 (i.e. their error messages are suppressed).
 356 .It Fl U , Fl Fl binary
 357 Search binary files, but do not attempt to print them.
 358 .It Fl u
 359 This option has no effect and is provided only for compatibility with GNU grep.
 360 .It Fl V , Fl Fl version
 361 Display version information and exit.
 362 .It Fl v , Fl Fl invert-match
 363 Selected lines are those
 364 .Em not
 365 matching any of the specified patterns.
 366 .It Fl w , Fl Fl word-regexp
 367 The expression is searched for as a word (as if surrounded by
 368 .Sq [[:<:]]
 369 and
 370 .Sq [[:>:]] ;
 371 see
 372 .Xr re_format 7 ) .
 373 .It Fl x , Fl Fl line-regexp
 374 Only input lines selected against an entire fixed string or regular
 375 expression are considered to be matching lines.
 376 .It Fl y
 377 Equivalent to
 378 .Fl i .
 379 Obsoleted.
 380 .It Fl z , Fl Fl null-data
 381 Treat input and output data as sequences of lines terminated by a
 382 zero-byte instead of a newline.
 383 .It Fl Fl binary-files Ns = Ns Ar value
 384 Controls searching and printing of binary files.
 385 Options are
 386 .Ar binary ,
 387 the default: search binary files but do not print them;
 388 .Ar without-match :
 389 do not search binary files;
 390 and
 391 .Ar text :
 392 treat all files as text.
 393 .Sm off
 394 .It Fl Fl context Op = Ar num
 395 .Sm on
 396 Print
 397 .Ar num
 398 lines of leading and trailing context.
 399 The default is 2.
 400 .It Fl Fl line-buffered
 401 Force output to be line buffered.
 402 By default, output is line buffered when standard output is a terminal
 403 and block buffered otherwise.
 404 .El
 405 .Pp
 406 If no file arguments are specified, the standard input is used.
 407 Additionally,
 408 .Dq -
 409 may be used in place of a file name, anywhere that a file name is accepted, to
 410 read from standard input.
 411 This includes both
 412 .Fl f
 413 and file arguments.
 414 .Sh EXIT STATUS
 415 The
 416 .Nm grep
 417 utility exits with one of the following values:
 418 .Pp
 419 .Bl -tag -width flag -compact
 420 .It Li 0
 421 One or more lines were selected.
 422 .It Li 1
 423 No lines were selected.
 424 .It Li \*(Gt1
 425 An error occurred.
 426 .El
 427 .Sh EXAMPLES
 428 To find all occurrences of the word
 429 .Sq patricia
 430 in a file:
 431 .Pp
 432 .Dl $ grep 'patricia' myfile
 433 .Pp
 434 To find all occurrences of the pattern
 435 .Ql .Pp
 436 at the beginning of a line:
 437 .Pp
 438 .Dl $ grep '^\e.Pp' myfile
 439 .Pp
 440 The apostrophes ensure the entire expression is evaluated by
 441 .Nm grep
 442 instead of by the user's shell.
 443 The caret
 444 .Ql ^
 445 matches the null string at the beginning of a line,
 446 and the
 447 .Ql \e
 448 escapes the
 449 .Ql \&. ,
 450 which would otherwise match any character.
 451 .Pp
 452 To find all lines in a file which do not contain the words
 453 .Sq foo
 454 or
 455 .Sq bar :
 456 .Pp
 457 .Dl $ grep -v -e 'foo' -e 'bar' myfile
 458 .Pp
 459 A simple example of an extended regular expression:
 460 .Pp
 461 .Dl $ egrep '19|20|25' calendar
 462 .Pp
 463 Peruses the file
 464 .Sq calendar
 465 looking for either 19, 20, or 25.
 466 .Sh SEE ALSO
 467 .Xr ed 1 ,
 468 .Xr ex 1 ,
 469 .Xr sed 1 ,
 470 .Xr re_format 7
 471 .Sh STANDARDS
 472 The
 473 .Nm
 474 utility is compliant with the
 475 .St -p1003.1-2008
 476 specification.
 477 .Pp
 478 The flags
 479 .Op Fl AaBbCDdGHhILmoPRSUVw
 480 are extensions to that specification, and the behaviour of the
 481 .Fl f
 482 flag when used with an empty pattern file is left undefined.
 483 .Pp
 484 All long options are provided for compatibility with
 485 GNU versions of this utility.
 486 .Pp
 487 Historic versions of the
 488 .Nm grep
 489 utility also supported the flags
 490 .Op Fl ruy .
 491 This implementation supports those options;
 492 however, their use is strongly discouraged.
 493 .Sh HISTORY
 494 The
 495 .Nm grep
 496 command first appeared in
 497 .At v6 .