grep — Search a file for a specified pattern

Format

grep [–E|–F] [–Bbcilnqsvx ] [-W option[,option]...] [–e pattern] … [–f patternfile] … [pattern] [file …file …]
egrep [–Bbcilnqsvx] [-W option[,option]...] [–e pattern] … [–f patternfile] … [pattern] [file …file …]
fgrep [–Bbcilnqsvx] [-W option[,option]...] [–e pattern] … [–f patternfile] … [pattern] [file …file …]

Description

fgrep searches files for one or more pattern arguments. It does not use regular expressions; instead, it uses fixed string comparisons to find matching lines of text in the input.

egrep works in a similar way, but uses extended regular expression matching. (For information about regular expression matching, see Regular expressions (regexp).) If you include special characters in patterns typed on the command line, escape them by enclosing them in apostrophes to prevent inadvertent misinterpretation by the shell or command interpreter. To match a character that is special to egrep, put a backslash (\) in front of the character. It is usually simpler to use fgrep when you do not need special pattern matching.

grep is a combination of fgrep and egrep. If you do not specify either –E or –F, grep behaves like egrep, but matches basic regular expressions instead of extended ones. You can specify a pattern to search with either the –e or –f option. If you do not specify either option, grep (or egrep or fgrep) takes the first non-option argument as the pattern for which to search. If grep finds a line that matches a pattern, it displays the entire line. If you specify multiple input files, the name of the current file precedes each output line.

If you do not specify any files, the command reads from the standard input (stdin).

Options

grep accepts all the following options while egrep and fgrep accept all but the –E and –F options.

–B

Disables the automatic conversion of tagged files. This option is ignored if the filecodeset or pgmcodeset options (-W option) are specified.

–b

Precedes each matched line with its file block number.

–c

Displays only a count of the number of matched lines and not the lines themselves.

–E

Matches using extended regular expressions (causes grep to behave like egrep).

–e pattern

Specifies one or more patterns separated by newlines for which grep is to search.

You can indicate each pattern with a separate –e option character, or with newlines within pattern. For example, the following two commands are equivalent:

grep –e pattern_one –epattern_two file
grep –e 'pattern_one
pattern_two' file

–F

Matches using fixed strings (causes grep to behave like fgrep).

–f patternfile

Reads one or more patterns from patternfile. Patterns in patternfile are separated by newlines.

–i

Ignores the case of the strings being matched.

–l

Lists only the filenames that contain the matching lines.

–n

Precedes each matched line with its fileline number.

–q

Suppresses output and returns the appropriate return code.

–s

Suppresses the display of any error messages for nonexistent or unreadable files.

–v

Complements the sense of the match—that is, displays all lines not matching a pattern.

-W option[,option]...

Specifies z/OS-specific options. The option keywords are case-sensitive. Possible options are:

filecodeset=codeset

Performs text conversion from one code set to another when reading from the file. The coded character set of the file is codeset. codeset can be a code set name known to the system or a numeric coded character set identifier (CCSID). Note that the command iconv -l lists existing CCSIDs along with their corresponding code set names. The filecodeset and pgmcodeset options can be used on files with any file tag.

If pgmcodeset is specified but filecodeset is omitted, then the default file code set is ISO8859-1 even if the file is tagged with a different code set. If neither filecodeset nor pgmcodeset is specified, text conversion will not occur unless automatic conversion is enabled or the _TEXT_CONV environment variable indicates text conversion. For more information about text conversion, see Controlling text conversion for z/OS UNIX shell commands.

If filecodeset or pgmcodeset is specified, then automatic conversion is disabled for this command invocation and the -B option is ignored if it is also specified. See z/OS UNIX System Services Planning for more information about automatic conversion.

When specifying values for filecodeset, use the values that Unicode Service supports. For more information about supported code sets, see z/OS Unicode Services User's Guide and Reference.

pgmcodeset=codeset

Performs text conversion from one code set to another when reading from the file. The coded character set of the program (command) is codeset. codeset can be a code set name known to the system or a numeric coded character set identifier (CCSID). Note that the command iconv -l lists existing CCSIDs along with their corresponding code set names. The filecodeset and pgmcodeset options can be used on files with any file tag.

If filecodeset is specified but pgmcodeset is omitted, then the default program code set is IBM-1047. If neither filecodeset nor pgmcodeset is specified, text conversion will not occur unless automatic conversion is enabled or the _TEXT_CONV environment variable indicates text conversion. For more information about text conversion, see Controlling text conversion for z/OS UNIX shell commands.

Restriction: The only supported values for pgmcodeset are IBM-1047 and 1047.

–x

Requires a string to match an entire line.

Examples

To display every line mentioning an astrological element:
```
egrep "earth|air|fire|water" astro.log
```
To display every line in a text file containing the string ".com":
```
fgrep '.com' myTextFile
```
To display every line in a text file containing the string ".com" or ".org":
```
egrep '\.com|\.org' myTextFile
```
In this example, the period (.) is escaped by the \ character to ensure the period is not treated as a special character. Otherwise, any string with the letters "com" or "org" preceded by any character would match (for example, lines containing the strings "become" or "forge").
To display every line in a text file starting with "Hello" or "hello":
```
grep '^[Hh]ello' myTextFile
```
To display every line in a text file containing ASCII characters that does not start with the # character, assuming that:
- The text file is untagged and you do not want to tag it or enable automatic conversion, and
- You cannot alter the tag (for example, you are displaying an untagged public text file or a read-only text file):
```
grep -W filecodeset=ISO8859-1,pgmcodeset=IBM-1047 -v '^#' myAsciiFile
```
To display every line in a text file containing EBCDIC characters that has the string "path", regardless of case and assuming that automatic conversion has been enabled but the text file is incorrectly tagged as UTF-8:
```
grep -Bi 'path' myMisTaggedFile
```
In this example, lines containing strings such as "path", "Path", "PATH", and "pAtH" would match.

Localization

grep uses the following localization environment variables:

LANG
LC_ALL
LC_COLLATE
LC_CTYPE
LC_MESSAGES
LC_SYNTAX
NLSPATH

See Localization for more information.

Environment variables

grep uses the following environment variable:

_TEXT_CONV: Contains text conversion information for the command. The text conversion information is not used when either the -B option or the filecodeset or pgmcodeset option (-W option) is specified. For more information about text conversion, see Controlling text conversion for z/OS UNIX shell commands.

Exit values

0

At least one match for pattern was found.

1

No matches for pattern were found.

2

Failure due to any of the following:

The –e option was missing pattern.
The –f option was missing patternfile.
Out of memory for input or to hold a pattern.
patternfile could not be opened.
Incorrect regular expression.
Incorrect command-line option.
The command line had too few arguments.
The input file could not be opened.
The code set is not valid
Could not turn off automatic conversion
Could not perform requested text conversion

If the program fails to open one input file, it tries to go on to look at any remaining input files, but it returns 2 even if it succeeds in finding matches in other input files.

Messages

Possible error messages include:

input lines truncated—result questionable: One or more input lines were longer than grep could handle; the line has been truncated or split into two lines. Shorten the line or lines, if possible. This message does not affect the exit status.
out of space for pattern string: grep did not have enough memory available to store the code needed to work with the given pattern (regular expression). The usual cause is that the pattern is very complex. Make the pattern simpler, or try to release memory so that grep has more space to work with.

Limits

The longest input record (line) is restricted by the system variable LINE_MAX. It is always at least 2048 bytes. fgrep may be able to handle lines longer than LINE_MAX. Longer lines are treated as two or more records.

Portability

POSIX.2, X/Open Portability Guide, UNIX systems.

Only the grep command is part of th POSIX and X/Open standards. The egrep and fgrep commands are extensions. The –B, –b, and –W options are extensions of the POSIX standard.

Related information

ed, find

See Regular expressions (regexp) for more information about regexp.