| 347 |
library's default (usually the "C" locale) is used. There is |
library's default (usually the "C" locale) is used. There is |
| 348 |
no short form for this option. |
no short form for this option. |
| 349 |
|
|
| 350 |
|
--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 |
| 357 |
|
resources that it uses. |
| 358 |
|
|
| 359 |
|
The --match-limit option provides a means of limiting |
| 360 |
|
resource usage when processing patterns that are not going to |
| 361 |
|
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 |
| 368 |
|
that can take place. |
| 369 |
|
|
| 370 |
|
The --recursion-limit option is similar to --match-limit, but |
| 371 |
|
instead of limiting the total number of times that match() is |
| 372 |
|
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, |
| 375 |
|
because not all calls to match() are recursive. This limit is |
| 376 |
|
of use only if it is set smaller than --match-limit. |
| 377 |
|
|
| 378 |
|
There are no short forms for these options. The default set- |
| 379 |
|
tings are specified when the PCRE library is compiled, with |
| 380 |
|
the default default being 10 million. |
| 381 |
|
|
| 382 |
-M, --multiline |
-M, --multiline |
| 383 |
Allow patterns to match more than one line. When this option |
Allow patterns to match more than one line. When this option |
| 384 |
is given, patterns may usefully contain literal newline char- |
is given, patterns may usefully contain literal newline char- |
| 385 |
acters and internal occurrences of ^ and $ characters. The |
acters and internal occurrences of ^ and $ characters. The |
| 386 |
output for any one match may consist of more than one line. |
output for any one match may consist of more than one line. |
| 387 |
When this option is set, the PCRE library is called in "mul- |
When this option is set, the PCRE library is called in "mul- |
| 388 |
tiline" mode. There is a limit to the number of lines that |
tiline" mode. There is a limit to the number of lines that |
| 389 |
can be matched, imposed by the way that pcregrep buffers the |
can be matched, imposed by the way that pcregrep buffers the |
| 390 |
input file as it scans it. However, pcregrep ensures that at |
input file as it scans it. However, pcregrep ensures that at |
| 391 |
least 8K characters or the rest of the document (whichever is |
least 8K characters or the rest of the document (whichever is |
| 392 |
the shorter) are available for forward matching, and simi- |
the shorter) are available for forward matching, and simi- |
| 393 |
larly the previous 8K characters (or all the previous charac- |
larly the previous 8K characters (or all the previous charac- |
| 394 |
ters, if fewer than 8K) are guaranteed to be available for |
ters, if fewer than 8K) are guaranteed to be available for |
| 395 |
lookbehind assertions. This option does not work when input |
lookbehind assertions. This option does not work when input |
| 396 |
is read line by line (see --line-buffered.) |
is read line by line (see --line-buffered.) |
| 397 |
|
|
| 398 |
-N newline-type, --newline=newline-type |
-N newline-type, --newline=newline-type |
| 399 |
The PCRE library supports five different conventions for |
The PCRE library supports five different conventions for |
| 400 |
indicating the ends of lines. They are the single-character |
indicating the ends of lines. They are the single-character |
| 401 |
sequences CR (carriage return) and LF (linefeed), the two- |
sequences CR (carriage return) and LF (linefeed), the two- |
| 402 |
character sequence CRLF, an "anycrlf" convention, which rec- |
character sequence CRLF, an "anycrlf" convention, which rec- |
| 403 |
ognizes any of the preceding three types, and an "any" con- |
ognizes any of the preceding three types, and an "any" con- |
| 404 |
vention, in which any Unicode line ending sequence is assumed |
vention, in which any Unicode line ending sequence is assumed |
| 405 |
to end a line. The Unicode sequences are the three just men- |
to end a line. The Unicode sequences are the three just men- |
| 406 |
tioned, plus VT (vertical tab, U+000B), FF (formfeed, |
tioned, plus VT (vertical tab, U+000B), FF (formfeed, |
| 407 |
U+000C), NEL (next line, U+0085), LS (line separator, |
U+000C), NEL (next line, U+0085), LS (line separator, |
| 408 |
U+2028), and PS (paragraph separator, U+2029). |
U+2028), and PS (paragraph separator, U+2029). |
| 409 |
|
|
| 410 |
When the PCRE library is built, a default line-ending |
When the PCRE library is built, a default line-ending |
| 411 |
sequence is specified. This is normally the standard |
sequence is specified. This is normally the standard |
| 412 |
sequence for the operating system. Unless otherwise specified |
sequence for the operating system. Unless otherwise specified |
| 413 |
by this option, pcregrep uses the library's default. The |
by this option, pcregrep uses the library's default. The |
| 414 |
possible values for this option are CR, LF, CRLF, ANYCRLF, or |
possible values for this option are CR, LF, CRLF, ANYCRLF, or |
| 415 |
ANY. This makes it possible to use pcregrep on files that |
ANY. This makes it possible to use pcregrep on files that |
| 416 |
have come from other environments without having to modify |
have come from other environments without having to modify |
| 417 |
their line endings. If the data that is being scanned does |
their line endings. If the data that is being scanned does |
| 418 |
not agree with the convention set by this option, pcregrep |
not agree with the convention set by this option, pcregrep |
| 419 |
may behave in strange ways. |
may behave in strange ways. |
| 420 |
|
|
| 421 |
-n, --line-number |
-n, --line-number |
| 422 |
Precede each output line by its line number in the file, fol- |
Precede each output line by its line number in the file, fol- |
| 423 |
lowed by a colon for matching lines or a hyphen for context |
lowed by a colon for matching lines or a hyphen for context |
| 424 |
lines. If the filename is also being output, it precedes the |
lines. If the filename is also being output, it precedes the |
| 425 |
line number. This option is forced if --line-offsets is used. |
line number. This option is forced if --line-offsets is used. |
| 426 |
|
|
| 427 |
-o, --only-matching |
-o, --only-matching |
| 428 |
Show only the part of the line that matched a pattern. In |
Show only the part of the line that matched a pattern instead |
| 429 |
this mode, no context is shown. That is, the -A, -B, and -C |
of the whole line. In this mode, no context is shown. That |
| 430 |
options are ignored. If there is more than one match in a |
is, the -A, -B, and -C options are ignored. If there is more |
| 431 |
line, each of them is shown separately. If -o is combined |
than one match in a line, each of them is shown separately. |
| 432 |
with -v (invert the sense of the match to find non-matching |
If -o is combined with -v (invert the sense of the match to |
| 433 |
lines), no output is generated, but the return code is set |
find non-matching lines), no output is generated, but the |
| 434 |
appropriately. This option is mutually exclusive with --file- |
return code is set appropriately. If the matched portion of |
| 435 |
offsets and --line-offsets. |
the line is empty, nothing is output unless the file name or |
| 436 |
|
line number are being printed, in which case they are shown |
| 437 |
|
on an otherwise empty line. This option is mutually exclusive |
| 438 |
|
with --file-offsets and --line-offsets. |
| 439 |
|
|
| 440 |
|
-onumber, --only-matching=number |
| 441 |
|
Show only the part of the line that matched the capturing |
| 442 |
|
parentheses of the given number. Up to 32 capturing parenthe- |
| 443 |
|
ses are supported. Because these options can be given without |
| 444 |
|
an argument (see above), if an argument is present, it must |
| 445 |
|
be given in the same shell item, for example, -o3 or --only- |
| 446 |
|
matching=2. The comments given for the non-argument case |
| 447 |
|
above also apply to this case. If the specified capturing |
| 448 |
|
parentheses do not exist in the pattern, or were not set in |
| 449 |
|
the match, nothing is output unless the file name or line |
| 450 |
|
number are being printed. |
| 451 |
|
|
| 452 |
-q, --quiet |
-q, --quiet |
| 453 |
Work quietly, that is, display nothing except error messages. |
Work quietly, that is, display nothing except error messages. |
| 454 |
The exit status indicates whether or not any matches were |
The exit status indicates whether or not any matches were |
| 455 |
found. |
found. |
| 456 |
|
|
| 457 |
-r, --recursive |
-r, --recursive |
| 458 |
If any given path is a directory, recursively scan the files |
If any given path is a directory, recursively scan the files |
| 459 |
it contains, taking note of any --include and --exclude set- |
it contains, taking note of any --include and --exclude set- |
| 460 |
tings. By default, a directory is read as a normal file; in |
tings. By default, a directory is read as a normal file; in |
| 461 |
some operating systems this gives an immediate end-of-file. |
some operating systems this gives an immediate end-of-file. |
| 462 |
This option is a shorthand for setting the -d option to |
This option is a shorthand for setting the -d option to |
| 463 |
"recurse". |
"recurse". |
| 464 |
|
|
| 465 |
|
--recursion-limit=number |
| 466 |
|
See --match-limit above. |
| 467 |
|
|
| 468 |
-s, --no-messages |
-s, --no-messages |
| 469 |
Suppress error messages about non-existent or unreadable |
Suppress error messages about non-existent or unreadable |
| 470 |
files. Such files are quietly skipped. However, the return |
files. Such files are quietly skipped. However, the return |
| 471 |
code is still 2, even if matches were found in other files. |
code is still 2, even if matches were found in other files. |
| 472 |
|
|
| 473 |
-u, --utf-8 |
-u, --utf-8 |
| 474 |
Operate in UTF-8 mode. This option is available only if PCRE |
Operate in UTF-8 mode. This option is available only if PCRE |
| 475 |
has been compiled with UTF-8 support. Both patterns and sub- |
has been compiled with UTF-8 support. Both patterns and sub- |
| 476 |
ject lines must be valid strings of UTF-8 characters. |
ject lines must be valid strings of UTF-8 characters. |
| 477 |
|
|
| 478 |
-V, --version |
-V, --version |
| 479 |
Write the version numbers of pcregrep and the PCRE library |
Write the version numbers of pcregrep and the PCRE library |
| 480 |
that is being used to the standard error stream. |
that is being used to the standard error stream. |
| 481 |
|
|
| 482 |
-v, --invert-match |
-v, --invert-match |
| 483 |
Invert the sense of the match, so that lines which do not |
Invert the sense of the match, so that lines which do not |
| 484 |
match any of the patterns are the ones that are found. |
match any of the patterns are the ones that are found. |
| 485 |
|
|
| 486 |
-w, --word-regex, --word-regexp |
-w, --word-regex, --word-regexp |
| 488 |
lent to having \b at the start and end of the pattern. |
lent to having \b at the start and end of the pattern. |
| 489 |
|
|
| 490 |
-x, --line-regex, --line-regexp |
-x, --line-regex, --line-regexp |
| 491 |
Force the patterns to be anchored (each must start matching |
Force the patterns to be anchored (each must start matching |
| 492 |
at the beginning of a line) and in addition, require them to |
at the beginning of a line) and in addition, require them to |
| 493 |
match entire lines. This is equivalent to having ^ and $ |
match entire lines. This is equivalent to having ^ and $ |
| 494 |
characters at the start and end of each alternative branch in |
characters at the start and end of each alternative branch in |
| 495 |
every pattern. |
every pattern. |
| 496 |
|
|
| 497 |
|
|
| 498 |
ENVIRONMENT VARIABLES |
ENVIRONMENT VARIABLES |
| 499 |
|
|
| 500 |
The environment variables LC_ALL and LC_CTYPE are examined, in that |
The environment variables LC_ALL and LC_CTYPE are examined, in that |
| 501 |
order, for a locale. The first one that is set is used. This can be |
order, for a locale. The first one that is set is used. This can be |
| 502 |
overridden by the --locale option. If no locale is set, the PCRE |
overridden by the --locale option. If no locale is set, the PCRE |
| 503 |
library's default (usually the "C" locale) is used. |
library's default (usually the "C" locale) is used. |
| 504 |
|
|
| 505 |
|
|
| 506 |
NEWLINES |
NEWLINES |
| 507 |
|
|
| 508 |
The -N (--newline) option allows pcregrep to scan files with different |
The -N (--newline) option allows pcregrep to scan files with different |
| 509 |
newline conventions from the default. However, the setting of this |
newline conventions from the default. However, the setting of this |
| 510 |
option does not affect the way in which pcregrep writes information to |
option does not affect the way in which pcregrep writes information to |
| 511 |
the standard error and output streams. It uses the string "\n" in C |
the standard error and output streams. It uses the string "\n" in C |
| 512 |
printf() calls to indicate newlines, relying on the C I/O library to |
printf() calls to indicate newlines, relying on the C I/O library to |
| 513 |
convert this to an appropriate sequence if the output is sent to a |
convert this to an appropriate sequence if the output is sent to a |
| 514 |
file. |
file. |
| 515 |
|
|
| 516 |
|
|
| 517 |
OPTIONS COMPATIBILITY |
OPTIONS COMPATIBILITY |
| 518 |
|
|
| 519 |
The majority of short and long forms of pcregrep's options are the same |
The majority of short and long forms of pcregrep's options are the same |
| 520 |
as in the GNU grep program. Any long option of the form --xxx-regexp |
as in the GNU grep program. Any long option of the form --xxx-regexp |
| 521 |
(GNU terminology) is also available as --xxx-regex (PCRE terminology). |
(GNU terminology) is also available as --xxx-regex (PCRE terminology). |
| 522 |
However, the --locale, -M, --multiline, -u, and --utf-8 options are |
However, the --locale, -M, --multiline, -u, and --utf-8 options are |
| 523 |
specific to pcregrep. If both the -c and -l options are given, GNU grep |
specific to pcregrep. If both the -c and -l options are given, GNU grep |
| 524 |
lists only file names, without counts, but pcregrep gives the counts. |
lists only file names, without counts, but pcregrep gives the counts. |
| 525 |
|
|
| 527 |
OPTIONS WITH DATA |
OPTIONS WITH DATA |
| 528 |
|
|
| 529 |
There are four different ways in which an option with data can be spec- |
There are four different ways in which an option with data can be spec- |
| 530 |
ified. If a short form option is used, the data may follow immedi- |
ified. If a short form option is used, the data may follow immedi- |
| 531 |
ately, or in the next command line item. For example: |
ately, or in the next command line item. For example: |
| 532 |
|
|
| 533 |
-f/some/file |
-f/some/file |
| 534 |
-f /some/file |
-f /some/file |
| 535 |
|
|
| 536 |
If a long form option is used, the data may appear in the same command |
If a long form option is used, the data may appear in the same command |
| 537 |
line item, separated by an equals character, or (with one exception) it |
line item, separated by an equals character, or (with one exception) it |
| 538 |
may appear in the next command line item. For example: |
may appear in the next command line item. For example: |
| 539 |
|
|
| 540 |
--file=/some/file |
--file=/some/file |
| 541 |
--file /some/file |
--file /some/file |
| 542 |
|
|
| 543 |
Note, however, that if you want to supply a file name beginning with ~ |
Note, however, that if you want to supply a file name beginning with ~ |
| 544 |
as data in a shell command, and have the shell expand ~ to a home |
as data in a shell command, and have the shell expand ~ to a home |
| 545 |
directory, you must separate the file name from the option, because the |
directory, you must separate the file name from the option, because the |
| 546 |
shell does not treat ~ specially unless it is at the start of an item. |
shell does not treat ~ specially unless it is at the start of an item. |
| 547 |
|
|
| 548 |
The exception to the above is the --colour (or --color) option, for |
The exception to the above is the --colour (or --color) option, for |
| 549 |
which the data is optional. If this option does have data, it must be |
which the data is optional. If this option does have data, it must be |
| 550 |
given in the first form, using an equals character. Otherwise it will |
given in the first form, using an equals character. Otherwise it will |
| 551 |
be assumed that it has no data. |
be assumed that it has no data. |
| 552 |
|
|
| 553 |
|
|
| 554 |
MATCHING ERRORS |
MATCHING ERRORS |
| 555 |
|
|
| 556 |
It is possible to supply a regular expression that takes a very long |
It is possible to supply a regular expression that takes a very long |
| 557 |
time to fail to match certain lines. Such patterns normally involve |
time to fail to match certain lines. Such patterns normally involve |
| 558 |
nested indefinite repeats, for example: (a+)*\d when matched against a |
nested indefinite repeats, for example: (a+)*\d when matched against a |
| 559 |
line of a's with no final digit. The PCRE matching function has a |
line of a's with no final digit. The PCRE matching function has a |
| 560 |
resource limit that causes it to abort in these circumstances. If this |
resource limit that causes it to abort in these circumstances. If this |
| 561 |
happens, pcregrep outputs an error message and the line that caused the |
happens, pcregrep outputs an error message and the line that caused the |
| 562 |
problem to the standard error stream. If there are more than 20 such |
problem to the standard error stream. If there are more than 20 such |
| 563 |
errors, pcregrep gives up. |
errors, pcregrep gives up. |
| 564 |
|
|
| 565 |
|
|
| 566 |
DIAGNOSTICS |
DIAGNOSTICS |
| 567 |
|
|
| 568 |
Exit status is 0 if any matches were found, 1 if no matches were found, |
Exit status is 0 if any matches were found, 1 if no matches were found, |
| 569 |
and 2 for syntax errors and non-existent or inacessible files (even if |
and 2 for syntax errors and non-existent or inacessible files (even if |
| 570 |
matches were found in other files) or too many matching errors. Using |
matches were found in other files) or too many matching errors. Using |
| 571 |
the -s option to suppress error messages about inaccessble files does |
the -s option to suppress error messages about inaccessble files does |
| 572 |
not affect the return code. |
not affect the return code. |
| 573 |
|
|
| 574 |
|
|
| 586 |
|
|
| 587 |
REVISION |
REVISION |
| 588 |
|
|
| 589 |
Last updated: 21 May 2010 |
Last updated: 31 October 2010 |
| 590 |
Copyright (c) 1997-2010 University of Cambridge. |
Copyright (c) 1997-2010 University of Cambridge. |
Parent Directory
| 
Revision Log
| 
Patch