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