# grep

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           grep — search a file for a pattern
    


## SYNOPSIS



           grep **[** -E|-F**] [** -c|-l|-q**] [** -insvx**]** -e _pattern_list_
               **[** -e _pattern_list_**]**... **[** -f _pattern_file_**]**... **[**_file_...**]**
    
           grep **[** -E|-F**] [** -c|-l|-q**] [** -insvx**] [** -e _pattern_list_**]...**
               -f _pattern_file_ **[** -f _pattern_file_**]**... **[**_file_...**]**
    
           grep **[** -E|-F**] [** -c|-l|-q**] [** -insvx**]**_pattern_list_ **[**_file_...**]**
    


## DESCRIPTION



           The _grep_ 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 **-e** option, **-f** option, or the _pattern_list_ operand. The
           _pattern_list_ 's value shall consist of one or more patterns
           separated by <newline> characters; the _pattern_file_ 's contents
           shall consist of one or more patterns terminated by a <newline>
           character. 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 POSIX.1‐2017, _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.
    
           Regular expression matching shall be based on text lines. Since a
           <newline> separates or terminates patterns (see the **-e** and **-f**
           options below), regular expressions cannot contain a <newline>.
           Similarly, since patterns are matched against individual lines
           (excluding the terminating <newline> characters) of the input,
           there is no way for a pattern to match a <newline> found in the
           input.
    


## OPTIONS



           The _grep_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported:
    
           **-E** Match using extended regular expressions.  Treat each
                     pattern specified as an ERE, as described in the Base
                     Definitions volume of POSIX.1‐2017, _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.
    
           **-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 shall be matched.  A null
                     string shall match 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.  The application shall ensure that
                     patterns in _pattern_list_ are separated by a <newline>.
                     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 shall be
                     treated as a BRE, as described in the Base Definitions
                     volume of POSIX.1‐2017, _Section 9.3_ , _Basic Regular_
                     _Expressions_.  Multiple **-e** and **-f** options shall be
                     accepted by the _grep_ utility. All of the specified
                     patterns shall be 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_ shall
                     be terminated by a <newline>.  A null pattern can be
                     specified by an empty line in _pattern_file_.  Unless the
                     **-E** or **-F** option is also specified, each pattern shall be
                     treated as a BRE, as described in the Base Definitions
                     volume of POSIX.1‐2017, _Section 9.3_ , _Basic Regular_
                     _Expressions_.
    
           **-i** Perform pattern matching in searches without regard to
                     case; see the Base Definitions volume of POSIX.1‐2017,
                     _Section 9.2_ , _Regular Expression General Requirements_.
    
           **-l**(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 **"(standard** input)" shall
                     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 shall be reset for each file processed.
    
           **-q** Quiet. Nothing shall be written 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
                     nonexistent or unreadable files. Other error messages
                     shall not be suppressed.
    
           **-v** Select lines not matching any of the specified patterns.
                     If the **-v** option is not specified, selected lines shall
                     be those that match any of the specified patterns.
    
           **-x** 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.
    


## OPERANDS



           The following operands shall be supported:
    
           _pattern_list_
                     Specify one or more patterns to be used during the
                     search for input.  This operand shall be 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 shall
                     be used.
    


## STDIN



           The standard input shall be used if no _file_ operands are
           specified, and shall be used if a _file_ operand is **'-'** and the
           implementation treats the **'-'** as meaning standard input.
           Otherwise, the standard input shall not be used.  See the INPUT
           FILES section.
    


## INPUT FILES



           The input files shall be text files.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _grep_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_COLLATE_
                     Determine the locale for the behavior 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-byte as opposed to multi-byte characters in
                     arguments and input files) and the behavior 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 catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           If the **-l** option is in effect, the following shall 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 shall prefix each output line by:
    
               "%s:", <_file_ >
    
           The remainder of each output line shall depend on the other
           options specified:
    
            *  If the **-c** option is in effect, the remainder of each output
               line shall contain:
    
                   "%d\n", <_count_ >
    
            *  Otherwise, if **-c** is not in effect and the **-n** option is in
               effect, the following shall be written to standard output:
    
                   "%d:", <_line number_ >
    
            *  Finally, the following shall be written to standard output:
    
                   "%s", <_selected-line contents_ >
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be 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 shall be zero if an
           input line is selected, even if an error was detected. Otherwise,
           default actions shall be performed.
    
           _The following sections are informative._
    


## 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-
           minus> 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_ 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.)
    
           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 exits zero if it finds a match
           even if _grep_ detected an access or read error on earlier _file_
           operands).
    
           When using _grep_ to process pathnames, it is recommended that
           LC_ALL, or at least LC_CTYPE and LC_COLLATE, are set to POSIX or C
           in the environment, since pathnames can contain byte sequences
           that do not form valid characters in some locales, in which case
           the utility's behavior would be undefined. In the POSIX locale
           each byte is a valid single-byte character, and therefore this
           problem is avoided.
    


## 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'
    


## RATIONALE



           This _grep_ has been enhanced in an upwards-compatible way to
           provide the exact functionality of the historical _egrep_ and _fgrep_
           commands as well. It was the clear intention of the standard
           developers to consolidate the three _grep_ s into a single command.
    
           The old _egrep_ and _fgrep_ commands are likely to be supported for
           many years to come as implementation extensions, allowing
           historical applications to operate unmodified.
    
           Historical implementations usually silently ignored all but one of
           multiply-specified **-e** and **-f** options, but were not consistent as
           to which specification was actually used.
    
           The **-b** option was omitted from the OPTIONS section because block
           numbers are implementation-defined.
    
           The System V restriction on using **-** to mean standard input was
           omitted.
    
           A definition of action taken when given a null BRE or ERE is
           specified.  This is an error condition in some historical
           implementations.
    
           The **-l** 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.
    
           The historical BSD _grep_ **-s** option practice is easily duplicated by
           redirecting standard output to **/dev/null**.  The **-s** option required
           here is from System V.
    
           The **-x** option, historically available only with _fgrep_ , is
           available here for all of the non-obsolescent versions.
    


## FUTURE DIRECTIONS



           None.
    


* * *