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

NAME

12       grep — search a file for a pattern
13

SYNOPSIS

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

DESCRIPTION

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

OPTIONS

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

OPERANDS

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

STDIN

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

INPUT FILES

138       The input files shall be text files.
139

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

172       Default.
173

STDOUT

175       If  the -l option is in effect, the following shall be written for each
176       file containing at least one selected input line:
177
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
185           "%s:", <file>
186
187       The  remainder  of  each  output line shall depend on the other options
188       specified:
189
190        *  If the -c option is in effect, the remainder of  each  output  line
191           shall contain:
192
193
194               "%d\n", <count>
195
196        *  Otherwise,  if  -c is not in effect and the -n option is in effect,
197           the following shall be written to standard output:
198
199
200               "%d:", <line number>
201
202        *  Finally, the following shall be written to standard output:
203
204
205               "%s", <selected-line contents>
206

STDERR

208       The standard error shall be used only for diagnostic messages.
209

OUTPUT FILES

211       None.
212

EXTENDED DESCRIPTION

214       None.
215

EXIT STATUS

217       The following exit values shall be returned:
218
219        0    One or more lines were selected.
220
221        1    No lines were selected.
222
223       >1    An error occurred.
224

CONSEQUENCES OF ERRORS

226       If the -q option is specified, the exit status  shall  be  zero  if  an
227       input  line  is  selected,  even  if  an error was detected. Otherwise,
228       default actions shall be performed.
229
230       The following sections are informative.
231

APPLICATION USAGE

233       Care should be taken when using characters  in  pattern_list  that  may
234       also  be meaningful to the command interpreter. It is safest to enclose
235       the entire pattern_list argument in single-quotes:
236
237
238           '...'
239
240       The -e pattern_list option has the same effect as the pattern_list  op‐
241       erand,  but  is useful when pattern_list begins with the <hyphen-minus>
242       delimiter. It is also useful when it is more convenient to provide mul‐
243       tiple patterns as separate arguments.
244
245       Multiple  -e  and -f options are accepted and grep uses all of the pat‐
246       terns it is given while matching input  text  lines.   (Note  that  the
247       order of evaluation is not specified. If an implementation finds a null
248       string as a pattern, it is allowed to use that pattern first,  matching
249       every line, and effectively ignore any other patterns.)
250
251       The  -q  option provides a means of easily determining whether or not a
252       pattern (or string) exists in a group of files. When searching  several
253       files,  it  provides  a performance improvement (because it can quit as
254       soon as it finds the first match) and requires less care by the user in
255       choosing the set of files to supply as arguments (because it exits zero
256       if it finds a match even if grep detected an access or  read  error  on
257       earlier file operands).
258
259       When using grep to process pathnames, it is recommended that LC_ALL, or
260       at least LC_CTYPE and LC_COLLATE, are set to POSIX or C in the environ‐
261       ment, since pathnames can contain byte sequences that do not form valid
262       characters in some locales, in which case the utility's behavior  would
263       be  undefined.  In  the  POSIX  locale each byte is a valid single-byte
264       character, and therefore this problem is avoided.
265

EXAMPLES

267        1. To find all uses of the word "Posix" (in any case) in file  text.mm
268           and write with line numbers:
269
270
271               grep -i -n posix text.mm
272
273        2. To find all empty lines in the standard input:
274
275
276               grep ^$
277
278           or:
279
280
281               grep -v .
282
283        3. Both  of  the following commands print all lines containing strings
284           "abc" or "def" or both:
285
286
287               grep -E 'abc|def'
288
289               grep -F 'abc
290               def'
291
292        4. Both of the following commands print  all  lines  matching  exactly
293           "abc" or "def":
294
295
296               grep -E '^abc$|^def$'
297
298               grep -F -x 'abc
299               def'
300

RATIONALE

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

FUTURE DIRECTIONS

335       None.
336

SEE ALSO

338       sed
339
340       The  Base  Definitions  volume  of POSIX.1‐2017, Chapter 8, Environment
341       Variables, Chapter 9, Regular Expressions, Section 12.2, Utility Syntax
342       Guidelines
343
345       Portions  of  this text are reprinted and reproduced in electronic form
346       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
347       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
348       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
349       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
350       event of any discrepancy between this version and the original IEEE and
351       The  Open Group Standard, the original IEEE and The Open Group Standard
352       is the referee document. The original Standard can be  obtained  online
353       at http://www.opengroup.org/unix/online.html .
354
355       Any  typographical  or  formatting  errors that appear in this page are
356       most likely to have been introduced during the conversion of the source
357       files  to  man page format. To report such errors, see https://www.ker
358       nel.org/doc/man-pages/reporting_bugs.html .
359
360
361
362IEEE/The Open Group                  2017                             GREP(1P)
Impressum