usr.bin/grep/grep.1

   1 .\"     $NetBSD: grep.1,v 1.7 2003/11/05 16:39:01 cjep Exp $
   2 .\"
   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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)grep.1      8.3 (Berkeley) 4/18/94
  35 .\"
  36 .Dd July 3, 1999
  37 .Dt GREP 1
  38 .Os
  39 .Sh NAME
  40 .Nm grep, egrep, fgrep, zgrep
  41 .Nd file pattern searcher
  42 .Sh SYNOPSIS
  43 .Nm grep
  44 .Op Fl ABC Ar num
  45 .Op Fl EFGHILPSVZabchilnqrsvwxz
  46 .Op Fl d Ar action
  47 .Op Fl e Ar pattern
  48 .Op Fl f Ar file
  49 .Op Ar
  50 .Sh DESCRIPTION
  51 The
  52 .Nm grep
  53 utilities search the given input files selecting lines that match one
  54 or more patterns.
  55 By default, a pattern matches an input line if any regular expression
  56 (RE) in the pattern matches the input line without its trailing
  57 newline.
  58 An empty expression matches every line.
  59 Each input line that matches at least one of the patterns is written
  60 to the standard output.
  61 .Pp
  62 The
  63 .Nm grep
  64 utility is used for simple patterns and
  65 .Xr ex 1
  66 or
  67 .Xr ed 1
  68 style regular expressions.
  69 The
  70 .Nm egrep
  71 utility can handle extended regular expressions and multi-line
  72 patterns.
  73 The
  74 .Nm fgrep
  75 utility is quick but can handle only fixed patterns consisting of one
  76 or more lines, allowing any of the pattern lines to match a portion of
  77 the input.
  78 The
  79 .Nm zgrep
  80 utility acts like grep, but accepts input files compressed with the
  81 .Xr compress 1
  82 or
  83 .Xr gzip 1
  84 compression utilities.
  85 .Pp
  86 The following options are available:
  87 .Pp
  88 .Bl -tag -width indent
  89 .It Fl A Ar num
  90 Print
  91 .Ar num
  92 lines of trailing context after each match.
  93 .It Fl B Ar num
  94 Print
  95 .Ar num
  96 lines of leading context before each match.
  97 .It Fl C Ar num
  98 Print
  99 .Ar num
 100 lines of leading and trailing context before and after each match
 101 respectively.
 102 .It Fl D Ar action
 103 Use the specified action when processing input files that are devices, FIFOs
 104 or sockets.
 105 The default action is
 106 .Nm read ,
 107 which means that that devices are treated as ordinary files. If the action is
 108 .Nm skip
 109 then devices will not be processed at all.
 110 .It Fl E
 111 Force
 112 .Nm grep
 113 to behave as
 114 .Nm egrep.
 115 .It Fl F
 116 Force
 117 .Nm grep
 118 to behave as
 119 .Nm fgrep.
 120 .It Fl G
 121 Force
 122 .Nm grep
 123 to behave as
 124 .Nm grep.
 125 .It Fl H
 126 Always print filename headers with output lines.
 127 .It Fl I
 128 If the file being processed is binary, assume that it does not contain
 129 matching data.
 130 .It Fl L
 131 Only the names of files not containing selected lines are written to
 132 standard output.
 133 Pathnames are listed once per file searched.
 134 If the standard input is searched, the pathname
 135 .Sq Fl
 136 is written.
 137 .It Fl P
 138 If
 139 .Fl R
 140 is specified, no symbolic links are followed.
 141 .It Fl S
 142 If
 143 .Fl R
 144 is specified, all symbolic links are followed.
 145 .It Fl V
 146 Display version information.
 147 .It Fl Z
 148 When printing filenames, output a null character after the filename instead of
 149 a newline character.
 150 .It Fl a
 151 Treat all files as text.
 152 .It Fl b
 153 The block number on the disk in which a matched pattern is located is
 154 displayed in front of the respective matched line.
 155 .It Fl c
 156 Only a count of selected lines is written to standard output.
 157 .It Fl d Ar action
 158 Use the specified action when processing input files that are directories.
 159 The default action is
 160 .Nm read ,
 161 which means that directories are treated as ordinary files. If the action is
 162 .Nm skip
 163 then directories will not be processed at all. If the action is
 164 .Nm recurse
 165 then
 166 .Nm grep
 167 will read all files under each directory recursively.
 168 .It Fl e Ar expression
 169 Specify a pattern used during the search of the input. Multiple
 170 .Fl e
 171 options can be used to specify multiple patterns; an input line is
 172 selected if it matches any of the specified patterns.
 173 .It Fl f Ar pattern_file
 174 The pattern is read from the specified file. Trailing newlines in the
 175 pattern file are ignored.
 176 .Pf ( Nm Egrep
 177 and
 178 .Nm fgrep
 179 only).
 180 .It Fl h
 181 Never print filename headers with output lines.
 182 .It Fl i
 183 Perform case insensitive matching.
 184 .It Fl l
 185 Only the names of files containing selected lines are written to
 186 standard output. Pathnames are listed once per file searched. If the
 187 standard input is searched, the pathname
 188 .Sq -
 189 is written.
 190 .It Fl n
 191 Each output line is preceded by its relative line number in the file,
 192 starting at line 1.
 193 The line number counter is reset for each file processed.
 194 This option is ignored if
 195 .Fl c ,
 196 .Fl l ,
 197 or
 198 .Fl s
 199 is
 200 specified.
 201 .It Fl q
 202 Suppress normal output.
 203 .It Fl r
 204 Recursively search subdirectories listed.
 205 .It Fl s
 206 Silent mode.  Nonexistent and unreadable files are ignored.
 207 .It Fl v
 208 Selected lines are those
 209 .Em not
 210 matching the specified
 211 patterns.
 212 .It Fl w
 213 The expression is searched for as a word (as if surrounded by `\e<'
 214 and `\e>', see
 215 .Xr ex 1 ) .
 216 .It Fl x
 217 Only input lines selected against an entire fixed string or regular
 218 expression are considered to be matching lines.
 219 .It Fl z
 220 When printing matched lines, output a null character after the line instead of
 221 a newline character.
 222 .Pp
 223 .El
 224 If no file arguments are specified, the standard input is used.
 225 .Pp
 226 The
 227 .Nm grep
 228 utility exits with one of the following values:
 229 .Pp
 230 .Bl -tag -width flag -compact
 231 .It Li 0
 232 One or more lines were selected.
 233 .It Li 1
 234 No lines were selected.
 235 .It Li >1
 236 An error occurred.
 237 .El
 238 .Sh EXTENDED REGULAR EXPRESSIONS
 239 The following characters are interpreted by
 240 .Nm egrep :
 241 .Pp
 242 .Bl -tag -width flag -compact
 243 .It Cm \&$
 244 Align the match from the end of the line.
 245 .It Cm \&^
 246 Align the match from the beginning of the line.
 247 .It Cm \&|
 248 Add another pattern (see example below).
 249 .It Cm \&?
 250 Match 1 or less sequential repetitions of the pattern.
 251 .It Cm \&+
 252 Match 1 or more sequential repetitions of the pattern.
 253 .It Cm \&*
 254 Match 0 or more sequential repetitions of the pattern.
 255 .It Cm \&[]
 256 Match any single character or range of characters
 257 enclosed in the brackets.
 258 .It Cm \&\e
 259 Escape special characters which have meaning to
 260 .Nm egrep ,
 261 the set of {$,.,^,[,],|,?,+,*,(,)}.
 262 .El
 263 .Sh EXAMPLES
 264 To find all occurrences of the word patricia in a file:
 265 .Pp
 266 .Dl grep patricia myfile
 267 .Pp
 268 To find all occurrences of the pattern
 269 .Ql \&.Pp
 270 at the beginning of a line:
 271 .Pp
 272 .Dl grep '^\e.Pp'
 273 .Pp
 274 The apostrophes assure the entire expression is evaluated by
 275 .Nm grep
 276 instead of by the
 277 user's shell.
 278 The caret
 279 .Ql Li \&^
 280 matches the null string at the beginning of a line,
 281 and the
 282 .Ql Li \&\e
 283 escapes the
 284 .Ql Li \&.
 285 which would otherwise match any character.
 286 .Pp
 287 A simple example of an extended regular expression:
 288 .Pp
 289 .Dl egrep '19|20|25' calendar
 290 .Pp
 291 Peruses the file calendar looking for either 19, 20
 292 or 25.
 293 .Sh SEE ALSO
 294 .Xr ed 1 ,
 295 .Xr ex 1 ,
 296 .Xr sed 1 ,
 297 .Xr re_format 7 ,
 298 .Xr regex 3 ,
 299 .Xr regexp 3
 300 .Sh HISTORY
 301 The
 302 .Nm grep
 303 command appeared in
 304 .At v6 .