path: root/usr.bin/grep/grep.1

.\"	$OpenBSD: grep.1,v 1.2 2002/11/09 02:22:33 fgsch Exp $
.\"
.\" Copyright (c) 2000 Carson Harding. All rights reserved.
.\" This code was written and contributed to OpenBSD by Carson Harding.
.\"
.\" 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. Neither the name of the author, or the names of contributors may be 
.\"    used to endorse or promote products derived from this software without
.\"    specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.Dd May 10, 2001
.Dt GREP 1
.Os
.Sh NAME
.Nm grep , egrep , fgrep
.Nd print lines matching a pattern
.Sh SYNOPSIS
.Nm grep
.Op Fl E | Fl F
.Op Fl bchilnqsvwxz
.Oo
.Fl RXH
.Op Fl L | Fl P
.Oc
.Op Fl e Ar pattern_list
.Op Fl f Ar pattern_file
.Op Ar pattern
.Op Ar file
.Ar ...
.Sh DESCRIPTION
The
.Nm
utility searches for lines that contain the specified pattern 
or patterns. By default
.Nm
prints lines containing matches to the standard output. If no input files
are specified,
.Nm
expects to read its input from the standard input.
.Pp
.Nm egrep
is equivalent to
.Nm grep
.Fl E ;
.Nm fgrep
is equivalent to
.Nm grep
.Fl F .
.Pp
The patterns are regular expressions, or in the case of
.Nm fgrep ,
fixed strings. More than one pattern may be specified on the 
command-line, either by repeated use of the
.Fl e
flag, or by separating patterns with newlines:

.Nm grep 
\'Ishmael
 Ahab' mobydick.txt

is the same as:

.Nm
-e Ishmael -e Ahab mobydick.txt

Note that many regular expression special characters also have special
meaning to the shell. It is best to enclose the regular expression 
in quotation marks. Note also that a null pattern ("" or a newline alone)
matches all input.
.Sh OPTIONS
.Pp
The options available are:
.Bl -tag -width file Ds
.It Fl E
Use extended regular expressions, as if the program was invoked as
.Nm egrep.
.It Fl F
Patterns are fixed strings, not regular expressions, as if the
program was invoked as
.Nm fgrep.
.It Fl a
Does nothing. In other greps this flag tells grep to treat the input
as ascii and turns off attempts to determine whether the input file is a 
binary file. This
.Nm grep
does not (yet) do that check, so behaves as if
.Fl a
is always specified.
.It Fl b
Prepend the byte-offset of the beginning of the line containing the match.
.It Fl c
Print only a count of the matches found.
.It Fl e Ar pattern_list
The argument to 
.Fl e
is a list of patterns to search for. 
.Fl e
may be used multiple times, each instance of which may have
one or more patterns separated by new-lines.
.It Fl f Ar pattern_file
The argument to
.Fl f
is the name of a file from which to read patterns.
.Fl f
may be more than once.
.It Fl h
Suppress the prefixing of file names to matching lines when multiple
files are searched.
.It Fl i
Ignore case in comparisons.
.It Fl l
Print only a list of the names of files in which matches were found.
If the input is the standard input,
.Nm
prints "(standard input)".
.It Fl n
Prefix matching lines with their line number in the file in which 
they occur.
.It Fl q
Be quiet about errors accessing files, only return program status.
The status returned is 0 if there was a match, 1 if there were no
matches, even if there were errors accessing files. (Without the
.Fl q
flag, if there was an error 
accessing a file 
.Nm
would return a status of 2 even
if it found matches.)
.It Fl s
Suppress errors about accessing files. Note that unlike
.Fl q
the program is not quiet: matches are still output.
.It Fl v
Invert the sense of the match: return all lines that do not
contain the pattern.
.It Fl w
The pattern is considered a word. A matching pattern in a line must not
be immediately bordered by a letter, a number, or an underscore ('_').
.It Fl x
Match the line exactly. If a regular expression (invoked as
.Nm grep ,
or
.Nm egrep )
the pattern must match the whole line (as if
the pattern was enclosed in ^ and $). If invoked as
.Nm fgrep,
the string must match the entire line.
.It Fl z
When the
.Fl l
flag is also specified, print an ASCII NUL character (0) following
the file name, rather than a newline. Like the 
.Fl print0
option to
.Nm find ,
this may be used to pass file names containing unusual characters 
to programs such as
.Nm xargs
with the
.Fl 0
flag.
.El
.Sh FILESYSTEM TRAVERSAL OPTIONS
.Pp
The following options control recursive searchs:
.Bl -tag -width file Ds
.It Fl R
Recursively descend through any specified directory arguments.
.It Fl H
If the 
.Fl R 
option is also specified, symbolic links on the command
line are followed.  (Symbolic links encountered in the tree
traversal are not followed.)
.It Fl L
If the
.Fl R
option is also specified, all symbolic links are followed.
.It Fl P
If the 
.Fl R
option is also specified, no symbolic links are followed.
.It Fl X
If the 
.Fl R 
option is also specified, searches are confined to the device on
which the search started (file system mount points are not crossed).
.El
.Sh EXAMPLES
.Pp
To print all occurrences of the word Ishmael in mobydick.txt:
.Dl grep Ishmael mobydick.txt
.Pp
To merely count all the lines in which the word Ishmael occurs:
.Dl grep -c Ishmael mobydick.txt
.Pp
To print all occurrences of either of the words Ishmael or Ahab in 
mobydick.txt:
.Dl grep 'Ishmael|Ahab' mobydick.txt
.Pp
To print all occurrences of the word whale in mobydick.txt, whether
or not it is capitalised, and where it appears alone and not as part
of a compound:
.Dl grep -iw whale mobydick.txt
.Pp
To find all the empty lines and print the line numbers for where they occur:
.Dl grep -nv \&. mobydick.txt
.Sh DIAGNOSTICS
.Pp
The
.Nm
utility exits with one of the following values:
.Pp
.Bl -tag -width flag -compact
.It 0
One or more matching lines was found.
.It 1
No matches were found.
.It 2
An error occurred (whether or not matches were found).
.Pp
Note that when the
.Fl q 
flag is used, file access errors do not cause an exit value of 2, 
and in the absence of other errors (a bad regular expression)
the exit value is determined only by whether or not matches
were found. (XX Should -s do the same??)
.Sh SEE ALSO
.Xr regex 3 ,
.Xr re_format 7
.Sh HISTORY
A
.Nm grep
command appeared in
.At v6 .
This version is a re-implementation from the POSIX specification and 
inspection of the operation of several implementations of 
.Nm grep .
.Sh NOTES
.Nm grep
has no limits on input line length (other than imposed by available
memory).