grep - Search a file for a specified pattern

Format

grep [-E|-F] [] [-A|-P|-C num] [-S string]
[-W option[option] ... [-e pattern] ... [-f patternfile] ... [pattern] [file … file ...]
egrep [-BNbcilnqsvx] [-A|-P|-C num] [-Sstring]
[-W option[option] ... [-e pattern] ... [-f patternfile] ... [pattern] [file ... file ...]
fgrep [-BNbcilnqsvx] [-A|-P|-C num] [-Sstring]
[-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.

-A num

Displays num lines of trailing context after the lines are matched.

-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 num

Displays num lines of leading and trailing output context.

-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 that are 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 that are being matched.

-l

Lists only the file names that contain the matching lines.

-N

When -A, -C or -P have been specified, does not print a separator between groups of lines.

-n

Precedes each matched line with its fileline number.

-P num

Displays num lines of leading context before matching lines.

-q

Suppresses output and returns the appropriate return code.

-S string

When -A, -C or -P have been specified, displays string instead of "--" between groups of lines.

-s

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

-v

Complements the sense of the match. That is, all lines that do not match a pattern are displayed.

-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.

If you are 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.

If filecodeset or pgmcodeset is specified, then automatic conversion is turned off 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.

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 that mentions an astrological element:
```
egrep "earth|air|fire|water" astro.log
```
To display every line in a text file that contains the string ".com":
```
fgrep '.com' myTextFile
```
To display every line in a text file that contains the string ".com" or ".org":
```
egrep '\.com|\.org' myTextFile
```
In this example, the period (.) is escaped by the \ character to ensure that 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 that contain the strings "become" or "forge").
To display every line in a text file that starts with "Hello" or "hello":
```
grep '^[Hh]ello' myTextFile
```
To display every line in a text file that contains ASCII characters that do 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 that contains EBCDIC characters having the string "path", regardless of case and assuming that automatic conversion was enabled but the text file is incorrectly tagged as UTF-8:
```
grep -Bi 'path' myMisTaggedFile
```
In this example, lines that contain strings such as "path", "Path", "PATH", and "pAtH" would match.
To display the lines either before or after the matching lines:
- To print 10 lines after the matching lines:
```
grep -A 10 'hello' myTextFile
```
- To print 10 lines before the matching lines:
```
grep -P 10 'hello' myTextFile
```
- To print 10 lines before and after the matching lines, using group separator "**" instead of "--":
```
grep -C 10 -S "**" 'hello' myTextFile
```

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 conditions:

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 pattern might be too 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 might 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 the 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.