NetBSD/usr.bin/grep/grep.1

.\"	$NetBSD: grep.1,v 1.1.1.2 2004/01/02 15:00:27 cjep Exp $
.\"
.\" Copyright (c) 1980, 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)grep.1	8.3 (Berkeley) 4/18/94
.\"
.Dd July 3, 1999
.Dt GREP 1
.Os
.Sh NAME
.Nm grep, egrep, fgrep, zgrep
.Nd file pattern searcher
.Sh SYNOPSIS
.Nm grep
.Op Fl ABC Ar num
.Op Fl EFGHILPSVZabchilnqrsvwxz
.Op Fl d Ar action
.Op Fl e Ar pattern
.Op Fl f Ar file
.Op Ar
.Sh DESCRIPTION
The
.Nm grep
utilities search the given input files selecting lines that match one
or more patterns.
By default, a pattern matches an input line if any regular expression
(RE) in the pattern matches the input line without its trailing
newline.
An empty expression matches every line.
Each input line that matches at least one of the patterns is written
to the standard output.
.Pp
The
.Nm grep
utility is used for simple patterns and
.Xr ex 1
or
.Xr ed 1
style regular expressions.
The
.Nm egrep
utility can handle extended regular expressions and multi-line
patterns.
The
.Nm fgrep
utility is quick but can handle only fixed patterns consisting of one
or more lines, allowing any of the pattern lines to match a portion of
the input.
The
.Nm zgrep 
utility acts like grep, but accepts input files compressed with the
.Xr compress 1
or
.Xr gzip 1
compression utilities.
.Pp
The following options are available:
.Pp
.Bl -tag -width indent
.It Fl A Ar num
Print 
.Ar num
lines of trailing context after each match.
.It Fl B Ar num
Print 
.Ar num 
lines of leading context before each match.
.It Fl C Ar num
Print
.Ar num
lines of leading and trailing context before and after each match
respectively.
.It Fl D Ar action
Use the specified action when processing input files that are devices, FIFOs 
or sockets.
The default action is 
.Nm read , 
which means that that devices are treated as ordinary files. If the action is
.Nm skip
then devices will not be processed at all. 
.It Fl E
Force 
.Nm grep 
to behave as 
.Nm egrep.
.It Fl F
Force 
.Nm grep
to behave as 
.Nm fgrep.
.It Fl G
Force 
.Nm grep
to behave as 
.Nm grep.
.It Fl H
Always print filename headers with output lines.
.It Fl I
If the file being processed is binary, assume that it does not contain 
matching data.
.It Fl L
Only the names of files not containing selected lines are written to
standard output.
Pathnames are listed once per file searched.
If the standard input is searched, the pathname
.Sq Fl
is written.
.It Fl P
If 
.Fl R
is specified, no symbolic links are followed.
.It Fl S
If 
.Fl R
is specified, all symbolic links are followed.
.It Fl V
Display version information.
.It Fl Z
When printing filenames, output a null character after the filename instead of
a newline character. 
.It Fl a
Treat all files as text.
.It Fl b
The block number on the disk in which a matched pattern is located is
displayed in front of the respective matched line.
.It Fl c
Only a count of selected lines is written to standard output.
.It Fl d Ar action
Use the specified action when processing input files that are directories.
The default action is 
.Nm read , 
which means that directories are treated as ordinary files. If the action is
.Nm skip
then directories will not be processed at all. If the action is
.Nm recurse
then 
.Nm grep
will read all files under each directory recursively.
.It Fl e Ar expression 
Specify a pattern used during the search of the input. Multiple
.Fl e
options can be used to specify multiple patterns; an input line is
selected if it matches any of the specified patterns.
.It Fl f Ar pattern_file 
The pattern is read from the specified file. Trailing newlines in the
pattern file are ignored.
.Pf ( Nm Egrep
and
.Nm fgrep
only).
.It Fl h
Never print filename headers with output lines.
.It Fl i
Perform case insensitive matching.
.It Fl l
Only the names of files containing selected lines are written to
standard output. Pathnames are listed once per file searched. If the
standard input is searched, the pathname
.Sq -
is written.
.It Fl n
Each output line is preceded by its relative line number in the file,
starting at line 1.
The line number counter is reset for each file processed.
This option is ignored if
.Fl c ,
.Fl l ,
or
.Fl s
is
specified.
.It Fl q
Suppress normal output.
.It Fl r
Recursively search subdirectories listed.
.It Fl s
Silent mode.  Nonexistent and unreadable files are ignored.
.It Fl v
Selected lines are those
.Em not
matching the specified
patterns.
.It Fl w
The expression is searched for as a word (as if surrounded by `\e<'
and `\e>', see
.Xr ex 1 ) .
.It Fl x
Only input lines selected against an entire fixed string or regular
expression are considered to be matching lines.
.It Fl z
When printing matched lines, output a null character after the line instead of
a newline character. 
.Pp
.El
If no file arguments are specified, the standard input is used.
.Pp
The
.Nm grep
utility exits with one of the following values:
.Pp
.Bl -tag -width flag -compact
.It Li 0
One or more lines were selected.
.It Li 1
No lines were selected.
.It Li >1
An error occurred.
.El
.Sh EXTENDED REGULAR EXPRESSIONS
The following characters are interpreted by
.Nm egrep :
.Pp
.Bl -tag -width flag -compact
.It Cm \&$
Align the match from the end of the line.
.It Cm \&^
Align the match from the beginning of the line.
.It Cm \&|
Add another pattern (see example below).
.It Cm \&?
Match 1 or less sequential repetitions of the pattern.
.It Cm \&+
Match 1 or more sequential repetitions of the pattern.
.It Cm \&*
Match 0 or more sequential repetitions of the pattern.
.It Cm \&[]
Match any single character or range of characters
enclosed in the brackets.
.It Cm \&\e
Escape special characters which have meaning to
.Nm egrep ,
the set of {$,.,^,[,],|,?,+,*,(,)}.
.El
.Sh EXAMPLES
To find all occurrences of the word patricia in a file:
.Pp
.Dl grep patricia myfile
.Pp
To find all occurrences of the pattern
.Ql \&.Pp
at the beginning of a line:
.Pp
.Dl grep '^\e.Pp'
.Pp
The apostrophes assure the entire expression is evaluated by
.Nm grep
instead of by the
user's shell.
The caret
.Ql Li \&^
matches the null string at the beginning of a line,
and the
.Ql Li \&\e
escapes the
.Ql Li \&.
which would otherwise match any character.
.Pp
A simple example of an extended regular expression:
.Pp
.Dl egrep '19|20|25' calendar
.Pp
Peruses the file calendar looking for either 19, 20
or 25.
.Sh SEE ALSO
.Xr ed 1 ,
.Xr ex 1 ,
.Xr sed 1 ,
.Xr re_format 7 ,
.Xr regex 3 ,
.Xr regexp 3
.Sh HISTORY
The
.Nm grep
command appeared in
.At v6 .