minix/usr.bin/grep/grep.1

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