.\" @(#)pgrep.1v 1.33 92/03/20 SMI;
.TH PGREP 1V "20 MARCH 1992"
.SH NAME
pgrep \- search a file for a string or regular expression
.SH SYNOPSIS
.B pgrep
[
.B \-pchilnsvx
] [
.BI \-e " expression"
] [
.BI \-f " filename"
] 
.if n .ti +0.5i
[
.I expression
] [
.IR filename ".\|.\|. ]" 
.SH DESCRIPTION
.B pgrep
search the input
.IR filename s
(the standard input default) for lines matching a pattern.
Normally, each line found is copied to the standard output.
.B pgrep
uses the full set of regular expressions that is supplied by
.BR perl (1) 
Take care when using the characters
.RB ` $ ',
.RB ` \(** ',
.RB ` [ ',
.RB ` ] ',
.RB ` \s+2^\s0 ',
.RB ` | ',
.RB ` ( ',
.RB ` ) ',
.RB ` ? ',
and
.RB ` \e '
in the
.IR expression ,
as these characters are also meaningful
to the shell.  It is safest to enclose
the entire
.I expression
argument in single quotes
.BR \&\|\' \|.\|.\|.\| \' .
.LP
When any of the
.B pgrep
utilities is applied to more than one input
file, the name of the file is displayed
preceding each line which matches
the pattern.  The filename is not displayed
when processing a single
file, so if you actually want the filename
to appear, use
.B /dev/null
as a second file in the list.
.LP
When executing, 
.B pgrep
constructs a
.BR perl (1)
program that it then executes (unless you give the
.B \-p
option in which case it prints the program to
.B stdout
). The program can then be fed into
.BR perl (1)
to execute the search.

.SH OPTIONS
.IP \-p
Print the code that
.BR perl (1)
evaluates to search the files on the standard output.
This code can then be passed to
.BR perl (1)
with the files that was supplied to
.BR pgrep (1v)
to execute the same search.
.IP \-c
Display a count of matching lines rather
than displaying the lines which
match.
.IP \-d
Do not hardcode the filenames in the code.
This option is used if you want to use the program produced for
several different queries.
Use the
.B \-p
option to print out the program.
The default is to hardcode the filenames into the code so that running
the program produced will look through the files supplied to
.BR pgrep (1)
instead of those supplied to the program produced.
.IP \-h
Do not display filenames.
.IP \-i
Ignore the case of letters in making
comparisons \(em that is, upper and
lower case are considered identical.
.IP \-l
List only the names of files with matching
lines (once) separated by
.SM NEWLINE
characters.
.IP \-n
Precede each line by its relative line number in the file.
.IP \-s
Work silently, that is, display nothing except error messages.
This is useful for checking the error status.
.IP \-v
Invert the search to only display lines that
.I do not
match.
.IP \-x
Display only those lines which match exactly \(em
that is, only lines
which match in their entirety.
.TP
.BI \-e " expression"
Same as a simple
.I expression
argument, but useful when the
.I expression
begins with a
.RB ` \- '.
.TP
.BI \-f " filename"
Take the regular expressions separated by
.SM NEWLINE\s0
from
.IR filename .
.br
.ne 4
.SH "REGULAR EXPRESSIONS"
.LP
Following is a description of 
regular expressions used by
.BR perl (1)
.RS
.LP
The primitive regular expressions are
.RS
.TP
.B \s+4.\s0
A
.RB ` \s+4.\s0 '
matches any character except
.B NEWLINE
.TP
\ew ( \eW )
matches any (non-)alphanumeric character, `_' counts as an
alphanumeric character.
.TP
\es ( \eS )
matches any (non-)whitespace character (
.SM TAB , SPACE , NEWLINE ,
.SM CARRIGE RETURN
)
.TP
\ed ( \eD )
matches any (non-)numeric character
.TP
\eb ( \eB )
matches any (non-)word boundary. Type `\ebfoo\eb' to match `foo' but not
`foobar' or `barfoo'.
.TP
.BI \e c
for any character
.I c
where
.I c
is a special character matches the special character itself.
The special characters are:
.RB ` . ',
.RB ` ? ',
.RB ` * ',
.RB ` + ',
.RB ` | ',
.RB ` ( ',
.RB ` ) ',
.RB ` [ ',
.RB ` ] ',
.RB ` { ',
.RB ` } ',
.RB ` $ '
and
.RB ` \e '
In addition the characters
.RB ` ^ '
is special at the beginning of a line.

Hint: You can escape any non-alphanumeric character using `\e' to
match that character itself as there is no special regexp of the
format `
.BI \e c
' where
.I c
is a non-alphanumeric character.
.RE
.LP
You can also construct regular expression in the following way:
.RS
.TP
.IR w *
matches any sequence of zero or more
.B w
.TP
.IR w +
matches any sequence of one or more
.I w
.TP
.IR w ?
matches any sequence of zero or one
.B w
.TP
.RI ( w )
matches
.I w\s0.
This is used for grouping.
.TP
.IR w { m , n }
matches between
.IR m " and " n
occurances of
.I w\s0.
If
.I n
is omitted it matches a sequence of
.I m
or more
.I w\s0.
.TP
.IR w { n }
matches a sequence of exactly
.I n
occurances of
.I w\s0.
.TP
.IR u | w
matches
.IR u " or " w
.TP
.RI [ string ]
matches any one occurance of a character in
.I string\s0.
It is also possible to name character ranges by using
.BR ` - ' \s0.
For example `[a-e]' is the same as `[abcde]'. If you want to use
.BR ` - '
as a matching character put it first in
.I string \s0.
.TP
.RI [ ^string ]
matches any one occurance of a character
.IR not " in " string .
.RE
.RE
.SH EXAMPLES
.LP
Search a file for a fixed string
.LP
.RS
.nf
.ft B
example% pgrep intro /usr/share/man/man3/*.3*
.ft P
.fi
.RE
.LP
Look for character classes
.LP
.RS
.nf
.ft B
example% pgrep '\ew+\es*\e(\ed\ew?\e)' /usr/share/man1/*.1
.ft P
.fi
.RE
.LP
Look for alternative patterns using
.LP
.RS
.nf
.ft B
example% pgrep '(Sally|Fred) (Smith|Jones|Parker)' telephone.list
.ft P
.fi
.RE
.LP
To get the filename displayed when only processing a single file, use
.B /dev/null
as the second file in the list:
.LP
.RS
.nf
.ft B
example% pgrep 'Sally Parker' telephone.list /dev/null
.ft P
.fi
.RE
.LP
To look for a specific word in a file without listing lines where the
word occurs as part of other words.
.LP
.RS
.nf
.ft B
example% pgrep '\ebfoo\eb' file_with_foos.txt
.ft P
.fi
.RE

.SH FILES
.PD 0
.IP /dev/null 20
.B 
.PD
.SH "SEE ALSO"
.BR awk (1),
.BR ed (1),
.BR ex (1),
.BR sh (1),
.BR vi (1),
.BR sed (1V),
.BR grep (1V),
.BR egrep (1V),
.BR fgrep (1V),
.BR perl (1)
.SH AUTHORS
Mats Kindahl (matkin@bern.docs.uu.se)
.SH BUGS
.LP
The combination of
.B \-l
and
.B \-v
options does
.I not
produce a list of files in which a regular expression is not found.
To get such a list, use the Bourne shell construct:
.LP
.nf
.ft B
.\" Unfortunately, this is what you have to do to set tabs every 8 spaces
.ta +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u +8u*\w'\0'u
	for \fIfilename\fP in *
	do
		if [ `pgrep "\fIre\fP" $\fIfilename\fP | wc -l` -eq 0 ]
		then
			echo $\fIfilename\fP
		fi
	done
.ft R
.fi
.LP
or the C shell construct:
.LP
.nf
.ft B
	foreach \fIfilename\fP (*)
		if (`pgrep "\fIre\fP" $\fIfilename\fP | wc -l` == 0) echo $\fIfilename\fP
	end
.ft R
.fi
.SH DIAGNOSTICS
Exit status is 0 if any matches are found,
1 if none, 2 for syntax errors or inaccessible files.