The Single UNIX ® Specification, Version 2
Copyright © 1997 The Open Group

 NAME

grep - search a file for a pattern

 SYNOPSIS



grep [ -E| -F][ -c| -l| -q ][-insvx] -e pattern_list...
[-f pattern_file]...[file...]

grep [ -E| -F][ -c| -l| -q ][-insvx][-e pattern_list...
-f pattern_file...[file...]

grep [ -E| -F][ -c| -l| -q ][-insvx] pattern_list[file...]

 DESCRIPTION

The grep utility searches 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 -e option, -f option, or the pattern_list operand. The pattern_list's value consists of one or more patterns separated by newline characters; the pattern_file's contents consist of one or more patterns terminated by newline characters. By default, an input line will be selected if any pattern, treated as an entire basic regular expression (BRE) as described in the XBD specification, Basic Regular Expressions  , matches any part of the line; a null BRE will match every line. By default, each selected input line will be written to the standard output.

Regular expression matching will be based on text lines. Since a newline character separates or terminates patterns (see the -e and -f options below), regular expressions cannot contain a newline character. Similarly, since patterns are matched against individual lines of the input, there is no way for a pattern to match a newline character found in the input.

 OPTIONS

The grep utility supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-E
Match using extended regular expressions. Treat each pattern specified as an ERE, as described in the XBD specification, Extended Regular Expressions  . If any entire ERE pattern matches an input line, the line will be matched. A null ERE matches every line.
-F
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 will be matched. A null string matches every line.
-c
Write only a count of selected lines to standard output.
-e pattern_list
Specify one or more patterns to be used during the search for input. Patterns in pattern_list must be separated by a newline character. A null pattern can be specified by two adjacent newline characters in pattern_list. Unless the -E or -F option is also specified, each pattern will be treated as a BRE, as described in the XBD specification, Basic Regular Expressions  . Multiple -e and -f options are accepted by the grep utility. All of the specified patterns are used when matching lines, but the order of evaluation is unspecified.
-f pattern_file
Read one or more patterns from the file named by the pathname pattern_file. Patterns in pattern_file are terminated by a newline character. A null pattern can be specified by an empty line in pattern_file. Unless the -E or -F option is also specified, each pattern will be treated as a BRE, as described in the XBD specification, Basic Regular Expressions  .
-i
Perform pattern matching in searches without regard to case. See the XBD specification, Regular Expression General Requirements  .
-l
(The letter ell.) Write only the names of files containing selected lines to standard output. Pathnames are written once per file searched. If the standard input is searched, a pathname of (standard input) will be written, in the POSIX locale. In other locales, standard input may be replaced by something more appropriate in those locales.
-n
Precede each output line by its relative line number in the file, each file starting at line 1. The line number counter will be reset for each file processed.
-q
Quiet. Do not write anything to the standard output, regardless of matching lines. Exit with zero status if an input line is selected.
-s
Suppress the error messages ordinarily written for non-existent or unreadable files. Other error messages will not be suppressed.
-v
Select lines not matching any of the specified patterns. If the -v option is not specified, selected lines will be those that match any of the specified patterns.
-x
Consider only input lines that use all characters in the line to match an entire fixed string or regular expression to be matching lines.

 OPERANDS

The following operands are supported:
pattern
Specify one or more patterns to be used during the search for input. This operand is treated as if it were specified as -e pattern_list.
file
A pathname of a file to be searched for the patterns. If no file operands are specified, the standard input will be used.

 STDIN

The standard input will be used only if no file operands are specified. See the INPUT FILES section.

 INPUT FILES

The input files must be text files.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of grep:
LANG
Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.
LC_ALL
If set to a non-empty string value, override the values of all the other internationalisation variables.
LC_COLLATE
Determine the locale for the behaviour of ranges, equivalence classes and multi-character collating elements within regular expressions.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files) and the behaviour of character classes within regular expressions.
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
NLSPATH
Determine the location of message catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

If the -l option is in effect, and the -q option is not, the following will be written for each file containing at least one selected input line:

"%s\n", file

Otherwise, if more than one file argument appears, and -q is not specified, the grep utility will prefix each output line by:

"%s:", file

The remainder of each output line depends on the other options specified:

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

None.

 EXIT STATUS

The following exit values are returned:
0
One or more lines were selected.
1
No lines were selected.
>1
An error occurred.

 CONSEQUENCES OF ERRORS

If the -q option is specified, the exit status will be zero if an input line is selected, even if an error was detected. Otherwise, default actions will be performed.

 APPLICATION USAGE

Care should be taken when using characters in pattern_list that may also be meaningful to the command interpreter. It is safest to enclose the entire pattern_list argument in single quotes:

'...'

The -e pattern_list option has the same effect as the pattern_list operand, but is useful when pattern_list begins with the hyphen delimiter. It is also useful when it is more convenient to provide multiple patterns as separate arguments.

Multiple -e and -f options are accepted and grep will use 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.)

The -q 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 will exit zero if it finds a match even if grep detected an access or read error on earlier file operands).

 EXAMPLES

  1. To find all uses of the word Posix (in any case) in file text.mm and write with line numbers:
    
    grep -i -n posix text.mm
    
    

  2. To find all empty lines in the standard input:
    
    grep ^$
    
    

    or:

    
    grep -v .
    
    

  3. Both of the following commands print all lines containing strings abc or def or both:
    
    grep -E 'abc
    def'
    
    grep -F 'abc
    def'
    
    

  4. Both of the following commands print all lines matching exactly abc or def:
    
    grep -E '^abc$
    ^def$'
    
    grep -F -x 'abc
    def'
    
    

 FUTURE DIRECTIONS

None.

 SEE ALSO

sed.

UNIX ® is a registered Trademark of The Open Group.
Copyright © 1997 The Open Group
[ Main Index | XSH | XCU | XBD | XCURSES | XNS ]