1GREP(1P)                   POSIX Programmer's Manual                  GREP(1P)
2
3
4

PROLOG

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

NAME

13       grep — search a file for a pattern
14

SYNOPSIS

16       grep [−E|−F] [−c|−l|−q] [−insvx] −e pattern_list
17           [−e pattern_list]... [−f pattern_file]... [file...]
18
19       grep [−E|−F] [−c|−l|−q] [−insvx] [−e pattern_list]...
20           −f pattern_file [−f pattern_file]... [file...]
21
22       grep [−E|−F] [−c|−l|−q] [−insvx] pattern_list [file...]
23

DESCRIPTION

25       The grep utility shall search the input files, selecting lines matching
26       one  or  more  patterns;  the  types  of patterns are controlled by the
27       options specified. The patterns are specified  by  the  −e  option,  −f
28       option,  or  the  pattern_list  operand. The pattern_list's value shall
29       consist of one or more patterns separated by <newline> characters;  the
30       pattern_file's  contents  shall  consist of one or more patterns termi‐
31       nated by a <newline> character. By default,  an  input  line  shall  be
32       selected  if any pattern, treated as an entire basic regular expression
33       (BRE) as described in the Base Definitions volume of POSIX.1‐2008, Sec‐
34       tion  9.3,  Basic  Regular  Expressions,  matches  any part of the line
35       excluding the terminating <newline>; a null BRE shall match every line.
36       By  default,  each selected input line shall be written to the standard
37       output.
38
39       Regular expression matching shall be based on text lines. Since a <new‐
40       line>  separates  or  terminates  patterns  (see  the −e and −f options
41       below), regular expressions cannot  contain  a  <newline>.   Similarly,
42       since patterns are matched against individual lines (excluding the ter‐
43       minating <newline> characters) of the input, there is no way for a pat‐
44       tern to match a <newline> found in the input.
45

OPTIONS

47       The  grep  utility  shall  conform  to  the  Base Definitions volume of
48       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
49
50       The following options shall be supported:
51
52       −E        Match using extended regular expressions.  Treat each pattern
53                 specified  as  an  ERE,  as described in the Base Definitions
54                 volume of POSIX.1‐2008, Section 9.4, Extended Regular Expres‐
55                 sions.   If  any  entire  ERE pattern matches some part of an
56                 input line excluding  the  terminating  <newline>,  the  line
57                 shall be matched. A null ERE shall match every line.
58
59       −F        Match  using fixed strings. Treat each pattern specified as a
60                 string instead of a regular expression. If an input line con‐
61                 tains  any of the patterns as a contiguous sequence of bytes,
62                 the line shall be matched.  A null string shall  match  every
63                 line.
64
65       −c        Write only a count of selected lines to standard output.
66
67       −e pattern_list
68                 Specify one or more patterns to be used during the search for
69                 input.  The application shall ensure that  patterns  in  pat‐
70                 tern_list  are  separated by a <newline>.  A null pattern can
71                 be specified by two adjacent  <newline>  characters  in  pat‐
72                 tern_list.   Unless  the  −E  or −F option is also specified,
73                 each pattern shall be treated as a BRE, as described  in  the
74                 Base  Definitions  volume of POSIX.1‐2008, Section 9.3, Basic
75                 Regular Expressions.  Multiple −e and  −f  options  shall  be
76                 accepted  by  the grep utility. All of the specified patterns
77                 shall be used when matching lines, but the order  of  evalua‐
78                 tion is unspecified.
79
80       −f pattern_file
81                 Read one or more patterns from the file named by the pathname
82                 pattern_file.  Patterns in pattern_file shall  be  terminated
83                 by  a <newline>.  A null pattern can be specified by an empty
84                 line in pattern_file.  Unless the −E or  −F  option  is  also
85                 specified,  each  pattern  shall  be  treated  as  a  BRE, as
86                 described in the Base  Definitions  volume  of  POSIX.1‐2008,
87                 Section 9.3, Basic Regular Expressions.
88
89       −i        Perform  pattern matching in searches without regard to case;
90                 see the Base Definitions volume of POSIX.1‐2008, Section 9.2,
91                 Regular Expression General Requirements.
92
93       −l        (The  letter  ell.)  Write only the names of files containing
94                 selected lines to standard output. Pathnames shall be written
95                 once  per file searched. If the standard input is searched, a
96                 pathname of "(standardinput)" shall be written, in the  POSIX
97                 locale.  In other locales, "standardinput" may be replaced by
98                 something more appropriate in those locales.
99
100       −n        Precede each output line by its relative line number  in  the
101                 file,  each  file starting at line 1. The line number counter
102                 shall be reset for each file processed.
103
104       −q        Quiet. Nothing shall  be  written  to  the  standard  output,
105                 regardless  of  matching  lines.  Exit with zero status if an
106                 input line is selected.
107
108       −s        Suppress the error messages ordinarily written  for  nonexis‐
109                 tent  or  unreadable files. Other error messages shall not be
110                 suppressed.
111
112       −v        Select lines not matching any of the specified  patterns.  If
113                 the −v option is not specified, selected lines shall be those
114                 that match any of the specified patterns.
115
116       −x        Consider only input lines that use all characters in the line
117                 excluding  the terminating <newline> to match an entire fixed
118                 string or regular expression to be matching lines.
119

OPERANDS

121       The following operands shall be supported:
122
123       pattern_list
124                 Specify one or more patterns to be used during the search for
125                 input.  This operand shall be treated as if it were specified
126                 as −e pattern_list.
127
128       file      A pathname of a file to be searched for the patterns.  If  no
129                 file  operands  are  specified,  the  standard input shall be
130                 used.
131

STDIN

133       The standard input shall be used if no file operands are specified, and
134       shall  be  used  if a file operand is '−' and the implementation treats
135       the '−' as meaning standard input.  Otherwise, the standard input shall
136       not be used.  See the INPUT FILES section.
137

INPUT FILES

139       The input files shall be text files.
140

ENVIRONMENT VARIABLES

142       The following environment variables shall affect the execution of grep:
143
144       LANG      Provide  a  default  value for the internationalization vari‐
145                 ables that are unset or null. (See the Base Definitions  vol‐
146                 ume  of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
147                 ables for the precedence  of  internationalization  variables
148                 used to determine the values of locale categories.)
149
150       LC_ALL    If  set  to  a non-empty string value, override the values of
151                 all the other internationalization variables.
152
153       LC_COLLATE
154                 Determine the locale for the behavior of ranges,  equivalence
155                 classes,  and multi-character collating elements within regu‐
156                 lar expressions.
157
158       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
159                 bytes of text data as characters (for example, single-byte as
160                 opposed to  multi-byte  characters  in  arguments  and  input
161                 files)  and  the behavior of character classes within regular
162                 expressions.
163
164       LC_MESSAGES
165                 Determine the locale that should be used to affect the format
166                 and  contents  of  diagnostic  messages  written  to standard
167                 error.
168
169       NLSPATH   Determine the location of message catalogs for the processing
170                 of LC_MESSAGES.
171

ASYNCHRONOUS EVENTS

173       Default.
174

STDOUT

176       If  the −l option is in effect, the following shall be written for each
177       file containing at least one selected input line:
178
179           "%s\n", <file>
180
181       Otherwise, if more than one file argument appears, and −q is not speci‐
182       fied, the grep utility shall prefix each output line by:
183
184           "%s:", <file>
185
186       The  remainder  of  each  output line shall depend on the other options
187       specified:
188
189        *  If the −c option is in effect, the remainder of  each  output  line
190           shall contain:
191
192               "%d\n", <count>
193
194        *  Otherwise,  if  −c is not in effect and the −n option is in effect,
195           the following shall be written to standard output:
196
197               "%d:", <line number>
198
199        *  Finally, the following shall be written to standard output:
200
201               "%s", <selected-line contents>
202

STDERR

204       The standard error shall be used only for diagnostic messages.
205

OUTPUT FILES

207       None.
208

EXTENDED DESCRIPTION

210       None.
211

EXIT STATUS

213       The following exit values shall be returned:
214
215        0    One or more lines were selected.
216
217        1    No lines were selected.
218
219       >1    An error occurred.
220

CONSEQUENCES OF ERRORS

222       If the −q option is specified, the exit status  shall  be  zero  if  an
223       input  line  is  selected,  even  if  an error was detected. Otherwise,
224       default actions shall be performed.
225
226       The following sections are informative.
227

APPLICATION USAGE

229       Care should be taken when using characters  in  pattern_list  that  may
230       also  be meaningful to the command interpreter. It is safest to enclose
231       the entire pattern_list argument in single-quotes:
232
233           '...'
234
235       The −e pattern_list option has the same effect as the pattern_list  op‐
236       erand,  but is useful when pattern_list begins with the <hyphen> delim‐
237       iter. It is also useful when it is more convenient to provide  multiple
238       patterns as separate arguments.
239
240       Multiple  −e  and −f options are accepted and grep uses all of the pat‐
241       terns it is given while matching input  text  lines.   (Note  that  the
242       order of evaluation is not specified. If an implementation finds a null
243       string as a pattern, it is allowed to use that pattern first,  matching
244       every line, and effectively ignore any other patterns.)
245
246       The  −q  option provides a means of easily determining whether or not a
247       pattern (or string) exists in a group of files. When searching  several
248       files,  it  provides  a performance improvement (because it can quit as
249       soon as it finds the first match) and requires less care by the user in
250       choosing the set of files to supply as arguments (because it exits zero
251       if it finds a match even if grep detected an access or  read  error  on
252       earlier file operands).
253

EXAMPLES

255        1. To  find all uses of the word "Posix" (in any case) in file text.mm
256           and write with line numbers:
257
258               grep −i −n posix text.mm
259
260        2. To find all empty lines in the standard input:
261
262               grep ^$
263
264           or:
265
266               grep −v .
267
268        3. Both of the following commands print all lines  containing  strings
269           "abc" or "def" or both:
270
271               grep −E 'abc|def'
272
273               grep −F 'abc
274               def'
275
276        4. Both  of  the  following  commands print all lines matching exactly
277           "abc" or "def":
278
279               grep −E '^abc$|^def$'
280
281               grep −F −x 'abc
282               def'
283

RATIONALE

285       This grep has been enhanced in an upwards-compatible way to provide the
286       exact functionality of the historical egrep and fgrep commands as well.
287       It was the clear intention of the standard  developers  to  consolidate
288       the three greps into a single command.
289
290       The  old  egrep  and fgrep commands are likely to be supported for many
291       years to come as implementation extensions, allowing historical  appli‐
292       cations to operate unmodified.
293
294       Historical implementations usually silently ignored all but one of mul‐
295       tiply-specified −e and −f options, but were not consistent as to  which
296       specification was actually used.
297
298       The  −b  option was omitted from the OPTIONS section because block num‐
299       bers are implementation-defined.
300
301       The System V restriction on using to mean standard input was omitted.
302
303       A definition of action taken when given a null BRE or ERE is specified.
304       This is an error condition in some historical implementations.
305
306       The  −l  option previously indicated that its use was undefined when no
307       files were explicitly named. This behavior was historical and placed an
308       unnecessary restriction on future implementations. It has been removed.
309
310       The  historical  BSD  grep  −s  option practice is easily duplicated by
311       redirecting standard output to /dev/null.  The −s option required  here
312       is from System V.
313
314       The  −x  option,  historically  available only with fgrep, is available
315       here for all of the non-obsolescent versions.
316

FUTURE DIRECTIONS

318       None.
319

SEE ALSO

321       sed
322
323       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
324       Variables, Chapter 9, Regular Expressions, Section 12.2, Utility Syntax
325       Guidelines
326
328       Portions of this text are reprinted and reproduced in  electronic  form
329       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
330       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
331       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
332       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
333       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
334       event of any discrepancy between this version and the original IEEE and
335       The  Open Group Standard, the original IEEE and The Open Group Standard
336       is the referee document. The original Standard can be  obtained  online
337       at http://www.unix.org/online.html .
338
339       Any  typographical  or  formatting  errors that appear in this page are
340       most likely to have been introduced during the conversion of the source
341       files  to  man page format. To report such errors, see https://www.ker
342       nel.org/doc/man-pages/reporting_bugs.html .
343
344
345
346IEEE/The Open Group                  2013                             GREP(1P)
Impressum