1PCREGREP(1) General Commands Manual PCREGREP(1)
2
6 pcregrep - a grep with Perl-compatible regular expressions.
7
9 pcregrep [options] [long options] [pattern] [path1 path2 ...]
10
12 pcregrep searches files for character patterns, in the same way as
14 other grep commands do, but it uses the PCRE regular expression library
15 to support patterns that are compatible with the regular expressions of
16 Perl 5. See pcresyntax(3) for a quick-reference summary of pattern syn‐
17 tax, or pcrepattern(3) for a full description of the syntax and seman‐
18 tics of the regular expressions that PCRE supports.
19 Patterns, whether supplied on the command line or in a separate file,
21 are given without delimiters. For example:
22 pcregrep Thursday /etc/motd
24 If you attempt to use delimiters (for example, by surrounding a pattern
26 with slashes, as is common in Perl scripts), they are interpreted as
27 part of the pattern. Quotes can of course be used to delimit patterns
28 on the command line because they are interpreted by the shell, and
29 indeed quotes are required if a pattern contains white space or shell
30 metacharacters.
31 The first argument that follows any option settings is treated as the
33 single pattern to be matched when neither -e nor -f is present. Con‐
34 versely, when one or both of these options are used to specify pat‐
35 terns, all arguments are treated as path names. At least one of -e, -f,
36 or an argument pattern must be provided.
37 If no files are specified, pcregrep reads the standard input. The stan‐
39 dard input can also be referenced by a name consisting of a single
40 hyphen. For example:
41 pcregrep some-pattern /file1 - /file3
43 By default, each line that matches a pattern is copied to the standard
45 output, and if there is more than one file, the file name is output at
46 the start of each line, followed by a colon. However, there are options
47 that can change how pcregrep behaves. In particular, the -M option
48 makes it possible to search for patterns that span line boundaries.
49 What defines a line boundary is controlled by the -N (--newline)
50 option.
51 The amount of memory used for buffering files that are being scanned is
53 controlled by a parameter that can be set by the --buffer-size option.
54 The default value for this parameter is specified when pcregrep is
55 built, with the default default being 20K. A block of memory three
56 times this size is used (to allow for buffering "before" and "after"
57 lines). An error occurs if a line overflows the buffer.
58 Patterns can be no longer than 8K or BUFSIZ bytes, whichever is the
60 greater. BUFSIZ is defined in <stdio.h>. When there is more than one
61 pattern (specified by the use of -e and/or -f), each pattern is applied
62 to each line in the order in which they are defined, except that all
63 the -e patterns are tried before the -f patterns.
64 By default, as soon as one pattern matches a line, no further patterns
66 are considered. However, if --colour (or --color) is used to colour the
67 matching substrings, or if --only-matching, --file-offsets, or --line-
68 offsets is used to output only the part of the line that matched
69 (either shown literally, or as an offset), scanning resumes immediately
70 following the match, so that further matches on the same line can be
71 found. If there are multiple patterns, they are all tried on the
72 remainder of the line, but patterns that follow the one that matched
73 are not tried on the earlier part of the line.
74 This behaviour means that the order in which multiple patterns are
76 specified can affect the output when one of the above options is used.
77 This is no longer the same behaviour as GNU grep, which now manages to
78 display earlier matches for later patterns (as long as there is no
79 overlap).
80 Patterns that can match an empty string are accepted, but empty string
82 matches are never recognized. An example is the pattern
83 "(super)?(man)?", in which all components are optional. This pattern
84 finds all occurrences of both "super" and "man"; the output differs
85 from matching with "super|man" when only the matching substrings are
86 being shown.
87 If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses
89 the value to set a locale when calling the PCRE library. The --locale
90 option can be used to override this.
91
93 It is possible to compile pcregrep so that it uses libz or libbz2 to
95 read files whose names end in .gz or .bz2, respectively. You can find
96 out whether your binary has support for one or both of these file types
97 by running it with the --help option. If the appropriate support is not
98 present, files are treated as plain text. The standard input is always
99 so treated.
100
102 By default, a file that contains a binary zero byte within the first
104 1024 bytes is identified as a binary file, and is processed specially.
105 (GNU grep also identifies binary files in this manner.) See the
106 --binary-files option for a means of changing the way binary files are
107 handled.
108
110 The order in which some of the options appear can affect the output.
112 For example, both the -h and -l options affect the printing of file
113 names. Whichever comes later in the command line will be the one that
114 takes effect. Similarly, except where noted below, if an option is
115 given twice, the later setting is used. Numerical values for options
116 may be followed by K or M, to signify multiplication by 1024 or
117 1024*1024 respectively.
118 -- This terminates the list of options. It is useful if the next
120 item on the command line starts with a hyphen but is not an
121 option. This allows for the processing of patterns and file‐
122 names that start with hyphens.
123 -A number, --after-context=number
125 Output number lines of context after each matching line. If
126 filenames and/or line numbers are being output, a hyphen sep‐
127 arator is used instead of a colon for the context lines. A
128 line containing "--" is output between each group of lines,
129 unless they are in fact contiguous in the input file. The
130 value of number is expected to be relatively small. However,
131 pcregrep guarantees to have up to 8K of following text avail‐
132 able for context output.
133 -a, --text
135 Treat binary files as text. This is equivalent to --binary-
136 files=text.
137 -B number, --before-context=number
139 Output number lines of context before each matching line. If
140 filenames and/or line numbers are being output, a hyphen sep‐
141 arator is used instead of a colon for the context lines. A
142 line containing "--" is output between each group of lines,
143 unless they are in fact contiguous in the input file. The
144 value of number is expected to be relatively small. However,
145 pcregrep guarantees to have up to 8K of preceding text avail‐
146 able for context output.
147 --binary-files=word
149 Specify how binary files are to be processed. If the word is
150 "binary" (the default), pattern matching is performed on
151 binary files, but the only output is "Binary file <name>
152 matches" when a match succeeds. If the word is "text", which
153 is equivalent to the -a or --text option, binary files are
154 processed in the same way as any other file. In this case,
155 when a match succeeds, the output may be binary garbage,
156 which can have nasty effects if sent to a terminal. If the
157 word is "without-match", which is equivalent to the -I
158 option, binary files are not processed at all; they are
159 assumed not to be of interest.
160 --buffer-size=number
162 Set the parameter that controls how much memory is used for
163 buffering files that are being scanned.
164 -C number, --context=number
166 Output number lines of context both before and after each
167 matching line. This is equivalent to setting both -A and -B
168 to the same value.
169 -c, --count
171 Do not output individual lines from the files that are being
172 scanned; instead output the number of lines that would other‐
173 wise have been shown. If no lines are selected, the number
174 zero is output. If several files are are being scanned, a
175 count is output for each of them. However, if the --files-
176 with-matches option is also used, only those files whose
177 counts are greater than zero are listed. When -c is used, the
178 -A, -B, and -C options are ignored.
179 --colour, --color
181 If this option is given without any data, it is equivalent to
182 "--colour=auto". If data is required, it must be given in
183 the same shell item, separated by an equals sign.
184 --colour=value, --color=value
186 This option specifies under what circumstances the parts of a
187 line that matched a pattern should be coloured in the output.
188 By default, the output is not coloured. The value (which is
189 optional, see above) may be "never", "always", or "auto". In
190 the latter case, colouring happens only if the standard out‐
191 put is connected to a terminal. More resources are used when
192 colouring is enabled, because pcregrep has to search for all
193 possible matches in a line, not just one, in order to colour
194 them all.
195 The colour that is used can be specified by setting the envi‐
197 ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
198 of this variable should be a string of two numbers, separated
199 by a semicolon. They are copied directly into the control
200 string for setting colour on a terminal, so it is your
201 responsibility to ensure that they make sense. If neither of
202 the environment variables is set, the default is "1;31",
203 which gives red.
204 -D action, --devices=action
206 If an input path is not a regular file or a directory,
207 "action" specifies how it is to be processed. Valid values
208 are "read" (the default) or "skip" (silently skip the path).
209 -d action, --directories=action
211 If an input path is a directory, "action" specifies how it is
212 to be processed. Valid values are "read" (the default in
213 non-Windows environments, for compatibility with GNU grep),
214 "recurse" (equivalent to the -r option), or "skip" (silently
215 skip the path, the default in Windows environments). In the
216 "read" case, directories are read as if they were ordinary
217 files. In some operating systems the effect of reading a
218 directory like this is an immediate end-of-file; in others it
219 may provoke an error.
220 -e pattern, --regex=pattern, --regexp=pattern
222 Specify a pattern to be matched. This option can be used mul‐
223 tiple times in order to specify several patterns. It can also
224 be used as a way of specifying a single pattern that starts
225 with a hyphen. When -e is used, no argument pattern is taken
226 from the command line; all arguments are treated as file
227 names. There is no limit to the number of patterns. They are
228 applied to each line in the order in which they are defined
229 until one matches.
230 If -f is used with -e, the command line patterns are matched
232 first, followed by the patterns from the file(s), independent
233 of the order in which these options are specified. Note that
234 multiple use of -e is not the same as a single pattern with
235 alternatives. For example, X|Y finds the first character in a
236 line that is X or Y, whereas if the two patterns are given
237 separately, with X first, pcregrep finds X if it is present,
238 even if it follows Y in the line. It finds Y only if there is
239 no X in the line. This matters only if you are using -o or
240 --colo(u)r to show the part(s) of the line that matched.
241 --exclude=pattern
243 Files (but not directories) whose names match the pattern are
244 skipped without being processed. This applies to all files,
245 whether listed on the command line, obtained from --file-
246 list, or by scanning a directory. The pattern is a PCRE regu‐
247 lar expression, and is matched against the final component of
248 the file name, not the entire path. The -F, -w, and -x
249 options do not apply to this pattern. The option may be given
250 any number of times in order to specify multiple patterns. If
251 a file name matches both an --include and an --exclude pat‐
252 tern, it is excluded. There is no short form for this option.
253 --exclude-from=filename
255 Treat each non-empty line of the file as the data for an
256 --exclude option. What constitutes a newline when reading the
257 file is the operating system's default. The --newline option
258 has no effect on this option. This option may be given more
259 than once in order to specify a number of files to read.
260 --exclude-dir=pattern
262 Directories whose names match the pattern are skipped without
263 being processed, whatever the setting of the --recursive
264 option. This applies to all directories, whether listed on
265 the command line, obtained from --file-list, or by scanning a
266 parent directory. The pattern is a PCRE regular expression,
267 and is matched against the final component of the directory
268 name, not the entire path. The -F, -w, and -x options do not
269 apply to this pattern. The option may be given any number of
270 times in order to specify more than one pattern. If a direc‐
271 tory matches both --include-dir and --exclude-dir, it is
272 excluded. There is no short form for this option.
273 -F, --fixed-strings
275 Interpret each data-matching pattern as a list of fixed
276 strings, separated by newlines, instead of as a regular
277 expression. What constitutes a newline for this purpose is
278 controlled by the --newline option. The -w (match as a word)
279 and -x (match whole line) options can be used with -F. They
280 apply to each of the fixed strings. A line is selected if any
281 of the fixed strings are found in it (subject to -w or -x, if
282 present). This option applies only to the patterns that are
283 matched against the contents of files; it does not apply to
284 patterns specified by any of the --include or --exclude
285 options.
286 -f filename, --file=filename
288 Read patterns from the file, one per line, and match them
289 against each line of input. What constitutes a newline when
290 reading the file is the operating system's default. The
291 --newline option has no effect on this option. Trailing white
292 space is removed from each line, and blank lines are ignored.
293 An empty file contains no patterns and therefore matches
294 nothing. See also the comments about multiple patterns versus
295 a single pattern with alternatives in the description of -e
296 above.
297 If this option is given more than once, all the specified
299 files are read. A data line is output if any of the patterns
300 match it. A filename can be given as "-" to refer to the
301 standard input. When -f is used, patterns specified on the
302 command line using -e may also be present; they are tested
303 before the file's patterns. However, no other pattern is
304 taken from the command line; all arguments are treated as the
305 names of paths to be searched.
306 --file-list=filename
308 Read a list of files and/or directories that are to be
309 scanned from the given file, one per line. Trailing white
310 space is removed from each line, and blank lines are ignored.
311 These paths are processed before any that are listed on the
312 command line. The filename can be given as "-" to refer to
313 the standard input. If --file and --file-list are both spec‐
314 ified as "-", patterns are read first. This is useful only
315 when the standard input is a terminal, from which further
316 lines (the list of files) can be read after an end-of-file
317 indication. If this option is given more than once, all the
318 specified files are read.
319 --file-offsets
321 Instead of showing lines or parts of lines that match, show
322 each match as an offset from the start of the file and a
323 length, separated by a comma. In this mode, no context is
324 shown. That is, the -A, -B, and -C options are ignored. If
325 there is more than one match in a line, each of them is shown
326 separately. This option is mutually exclusive with --line-
327 offsets and --only-matching.
328 -H, --with-filename
330 Force the inclusion of the filename at the start of output
331 lines when searching a single file. By default, the filename
332 is not shown in this case. For matching lines, the filename
333 is followed by a colon; for context lines, a hyphen separator
334 is used. If a line number is also being output, it follows
335 the file name.
336 -h, --no-filename
338 Suppress the output filenames when searching multiple files.
339 By default, filenames are shown when multiple files are
340 searched. For matching lines, the filename is followed by a
341 colon; for context lines, a hyphen separator is used. If a
342 line number is also being output, it follows the file name.
343 --help Output a help message, giving brief details of the command
345 options and file type support, and then exit. Anything else
346 on the command line is ignored.
347 -I Treat binary files as never matching. This is equivalent to
349 --binary-files=without-match.
350 -i, --ignore-case
352 Ignore upper/lower case distinctions during comparisons.
353 --include=pattern
355 If any --include patterns are specified, the only files that
356 are processed are those that match one of the patterns (and
357 do not match an --exclude pattern). This option does not
358 affect directories, but it applies to all files, whether
359 listed on the command line, obtained from --file-list, or by
360 scanning a directory. The pattern is a PCRE regular expres‐
361 sion, and is matched against the final component of the file
362 name, not the entire path. The -F, -w, and -x options do not
363 apply to this pattern. The option may be given any number of
364 times. If a file name matches both an --include and an
365 --exclude pattern, it is excluded. There is no short form
366 for this option.
367 --include-from=filename
369 Treat each non-empty line of the file as the data for an
370 --include option. What constitutes a newline for this purpose
371 is the operating system's default. The --newline option has
372 no effect on this option. This option may be given any number
373 of times; all the files are read.
374 --include-dir=pattern
376 If any --include-dir patterns are specified, the only direc‐
377 tories that are processed are those that match one of the
378 patterns (and do not match an --exclude-dir pattern). This
379 applies to all directories, whether listed on the command
380 line, obtained from --file-list, or by scanning a parent
381 directory. The pattern is a PCRE regular expression, and is
382 matched against the final component of the directory name,
383 not the entire path. The -F, -w, and -x options do not apply
384 to this pattern. The option may be given any number of times.
385 If a directory matches both --include-dir and --exclude-dir,
386 it is excluded. There is no short form for this option.
387 -L, --files-without-match
389 Instead of outputting lines from the files, just output the
390 names of the files that do not contain any lines that would
391 have been output. Each file name is output once, on a sepa‐
392 rate line.
393 -l, --files-with-matches
395 Instead of outputting lines from the files, just output the
396 names of the files containing lines that would have been out‐
397 put. Each file name is output once, on a separate line.
398 Searching normally stops as soon as a matching line is found
399 in a file. However, if the -c (count) option is also used,
400 matching continues in order to obtain the correct count, and
401 those files that have at least one match are listed along
402 with their counts. Using this option with -c is a way of sup‐
403 pressing the listing of files with no matches.
404 --label=name
406 This option supplies a name to be used for the standard input
407 when file names are being output. If not supplied, "(standard
408 input)" is used. There is no short form for this option.
409 --line-buffered
411 When this option is given, input is read and processed line
412 by line, and the output is flushed after each write. By
413 default, input is read in large chunks, unless pcregrep can
414 determine that it is reading from a terminal (which is cur‐
415 rently possible only in Unix-like environments). Output to
416 terminal is normally automatically flushed by the operating
417 system. This option can be useful when the input or output is
418 attached to a pipe and you do not want pcregrep to buffer up
419 large amounts of data. However, its use will affect perfor‐
420 mance, and the -M (multiline) option ceases to work.
421 --line-offsets
423 Instead of showing lines or parts of lines that match, show
424 each match as a line number, the offset from the start of the
425 line, and a length. The line number is terminated by a colon
426 (as usual; see the -n option), and the offset and length are
427 separated by a comma. In this mode, no context is shown.
428 That is, the -A, -B, and -C options are ignored. If there is
429 more than one match in a line, each of them is shown sepa‐
430 rately. This option is mutually exclusive with --file-offsets
431 and --only-matching.
432 --locale=locale-name
434 This option specifies a locale to be used for pattern match‐
435 ing. It overrides the value in the LC_ALL or LC_CTYPE envi‐
436 ronment variables. If no locale is specified, the PCRE
437 library's default (usually the "C" locale) is used. There is
438 no short form for this option.
439 --match-limit=number
441 Processing some regular expression patterns can require a
442 very large amount of memory, leading in some cases to a pro‐
443 gram crash if not enough is available. Other patterns may
444 take a very long time to search for all possible matching
445 strings. The pcre_exec() function that is called by pcregrep
446 to do the matching has two parameters that can limit the
447 resources that it uses.
448 The --match-limit option provides a means of limiting
450 resource usage when processing patterns that are not going to
451 match, but which have a very large number of possibilities in
452 their search trees. The classic example is a pattern that
453 uses nested unlimited repeats. Internally, PCRE uses a func‐
454 tion called match() which it calls repeatedly (sometimes
455 recursively). The limit set by --match-limit is imposed on
456 the number of times this function is called during a match,
457 which has the effect of limiting the amount of backtracking
458 that can take place.
459 The --recursion-limit option is similar to --match-limit, but
461 instead of limiting the total number of times that match() is
462 called, it limits the depth of recursive calls, which in turn
463 limits the amount of memory that can be used. The recursion
464 depth is a smaller number than the total number of calls,
465 because not all calls to match() are recursive. This limit is
466 of use only if it is set smaller than --match-limit.
467 There are no short forms for these options. The default set‐
469 tings are specified when the PCRE library is compiled, with
470 the default default being 10 million.
471 -M, --multiline
473 Allow patterns to match more than one line. When this option
474 is given, patterns may usefully contain literal newline char‐
475 acters and internal occurrences of ^ and $ characters. The
476 output for a successful match may consist of more than one
477 line, the last of which is the one in which the match ended.
478 If the matched string ends with a newline sequence the output
479 ends at the end of that line.
480 When this option is set, the PCRE library is called in "mul‐
482 tiline" mode. There is a limit to the number of lines that
483 can be matched, imposed by the way that pcregrep buffers the
484 input file as it scans it. However, pcregrep ensures that at
485 least 8K characters or the rest of the document (whichever is
486 the shorter) are available for forward matching, and simi‐
487 larly the previous 8K characters (or all the previous charac‐
488 ters, if fewer than 8K) are guaranteed to be available for
489 lookbehind assertions. This option does not work when input
490 is read line by line (see --line-buffered.)
491 -N newline-type, --newline=newline-type
493 The PCRE library supports five different conventions for
494 indicating the ends of lines. They are the single-character
495 sequences CR (carriage return) and LF (linefeed), the two-
496 character sequence CRLF, an "anycrlf" convention, which rec‐
497 ognizes any of the preceding three types, and an "any" con‐
498 vention, in which any Unicode line ending sequence is assumed
499 to end a line. The Unicode sequences are the three just men‐
500 tioned, plus VT (vertical tab, U+000B), FF (form feed,
501 U+000C), NEL (next line, U+0085), LS (line separator,
502 U+2028), and PS (paragraph separator, U+2029).
503 When the PCRE library is built, a default line-ending
505 sequence is specified. This is normally the standard
506 sequence for the operating system. Unless otherwise specified
507 by this option, pcregrep uses the library's default. The
508 possible values for this option are CR, LF, CRLF, ANYCRLF, or
509 ANY. This makes it possible to use pcregrep to scan files
510 that have come from other environments without having to mod‐
511 ify their line endings. If the data that is being scanned
512 does not agree with the convention set by this option, pcre‐
513 grep may behave in strange ways. Note that this option does
514 not apply to files specified by the -f, --exclude-from, or
515 --include-from options, which are expected to use the operat‐
516 ing system's standard newline sequence.
517 -n, --line-number
519 Precede each output line by its line number in the file, fol‐
520 lowed by a colon for matching lines or a hyphen for context
521 lines. If the filename is also being output, it precedes the
522 line number. This option is forced if --line-offsets is used.
523 --no-jit If the PCRE library is built with support for just-in-time
525 compiling (which speeds up matching), pcregrep automatically
526 makes use of this, unless it was explicitly disabled at build
527 time. This option can be used to disable the use of JIT at
528 run time. It is provided for testing and working round prob‐
529 lems. It should never be needed in normal use.
530 -o, --only-matching
532 Show only the part of the line that matched a pattern instead
533 of the whole line. In this mode, no context is shown. That
534 is, the -A, -B, and -C options are ignored. If there is more
535 than one match in a line, each of them is shown separately.
536 If -o is combined with -v (invert the sense of the match to
537 find non-matching lines), no output is generated, but the
538 return code is set appropriately. If the matched portion of
539 the line is empty, nothing is output unless the file name or
540 line number are being printed, in which case they are shown
541 on an otherwise empty line. This option is mutually exclusive
542 with --file-offsets and --line-offsets.
543 -onumber, --only-matching=number
545 Show only the part of the line that matched the capturing
546 parentheses of the given number. Up to 32 capturing parenthe‐
547 ses are supported, and -o0 is equivalent to -o without a num‐
548 ber. Because these options can be given without an argument
549 (see above), if an argument is present, it must be given in
550 the same shell item, for example, -o3 or --only-matching=2.
551 The comments given for the non-argument case above also apply
552 to this case. If the specified capturing parentheses do not
553 exist in the pattern, or were not set in the match, nothing
554 is output unless the file name or line number are being
555 printed.
556 If this option is given multiple times, multiple substrings
558 are output, in the order the options are given. For example,
559 -o3 -o1 -o3 causes the substrings matched by capturing paren‐
560 theses 3 and 1 and then 3 again to be output. By default,
561 there is no separator (but see the next option).
562 --om-separator=text
564 Specify a separating string for multiple occurrences of -o.
565 The default is an empty string. Separating strings are never
566 coloured.
567 -q, --quiet
569 Work quietly, that is, display nothing except error messages.
570 The exit status indicates whether or not any matches were
571 found.
572 -r, --recursive
574 If any given path is a directory, recursively scan the files
575 it contains, taking note of any --include and --exclude set‐
576 tings. By default, a directory is read as a normal file; in
577 some operating systems this gives an immediate end-of-file.
578 This option is a shorthand for setting the -d option to
579 "recurse".
580 --recursion-limit=number
582 See --match-limit above.
583 -s, --no-messages
585 Suppress error messages about non-existent or unreadable
586 files. Such files are quietly skipped. However, the return
587 code is still 2, even if matches were found in other files.
588 -u, --utf-8
590 Operate in UTF-8 mode. This option is available only if PCRE
591 has been compiled with UTF-8 support. All patterns (including
592 those for any --exclude and --include options) and all sub‐
593 ject lines that are scanned must be valid strings of UTF-8
594 characters.
595 -V, --version
597 Write the version numbers of pcregrep and the PCRE library to
598 the standard output and then exit. Anything else on the com‐
599 mand line is ignored.
600 -v, --invert-match
602 Invert the sense of the match, so that lines which do not
603 match any of the patterns are the ones that are found.
604 -w, --word-regex, --word-regexp
606 Force the patterns to match only whole words. This is equiva‐
607 lent to having \b at the start and end of the pattern. This
608 option applies only to the patterns that are matched against
609 the contents of files; it does not apply to patterns speci‐
610 fied by any of the --include or --exclude options.
611 -x, --line-regex, --line-regexp
613 Force the patterns to be anchored (each must start matching
614 at the beginning of a line) and in addition, require them to
615 match entire lines. This is equivalent to having ^ and $
616 characters at the start and end of each alternative branch in
617 every pattern. This option applies only to the patterns that
618 are matched against the contents of files; it does not apply
619 to patterns specified by any of the --include or --exclude
620 options.
621
623 The environment variables LC_ALL and LC_CTYPE are examined, in that
625 order, for a locale. The first one that is set is used. This can be
626 overridden by the --locale option. If no locale is set, the PCRE
627 library's default (usually the "C" locale) is used.
628
630 The -N (--newline) option allows pcregrep to scan files with different
632 newline conventions from the default. Any parts of the input files that
633 are written to the standard output are copied identically, with what‐
634 ever newline sequences they have in the input. However, the setting of
635 this option does not affect the interpretation of files specified by
636 the -f, --exclude-from, or --include-from options, which are assumed to
637 use the operating system's standard newline sequence, nor does it
638 affect the way in which pcregrep writes informational messages to the
639 standard error and output streams. For these it uses the string "\n" to
640 indicate newlines, relying on the C I/O library to convert this to an
641 appropriate sequence.
642
644 Many of the short and long forms of pcregrep's options are the same as
646 in the GNU grep program. Any long option of the form --xxx-regexp (GNU
647 terminology) is also available as --xxx-regex (PCRE terminology). How‐
648 ever, the --file-list, --file-offsets, --include-dir, --line-offsets,
649 --locale, --match-limit, -M, --multiline, -N, --newline, --om-separa‐
650 tor, --recursion-limit, -u, and --utf-8 options are specific to pcre‐
651 grep, as is the use of the --only-matching option with a capturing
652 parentheses number.
653 Although most of the common options work the same way, a few are dif‐
655 ferent in pcregrep. For example, the --include option's argument is a
656 glob for GNU grep, but a regular expression for pcregrep. If both the
657 -c and -l options are given, GNU grep lists only file names, without
658 counts, but pcregrep gives the counts.
659
661 There are four different ways in which an option with data can be spec‐
663 ified. If a short form option is used, the data may follow immedi‐
664 ately, or (with one exception) in the next command line item. For exam‐
665 ple:
666 -f/some/file
668 -f /some/file
669 The exception is the -o option, which may appear with or without data.
671 Because of this, if data is present, it must follow immediately in the
672 same item, for example -o3.
673 If a long form option is used, the data may appear in the same command
675 line item, separated by an equals character, or (with two exceptions)
676 it may appear in the next command line item. For example:
677 --file=/some/file
679 --file /some/file
680 Note, however, that if you want to supply a file name beginning with ~
682 as data in a shell command, and have the shell expand ~ to a home
683 directory, you must separate the file name from the option, because the
684 shell does not treat ~ specially unless it is at the start of an item.
685 The exceptions to the above are the --colour (or --color) and --only-
687 matching options, for which the data is optional. If one of these
688 options does have data, it must be given in the first form, using an
689 equals character. Otherwise pcregrep will assume that it has no data.
690
692 It is possible to supply a regular expression that takes a very long
694 time to fail to match certain lines. Such patterns normally involve
695 nested indefinite repeats, for example: (a+)*\d when matched against a
696 line of a's with no final digit. The PCRE matching function has a
697 resource limit that causes it to abort in these circumstances. If this
698 happens, pcregrep outputs an error message and the line that caused the
699 problem to the standard error stream. If there are more than 20 such
700 errors, pcregrep gives up.
701 The --match-limit option of pcregrep can be used to set the overall
703 resource limit; there is a second option called --recursion-limit that
704 sets a limit on the amount of memory (usually stack) that is used (see
705 the discussion of these options above).
706
708 Exit status is 0 if any matches were found, 1 if no matches were found,
710 and 2 for syntax errors, overlong lines, non-existent or inaccessible
711 files (even if matches were found in other files) or too many matching
712 errors. Using the -s option to suppress error messages about inaccessi‐
713 ble files does not affect the return code.
714
716 pcrepattern(3), pcresyntax(3), pcretest(1).
718
720 Philip Hazel
722 University Computing Service
723 Cambridge CB2 3QH, England.
724
726 Last updated: 03 April 2014
728 Copyright (c) 1997-2014 University of Cambridge.
729PCRE 8.35 03 April 2014 PCREGREP(1)