mirror of https://github.com/mkerrisk/man-pages
451 lines
13 KiB
Groff
451 lines
13 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GREP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" grep
|
|
.SH NAME
|
|
grep \- search a file for a pattern
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBgrep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB]\fP
|
|
\fB-e\fP
|
|
\fIpattern_list...
|
|
.br
|
|
\fP \fB\ \ \ \ \ \ \fP \fI\fP\fB[\fP\fB-f\fP
|
|
\fIpattern_file\fP\fB]\fP\fB...\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB
|
|
.br
|
|
.sp
|
|
grep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB][\fP\fB-e\fP
|
|
\fIpattern_list\fP\fB]...
|
|
.br
|
|
\fP \fB\ \ \ \ \ \ \fP \fB\fP\fB-f\fP
|
|
\fIpattern_file\fP\fB...\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB
|
|
.br
|
|
.sp
|
|
grep\fP \fB[\fP\fB-E| -F\fP\fB][\fP\fB-c| -l| -q\fP\fB][\fP\fB-insvx\fP\fB]\fP
|
|
\fIpattern_list\fP\fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgrep\fP utility shall search the input files, selecting lines
|
|
matching one or more patterns; the types of patterns are
|
|
controlled by the options specified. The patterns are specified by
|
|
the \fB-e\fP option, \fB-f\fP option, or the
|
|
\fIpattern_list\fP operand. The \fIpattern_list\fP's value shall consist
|
|
of one or more patterns separated by <newline>s;
|
|
the \fIpattern_file\fP's contents shall consist of one or more patterns
|
|
terminated by <newline>. By default, an input line
|
|
shall be selected if any pattern, treated as an entire basic regular
|
|
expression (BRE) as described in the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions,
|
|
matches any part of the line excluding the terminating <newline>;
|
|
a null BRE shall match every line. By default, each
|
|
selected input line shall be written to the standard output.
|
|
.LP
|
|
Regular expression matching shall be based on text lines. Since a
|
|
<newline> separates or terminates patterns (see the
|
|
\fB-e\fP and \fB-f\fP options below), regular expressions cannot contain
|
|
a <newline>. Similarly, since patterns are matched
|
|
against individual lines (excluding the terminating <newline>s) of
|
|
the input, there is no way for a pattern to match a
|
|
<newline> found in the input.
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fIgrep\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following options shall be supported:
|
|
.TP 7
|
|
\fB-E\fP
|
|
Match using extended regular expressions. Treat each pattern specified
|
|
as an ERE, as described in the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 9.4, Extended Regular Expressions.
|
|
If any entire ERE pattern matches some part of an input line excluding
|
|
the terminating <newline>, the line shall be matched.
|
|
A null ERE shall match every line.
|
|
.TP 7
|
|
\fB-F\fP
|
|
Match using fixed strings. Treat each pattern specified as a string
|
|
instead of a regular expression. If an input line contains
|
|
any of the patterns as a contiguous sequence of bytes, the line shall
|
|
be matched. A null string shall match every line.
|
|
.TP 7
|
|
\fB-c\fP
|
|
Write only a count of selected lines to standard output.
|
|
.TP 7
|
|
\fB-e\ \fP \fIpattern_list\fP
|
|
.sp
|
|
Specify one or more patterns to be used during the search for input.
|
|
The application shall ensure that patterns in
|
|
\fIpattern_list\fP are separated by a <newline>. A null pattern can
|
|
be specified by two adjacent <newline>s in
|
|
\fIpattern_list\fP. Unless the \fB-E\fP or \fB-F\fP option is also
|
|
specified, each pattern shall be treated as a BRE, as
|
|
described in the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
Section
|
|
9.3, Basic Regular Expressions. Multiple \fB-e\fP and \fB-f\fP options
|
|
shall be accepted by the \fIgrep\fP utility. All of
|
|
the specified patterns shall be used when matching lines, but the
|
|
order of evaluation is unspecified.
|
|
.TP 7
|
|
\fB-f\ \fP \fIpattern_file\fP
|
|
.sp
|
|
Read one or more patterns from the file named by the pathname \fIpattern_file\fP.
|
|
Patterns in \fIpattern_file\fP shall be
|
|
terminated by a <newline>. A null pattern can be specified by an empty
|
|
line in \fIpattern_file\fP. Unless the \fB-E\fP or
|
|
\fB-F\fP option is also specified, each pattern shall be treated as
|
|
a BRE, as described in the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions.
|
|
.TP 7
|
|
\fB-i\fP
|
|
Perform pattern matching in searches without regard to case; see the
|
|
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
Section 9.2, Regular Expression General Requirements.
|
|
.TP 7
|
|
\fB-l\fP
|
|
(The letter ell.) Write only the names of files containing selected
|
|
lines to standard output. Pathnames shall be written once
|
|
per file searched. If the standard input is searched, a pathname of
|
|
\fB"(standard input)"\fP shall be written, in the POSIX
|
|
locale. In other locales, \fB"standard input"\fP may be replaced by
|
|
something more appropriate in those locales.
|
|
.TP 7
|
|
\fB-n\fP
|
|
Precede each output line by its relative line number in the file,
|
|
each file starting at line 1. The line number counter shall
|
|
be reset for each file processed.
|
|
.TP 7
|
|
\fB-q\fP
|
|
Quiet. Nothing shall be written to the standard output, regardless
|
|
of matching lines. Exit with zero status if an input line is
|
|
selected.
|
|
.TP 7
|
|
\fB-s\fP
|
|
Suppress the error messages ordinarily written for nonexistent or
|
|
unreadable files. Other error messages shall not be
|
|
suppressed.
|
|
.TP 7
|
|
\fB-v\fP
|
|
Select lines not matching any of the specified patterns. If the \fB-v\fP
|
|
option is not specified, selected lines shall be
|
|
those that match any of the specified patterns.
|
|
.TP 7
|
|
\fB-x\fP
|
|
Consider only input lines that use all characters in the line excluding
|
|
the terminating <newline> to match an entire
|
|
fixed string or regular expression to be matching lines.
|
|
.sp
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIpattern_list\fP
|
|
Specify one or more patterns to be used during the search for input.
|
|
This operand shall be treated as if it were specified as
|
|
\fB-e\fP \fIpattern_list\fP.
|
|
.TP 7
|
|
\fIfile\fP
|
|
A pathname of a file to be searched for the patterns. If no \fIfile\fP
|
|
operands are specified, the standard input shall be
|
|
used.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
The standard input shall be used only if no \fIfile\fP operands are
|
|
specified. See the INPUT FILES section.
|
|
.SH INPUT FILES
|
|
.LP
|
|
The input files shall be text files.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIgrep\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_COLLATE\fP
|
|
.sp
|
|
Determine the locale for the behavior of ranges, equivalence classes,
|
|
and multi-character collating elements within regular
|
|
expressions.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments and input files) and
|
|
the behavior of character classes within regular
|
|
expressions.
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
If the \fB-l\fP option is in effect, and the \fB-q\fP option is not,
|
|
the following shall be written for each file containing
|
|
at least one selected input line:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s\\n", <\fP\fIfile\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Otherwise, if more than one \fIfile\fP argument appears, and \fB-q\fP
|
|
is not specified, the \fIgrep\fP utility shall prefix
|
|
each output line by:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s:", <\fP\fIfile\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The remainder of each output line shall depend on the other options
|
|
specified:
|
|
.IP " *" 3
|
|
If the \fB-c\fP option is in effect, the remainder of each output
|
|
line shall contain:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%d\\n", <\fP\fIcount\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " *" 3
|
|
Otherwise, if \fB-c\fP is not in effect and the \fB-n\fP option is
|
|
in effect, the following shall be written to standard
|
|
output:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%d:", <\fP\fIline number\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " *" 3
|
|
Finally, the following shall be written to standard output:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s", <\fP\fIselected-line contents\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
One or more lines were selected.
|
|
.TP 7
|
|
\ 1
|
|
No lines were selected.
|
|
.TP 7
|
|
>1
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
If the \fB-q\fP option is specified, the exit status shall be zero
|
|
if an input line is selected, even if an error was detected.
|
|
Otherwise, default actions shall be performed.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Care should be taken when using characters in \fIpattern_list\fP that
|
|
may also be meaningful to the command interpreter. It is
|
|
safest to enclose the entire \fIpattern_list\fP argument in single
|
|
quotes:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB'...'
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The \fB-e\fP \fIpattern_list\fP option has the same effect as the
|
|
\fIpattern_list\fP operand, but is useful when
|
|
\fIpattern_list\fP begins with the hyphen delimiter. It is also useful
|
|
when it is more convenient to provide multiple patterns as
|
|
separate arguments.
|
|
.LP
|
|
Multiple \fB-e\fP and \fB-f\fP options are accepted and \fIgrep\fP
|
|
uses all of the patterns it is given while matching input
|
|
text lines. (Note that the order of evaluation is not specified. If
|
|
an implementation finds a null string as a pattern, it is
|
|
allowed to use that pattern first, matching every line, and effectively
|
|
ignore any other patterns.)
|
|
.LP
|
|
The \fB-q\fP option provides a means of easily determining whether
|
|
or not a pattern (or string) exists in a group of files.
|
|
When searching several files, it provides a performance improvement
|
|
(because it can quit as soon as it finds the first match) and
|
|
requires less care by the user in choosing the set of files to supply
|
|
as arguments (because it exits zero if it finds a match even
|
|
if \fIgrep\fP detected an access or read error on earlier \fIfile\fP
|
|
operands).
|
|
.SH EXAMPLES
|
|
.IP " 1." 4
|
|
To find all uses of the word \fB"Posix"\fP (in any case) in file \fBtext.mm\fP
|
|
and write with line numbers:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBgrep -i -n posix text.mm
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " 2." 4
|
|
To find all empty lines in the standard input:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBgrep ^$
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
or:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBgrep -v .
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " 3." 4
|
|
Both of the following commands print all lines containing strings
|
|
\fB"abc"\fP or \fB"def"\fP or both:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBgrep -E 'abc|def'
|
|
.sp
|
|
|
|
grep -F 'abc
|
|
def'
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " 4." 4
|
|
Both of the following commands print all lines matching exactly \fB"abc"\fP
|
|
or \fB"def"\fP :
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBgrep -E '^abc$|^def$'
|
|
.sp
|
|
|
|
grep -F -x 'abc
|
|
def'
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.SH RATIONALE
|
|
.LP
|
|
This \fIgrep\fP has been enhanced in an upwards-compatible way to
|
|
provide the exact functionality of the historical
|
|
\fIegrep\fP and \fIfgrep\fP commands as well. It was the clear intention
|
|
of the standard developers to consolidate the three
|
|
\fIgrep\fPs into a single command.
|
|
.LP
|
|
The old \fIegrep\fP and \fIfgrep\fP commands are likely to be supported
|
|
for many years to come as implementation extensions,
|
|
allowing historical applications to operate unmodified.
|
|
.LP
|
|
Historical implementations usually silently ignored all but one of
|
|
multiply-specified \fB-e\fP and \fB-f\fP options, but were
|
|
not consistent as to which specification was actually used.
|
|
.LP
|
|
The \fB-b\fP option was omitted from the OPTIONS section because block
|
|
numbers are implementation-defined.
|
|
.LP
|
|
The System V restriction on using \fB-\fP to mean standard input was
|
|
omitted.
|
|
.LP
|
|
A definition of action taken when given a null BRE or ERE is specified.
|
|
This is an error condition in some historical
|
|
implementations.
|
|
.LP
|
|
The \fB-l\fP option previously indicated that its use was undefined
|
|
when no files were explicitly named. This behavior was
|
|
historical and placed an unnecessary restriction on future implementations.
|
|
It has been removed.
|
|
.LP
|
|
The historical BSD \fIgrep\fP \fB-s\fP option practice is easily duplicated
|
|
by redirecting standard output to
|
|
\fB/dev/null\fP. The \fB-s\fP option required here is from System
|
|
V.
|
|
.LP
|
|
The \fB-x\fP option, historically available only with \fIfgrep\fP,
|
|
is available here for all of the non-obsolescent
|
|
versions.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIsed\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|