1GREP(1P) POSIX Programmer's Manual GREP(1P)
2
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
12 grep — search a file for a pattern
13
15 grep [-E|-F] [-c|-l|-q] [-insvx] -e pattern_list
16 [-e pattern_list]... [-f pattern_file]... [file...]
17 grep [-E|-F] [-c|-l|-q] [-insvx] [-e pattern_list]...
19 -f pattern_file [-f pattern_file]... [file...]
20 grep [-E|-F] [-c|-l|-q] [-insvx] pattern_list [file...]
22
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 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
46 The grep utility shall conform to the Base Definitions volume of
47 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
48 The following options shall be supported:
50 -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 -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 -c Write only a count of selected lines to standard output.
65 -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 -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 -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 -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 -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 -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 -s Suppress the error messages ordinarily written for nonexis‐
108 tent or unreadable files. Other error messages shall not be
109 suppressed.
110 -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 -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
120 The following operands shall be supported:
121 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 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
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
138 The input files shall be text files.
139
141 The following environment variables shall affect the execution of grep:
142 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 LC_ALL If set to a non-empty string value, override the values of
150 all the other internationalization variables.
151 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 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 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 NLSPATH Determine the location of message catalogs for the processing
169 of LC_MESSAGES.
170
172 Default.
173
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 "%s\n", <file>
180 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 "%s:", <file>
186 The remainder of each output line shall depend on the other options
188 specified:
189 * If the -c option is in effect, the remainder of each output line
191 shall contain:
192 "%d\n", <count>
195 * Otherwise, if -c is not in effect and the -n option is in effect,
197 the following shall be written to standard output:
198 "%d:", <line number>
201 * Finally, the following shall be written to standard output:
203 "%s", <selected-line contents>
206
208 The standard error shall be used only for diagnostic messages.
209
211 None.
212
214 None.
215
217 The following exit values shall be returned:
218 0 One or more lines were selected.
220 1 No lines were selected.
222 >1 An error occurred.
224
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 The following sections are informative.
231
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 '...'
239 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 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 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 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
267 1. To find all uses of the word "Posix" (in any case) in file text.mm
268 and write with line numbers:
269 grep -i -n posix text.mm
272 2. To find all empty lines in the standard input:
274 grep ^$
277 or:
279 grep -v .
282 3. Both of the following commands print all lines containing strings
284 "abc" or "def" or both:
285 grep -E 'abc|def'
288 grep -F 'abc
290 def'
291 4. Both of the following commands print all lines matching exactly
293 "abc" or "def":
294 grep -E '^abc$|^def$'
297 grep -F -x 'abc
299 def'
300
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 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 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 The -b option was omitted from the OPTIONS section because block num‐
316 bers are implementation-defined.
317 The System V restriction on using - to mean standard input was omitted.
319 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 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 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 The -x option, historically available only with fgrep, is available
332 here for all of the non-obsolescent versions.
333
335 None.
336
338 sed
339 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 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 .
359IEEE/The Open Group 2017 GREP(1P)