123
131
pcregrep guarantees to have up to 8K of preceding text avail-
124
132
able for context output.
135
Set the parameter that controls how much memory is used for
136
buffering files that are being scanned.
126
138
-C number, --context=number
127
Output number lines of context both before and after each
128
matching line. This is equivalent to setting both -A and -B
139
Output number lines of context both before and after each
140
matching line. This is equivalent to setting both -A and -B
129
141
to the same value.
132
Do not output individual lines from the files that are being
144
Do not output individual lines from the files that are being
133
145
scanned; instead output the number of lines that would other-
134
wise have been shown. If no lines are selected, the number
135
zero is output. If several files are are being scanned, a
136
count is output for each of them. However, if the --files-
137
with-matches option is also used, only those files whose
146
wise have been shown. If no lines are selected, the number
147
zero is output. If several files are are being scanned, a
148
count is output for each of them. However, if the --files-
149
with-matches option is also used, only those files whose
138
150
counts are greater than zero are listed. When -c is used, the
139
151
-A, -B, and -C options are ignored.
141
153
--colour, --color
142
154
If this option is given without any data, it is equivalent to
143
"--colour=auto". If data is required, it must be given in
155
"--colour=auto". If data is required, it must be given in
144
156
the same shell item, separated by an equals sign.
146
158
--colour=value, --color=value
147
159
This option specifies under what circumstances the parts of a
148
160
line that matched a pattern should be coloured in the output.
149
By default, the output is not coloured. The value (which is
150
optional, see above) may be "never", "always", or "auto". In
151
the latter case, colouring happens only if the standard out-
152
put is connected to a terminal. More resources are used when
153
colouring is enabled, because pcregrep has to search for all
154
possible matches in a line, not just one, in order to colour
161
By default, the output is not coloured. The value (which is
162
optional, see above) may be "never", "always", or "auto". In
163
the latter case, colouring happens only if the standard out-
164
put is connected to a terminal. More resources are used when
165
colouring is enabled, because pcregrep has to search for all
166
possible matches in a line, not just one, in order to colour
157
169
The colour that is used can be specified by setting the envi-
158
170
ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
159
171
of this variable should be a string of two numbers, separated
160
by a semicolon. They are copied directly into the control
161
string for setting colour on a terminal, so it is your
162
responsibility to ensure that they make sense. If neither of
163
the environment variables is set, the default is "1;31",
172
by a semicolon. They are copied directly into the control
173
string for setting colour on a terminal, so it is your
174
responsibility to ensure that they make sense. If neither of
175
the environment variables is set, the default is "1;31",
166
178
-D action, --devices=action
167
If an input path is not a regular file or a directory,
168
"action" specifies how it is to be processed. Valid values
179
If an input path is not a regular file or a directory,
180
"action" specifies how it is to be processed. Valid values
169
181
are "read" (the default) or "skip" (silently skip the path).
171
183
-d action, --directories=action
172
184
If an input path is a directory, "action" specifies how it is
173
to be processed. Valid values are "read" (the default),
174
"recurse" (equivalent to the -r option), or "skip" (silently
175
skip the path). In the default case, directories are read as
176
if they were ordinary files. In some operating systems the
177
effect of reading a directory like this is an immediate end-
185
to be processed. Valid values are "read" (the default),
186
"recurse" (equivalent to the -r option), or "skip" (silently
187
skip the path). In the default case, directories are read as
188
if they were ordinary files. In some operating systems the
189
effect of reading a directory like this is an immediate end-
180
192
-e pattern, --regex=pattern, --regexp=pattern
181
193
Specify a pattern to be matched. This option can be used mul-
182
194
tiple times in order to specify several patterns. It can also
183
be used as a way of specifying a single pattern that starts
184
with a hyphen. When -e is used, no argument pattern is taken
185
from the command line; all arguments are treated as file
186
names. There is an overall maximum of 100 patterns. They are
187
applied to each line in the order in which they are defined
195
be used as a way of specifying a single pattern that starts
196
with a hyphen. When -e is used, no argument pattern is taken
197
from the command line; all arguments are treated as file
198
names. There is an overall maximum of 100 patterns. They are
199
applied to each line in the order in which they are defined
188
200
until one matches (or fails to match if -v is used). If -f is
189
used with -e, the command line patterns are matched first,
190
followed by the patterns from the file, independent of the
191
order in which these options are specified. Note that multi-
201
used with -e, the command line patterns are matched first,
202
followed by the patterns from the file, independent of the
203
order in which these options are specified. Note that multi-
192
204
ple use of -e is not the same as a single pattern with alter-
193
205
natives. For example, X|Y finds the first character in a line
194
that is X or Y, whereas if the two patterns are given sepa-
206
that is X or Y, whereas if the two patterns are given sepa-
195
207
rately, pcregrep finds X if it is present, even if it follows
196
Y in the line. It finds Y only if there is no X in the line.
197
This really matters only if you are using -o to show the
208
Y in the line. It finds Y only if there is no X in the line.
209
This really matters only if you are using -o to show the
198
210
part(s) of the line that matched.
200
212
--exclude=pattern
201
213
When pcregrep is searching the files in a directory as a con-
202
sequence of the -r (recursive search) option, any regular
214
sequence of the -r (recursive search) option, any regular
203
215
files whose names match the pattern are excluded. Subdirecto-
204
ries are not excluded by this option; they are searched
205
recursively, subject to the --exclude-dir and --include_dir
206
options. The pattern is a PCRE regular expression, and is
216
ries are not excluded by this option; they are searched
217
recursively, subject to the --exclude-dir and --include_dir
218
options. The pattern is a PCRE regular expression, and is
207
219
matched against the final component of the file name (not the
208
entire path). If a file name matches both --include and
209
--exclude, it is excluded. There is no short form for this
220
entire path). If a file name matches both --include and
221
--exclude, it is excluded. There is no short form for this
212
224
--exclude-dir=pattern
213
When pcregrep is searching the contents of a directory as a
214
consequence of the -r (recursive search) option, any subdi-
215
rectories whose names match the pattern are excluded. (Note
216
that the --exclude option does not affect subdirectories.)
217
The pattern is a PCRE regular expression, and is matched
218
against the final component of the name (not the entire
219
path). If a subdirectory name matches both --include-dir and
220
--exclude-dir, it is excluded. There is no short form for
225
When pcregrep is searching the contents of a directory as a
226
consequence of the -r (recursive search) option, any subdi-
227
rectories whose names match the pattern are excluded. (Note
228
that the --exclude option does not affect subdirectories.)
229
The pattern is a PCRE regular expression, and is matched
230
against the final component of the name (not the entire
231
path). If a subdirectory name matches both --include-dir and
232
--exclude-dir, it is excluded. There is no short form for
223
235
-F, --fixed-strings
224
Interpret each pattern as a list of fixed strings, separated
225
by newlines, instead of as a regular expression. The -w
226
(match as a word) and -x (match whole line) options can be
236
Interpret each pattern as a list of fixed strings, separated
237
by newlines, instead of as a regular expression. The -w
238
(match as a word) and -x (match whole line) options can be
227
239
used with -F. They apply to each of the fixed strings. A line
228
240
is selected if any of the fixed strings are found in it (sub-
229
241
ject to -w or -x, if present).
231
243
-f filename, --file=filename
232
Read a number of patterns from the file, one per line, and
233
match them against each line of input. A data line is output
244
Read a number of patterns from the file, one per line, and
245
match them against each line of input. A data line is output
234
246
if any of the patterns match it. The filename can be given as
235
247
"-" to refer to the standard input. When -f is used, patterns
236
specified on the command line using -e may also be present;
248
specified on the command line using -e may also be present;
237
249
they are tested before the file's patterns. However, no other
238
pattern is taken from the command line; all arguments are
239
treated as file names. There is an overall maximum of 100
250
pattern is taken from the command line; all arguments are
251
treated as file names. There is an overall maximum of 100
240
252
patterns. Trailing white space is removed from each line, and
241
blank lines are ignored. An empty file contains no patterns
242
and therefore matches nothing. See also the comments about
243
multiple patterns versus a single pattern with alternatives
253
blank lines are ignored. An empty file contains no patterns
254
and therefore matches nothing. See also the comments about
255
multiple patterns versus a single pattern with alternatives
244
256
in the description of -e above.
247
Instead of showing lines or parts of lines that match, show
248
each match as an offset from the start of the file and a
249
length, separated by a comma. In this mode, no context is
250
shown. That is, the -A, -B, and -C options are ignored. If
259
Instead of showing lines or parts of lines that match, show
260
each match as an offset from the start of the file and a
261
length, separated by a comma. In this mode, no context is
262
shown. That is, the -A, -B, and -C options are ignored. If
251
263
there is more than one match in a line, each of them is shown
252
separately. This option is mutually exclusive with --line-
264
separately. This option is mutually exclusive with --line-
253
265
offsets and --only-matching.
255
267
-H, --with-filename
256
Force the inclusion of the filename at the start of output
257
lines when searching a single file. By default, the filename
258
is not shown in this case. For matching lines, the filename
268
Force the inclusion of the filename at the start of output
269
lines when searching a single file. By default, the filename
270
is not shown in this case. For matching lines, the filename
259
271
is followed by a colon; for context lines, a hyphen separator
260
is used. If a line number is also being output, it follows
272
is used. If a line number is also being output, it follows
263
275
-h, --no-filename
264
Suppress the output filenames when searching multiple files.
265
By default, filenames are shown when multiple files are
266
searched. For matching lines, the filename is followed by a
267
colon; for context lines, a hyphen separator is used. If a
276
Suppress the output filenames when searching multiple files.
277
By default, filenames are shown when multiple files are
278
searched. For matching lines, the filename is followed by a
279
colon; for context lines, a hyphen separator is used. If a
268
280
line number is also being output, it follows the file name.
270
--help Output a help message, giving brief details of the command
282
--help Output a help message, giving brief details of the command
271
283
options and file type support, and then exit.
273
285
-i, --ignore-case
277
289
When pcregrep is searching the files in a directory as a con-
278
290
sequence of the -r (recursive search) option, only those reg-
279
291
ular files whose names match the pattern are included. Subdi-
280
rectories are always included and searched recursively, sub-
292
rectories are always included and searched recursively, sub-
281
293
ject to the --include-dir and --exclude-dir options. The pat-
282
294
tern is a PCRE regular expression, and is matched against the
283
final component of the file name (not the entire path). If a
295
final component of the file name (not the entire path). If a
284
296
file name matches both --include and --exclude, it is
285
297
excluded. There is no short form for this option.
287
299
--include-dir=pattern
288
When pcregrep is searching the contents of a directory as a
289
consequence of the -r (recursive search) option, only those
290
subdirectories whose names match the pattern are included.
291
(Note that the --include option does not affect subdirecto-
292
ries.) The pattern is a PCRE regular expression, and is
293
matched against the final component of the name (not the
294
entire path). If a subdirectory name matches both --include-
300
When pcregrep is searching the contents of a directory as a
301
consequence of the -r (recursive search) option, only those
302
subdirectories whose names match the pattern are included.
303
(Note that the --include option does not affect subdirecto-
304
ries.) The pattern is a PCRE regular expression, and is
305
matched against the final component of the name (not the
306
entire path). If a subdirectory name matches both --include-
295
307
dir and --exclude-dir, it is excluded. There is no short form
298
310
-L, --files-without-match
299
Instead of outputting lines from the files, just output the
300
names of the files that do not contain any lines that would
301
have been output. Each file name is output once, on a sepa-
311
Instead of outputting lines from the files, just output the
312
names of the files that do not contain any lines that would
313
have been output. Each file name is output once, on a sepa-
304
316
-l, --files-with-matches
305
Instead of outputting lines from the files, just output the
317
Instead of outputting lines from the files, just output the
306
318
names of the files containing lines that would have been out-
307
put. Each file name is output once, on a separate line.
308
Searching normally stops as soon as a matching line is found
309
in a file. However, if the -c (count) option is also used,
310
matching continues in order to obtain the correct count, and
311
those files that have at least one match are listed along
319
put. Each file name is output once, on a separate line.
320
Searching normally stops as soon as a matching line is found
321
in a file. However, if the -c (count) option is also used,
322
matching continues in order to obtain the correct count, and
323
those files that have at least one match are listed along
312
324
with their counts. Using this option with -c is a way of sup-
313
325
pressing the listing of files with no matches.
318
330
input)" is used. There is no short form for this option.
321
When this option is given, input is read and processed line
322
by line, and the output is flushed after each write. By
323
default, input is read in large chunks, unless pcregrep can
324
determine that it is reading from a terminal (which is cur-
325
rently possible only in Unix environments). Output to termi-
326
nal is normally automatically flushed by the operating sys-
327
tem. This option can be useful when the input or output is
328
attached to a pipe and you do not want pcregrep to buffer up
329
large amounts of data. However, its use will affect perfor-
333
When this option is given, input is read and processed line
334
by line, and the output is flushed after each write. By
335
default, input is read in large chunks, unless pcregrep can
336
determine that it is reading from a terminal (which is cur-
337
rently possible only in Unix environments). Output to termi-
338
nal is normally automatically flushed by the operating sys-
339
tem. This option can be useful when the input or output is
340
attached to a pipe and you do not want pcregrep to buffer up
341
large amounts of data. However, its use will affect perfor-
330
342
mance, and the -M (multiline) option ceases to work.
333
Instead of showing lines or parts of lines that match, show
345
Instead of showing lines or parts of lines that match, show
334
346
each match as a line number, the offset from the start of the
335
line, and a length. The line number is terminated by a colon
336
(as usual; see the -n option), and the offset and length are
337
separated by a comma. In this mode, no context is shown.
338
That is, the -A, -B, and -C options are ignored. If there is
339
more than one match in a line, each of them is shown sepa-
347
line, and a length. The line number is terminated by a colon
348
(as usual; see the -n option), and the offset and length are
349
separated by a comma. In this mode, no context is shown.
350
That is, the -A, -B, and -C options are ignored. If there is
351
more than one match in a line, each of them is shown sepa-
340
352
rately. This option is mutually exclusive with --file-offsets
341
353
and --only-matching.
343
355
--locale=locale-name
344
This option specifies a locale to be used for pattern match-
345
ing. It overrides the value in the LC_ALL or LC_CTYPE envi-
346
ronment variables. If no locale is specified, the PCRE
347
library's default (usually the "C" locale) is used. There is
356
This option specifies a locale to be used for pattern match-
357
ing. It overrides the value in the LC_ALL or LC_CTYPE envi-
358
ronment variables. If no locale is specified, the PCRE
359
library's default (usually the "C" locale) is used. There is
348
360
no short form for this option.
350
362
--match-limit=number
351
Processing some regular expression patterns can require a
352
very large amount of memory, leading in some cases to a pro-
353
gram crash if not enough is available. Other patterns may
354
take a very long time to search for all possible matching
355
strings. The pcre_exec() function that is called by pcregrep
356
to do the matching has two parameters that can limit the
363
Processing some regular expression patterns can require a
364
very large amount of memory, leading in some cases to a pro-
365
gram crash if not enough is available. Other patterns may
366
take a very long time to search for all possible matching
367
strings. The pcre_exec() function that is called by pcregrep
368
to do the matching has two parameters that can limit the
357
369
resources that it uses.
359
The --match-limit option provides a means of limiting
371
The --match-limit option provides a means of limiting
360
372
resource usage when processing patterns that are not going to
361
373
match, but which have a very large number of possibilities in
362
their search trees. The classic example is a pattern that
363
uses nested unlimited repeats. Internally, PCRE uses a func-
364
tion called match() which it calls repeatedly (sometimes
365
recursively). The limit set by --match-limit is imposed on
366
the number of times this function is called during a match,
367
which has the effect of limiting the amount of backtracking
374
their search trees. The classic example is a pattern that
375
uses nested unlimited repeats. Internally, PCRE uses a func-
376
tion called match() which it calls repeatedly (sometimes
377
recursively). The limit set by --match-limit is imposed on
378
the number of times this function is called during a match,
379
which has the effect of limiting the amount of backtracking
368
380
that can take place.
370
382
The --recursion-limit option is similar to --match-limit, but
371
383
instead of limiting the total number of times that match() is
372
384
called, it limits the depth of recursive calls, which in turn
373
limits the amount of memory that can be used. The recursion
374
depth is a smaller number than the total number of calls,
385
limits the amount of memory that can be used. The recursion
386
depth is a smaller number than the total number of calls,
375
387
because not all calls to match() are recursive. This limit is
376
388
of use only if it is set smaller than --match-limit.
378
There are no short forms for these options. The default set-
379
tings are specified when the PCRE library is compiled, with
390
There are no short forms for these options. The default set-
391
tings are specified when the PCRE library is compiled, with
380
392
the default default being 10 million.
383
Allow patterns to match more than one line. When this option
395
Allow patterns to match more than one line. When this option
384
396
is given, patterns may usefully contain literal newline char-
385
acters and internal occurrences of ^ and $ characters. The
386
output for a successful match may consist of more than one
387
line, the last of which is the one in which the match ended.
397
acters and internal occurrences of ^ and $ characters. The
398
output for a successful match may consist of more than one
399
line, the last of which is the one in which the match ended.
388
400
If the matched string ends with a newline sequence the output
389
401
ends at the end of that line.
391
When this option is set, the PCRE library is called in "mul-
392
tiline" mode. There is a limit to the number of lines that
393
can be matched, imposed by the way that pcregrep buffers the
394
input file as it scans it. However, pcregrep ensures that at
403
When this option is set, the PCRE library is called in "mul-
404
tiline" mode. There is a limit to the number of lines that
405
can be matched, imposed by the way that pcregrep buffers the
406
input file as it scans it. However, pcregrep ensures that at
395
407
least 8K characters or the rest of the document (whichever is
396
the shorter) are available for forward matching, and simi-
408
the shorter) are available for forward matching, and simi-
397
409
larly the previous 8K characters (or all the previous charac-
398
ters, if fewer than 8K) are guaranteed to be available for
399
lookbehind assertions. This option does not work when input
410
ters, if fewer than 8K) are guaranteed to be available for
411
lookbehind assertions. This option does not work when input
400
412
is read line by line (see --line-buffered.)
402
414
-N newline-type, --newline=newline-type
403
The PCRE library supports five different conventions for
404
indicating the ends of lines. They are the single-character
405
sequences CR (carriage return) and LF (linefeed), the two-
406
character sequence CRLF, an "anycrlf" convention, which rec-
407
ognizes any of the preceding three types, and an "any" con-
415
The PCRE library supports five different conventions for
416
indicating the ends of lines. They are the single-character
417
sequences CR (carriage return) and LF (linefeed), the two-
418
character sequence CRLF, an "anycrlf" convention, which rec-
419
ognizes any of the preceding three types, and an "any" con-
408
420
vention, in which any Unicode line ending sequence is assumed
409
to end a line. The Unicode sequences are the three just men-
410
tioned, plus VT (vertical tab, U+000B), FF (formfeed,
411
U+000C), NEL (next line, U+0085), LS (line separator,
421
to end a line. The Unicode sequences are the three just men-
422
tioned, plus VT (vertical tab, U+000B), FF (form feed,
423
U+000C), NEL (next line, U+0085), LS (line separator,
412
424
U+2028), and PS (paragraph separator, U+2029).
414
426
When the PCRE library is built, a default line-ending
415
sequence is specified. This is normally the standard
427
sequence is specified. This is normally the standard
416
428
sequence for the operating system. Unless otherwise specified
417
by this option, pcregrep uses the library's default. The
429
by this option, pcregrep uses the library's default. The
418
430
possible values for this option are CR, LF, CRLF, ANYCRLF, or
419
ANY. This makes it possible to use pcregrep on files that
420
have come from other environments without having to modify
421
their line endings. If the data that is being scanned does
422
not agree with the convention set by this option, pcregrep
431
ANY. This makes it possible to use pcregrep on files that
432
have come from other environments without having to modify
433
their line endings. If the data that is being scanned does
434
not agree with the convention set by this option, pcregrep
423
435
may behave in strange ways.
425
437
-n, --line-number
426
438
Precede each output line by its line number in the file, fol-
427
lowed by a colon for matching lines or a hyphen for context
428
lines. If the filename is also being output, it precedes the
439
lowed by a colon for matching lines or a hyphen for context
440
lines. If the filename is also being output, it precedes the
429
441
line number. This option is forced if --line-offsets is used.
443
--no-jit If the PCRE library is built with support for just-in-time
444
compiling (which speeds up matching), pcregrep automatically
445
makes use of this, unless it was explicitly disabled at build
446
time. This option can be used to disable the use of JIT at
447
run time. It is provided for testing and working round prob-
448
lems. It should never be needed in normal use.
431
450
-o, --only-matching
432
451
Show only the part of the line that matched a pattern instead
433
452
of the whole line. In this mode, no context is shown. That
added
removed
doc/pcregrep.txt
