"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/pcregrep.txt" between
pcre-8.43.tar.bz2 and pcre-8.44.tar.bz2

About: The PCRE library implements Perl compatible regular expression pattern matching.

pcregrep.txt  (pcre-8.43.tar.bz2):pcregrep.txt  (pcre-8.44.tar.bz2)
skipping to change at line 26 skipping to change at line 26
tics of the regular expressions that PCRE supports. tics of the regular expressions that PCRE supports.
Patterns, whether supplied on the command line or in a separate file, Patterns, whether supplied on the command line or in a separate file,
are given without delimiters. For example: are given without delimiters. For example:
pcregrep Thursday /etc/motd pcregrep Thursday /etc/motd
If you attempt to use delimiters (for example, by surrounding a pattern If you attempt to use delimiters (for example, by surrounding a pattern
with slashes, as is common in Perl scripts), they are interpreted as with slashes, as is common in Perl scripts), they are interpreted as
part of the pattern. Quotes can of course be used to delimit patterns part of the pattern. Quotes can of course be used to delimit patterns
on the command line because they are interpreted by the shell, and on the command line because they are interpreted by the shell, and in-
indeed quotes are required if a pattern contains white space or shell deed quotes are required if a pattern contains white space or shell
metacharacters. metacharacters.
The first argument that follows any option settings is treated as the The first argument that follows any option settings is treated as the
single pattern to be matched when neither -e nor -f is present. Con- single pattern to be matched when neither -e nor -f is present. Con-
versely, when one or both of these options are used to specify pat- versely, when one or both of these options are used to specify pat-
terns, all arguments are treated as path names. At least one of -e, -f, terns, all arguments are treated as path names. At least one of -e, -f,
or an argument pattern must be provided. or an argument pattern must be provided.
If no files are specified, pcregrep reads the standard input. The stan- If no files are specified, pcregrep reads the standard input. The stan-
dard input can also be referenced by a name consisting of a single dard input can also be referenced by a name consisting of a single hy-
hyphen. For example: phen. For example:
pcregrep some-pattern /file1 - /file3 pcregrep some-pattern /file1 - /file3
By default, each line that matches a pattern is copied to the standard By default, each line that matches a pattern is copied to the standard
output, and if there is more than one file, the file name is output at output, and if there is more than one file, the file name is output at
the start of each line, followed by a colon. However, there are options the start of each line, followed by a colon. However, there are options
that can change how pcregrep behaves. In particular, the -M option that can change how pcregrep behaves. In particular, the -M option
makes it possible to search for patterns that span line boundaries. makes it possible to search for patterns that span line boundaries.
What defines a line boundary is controlled by the -N (--newline) What defines a line boundary is controlled by the -N (--newline) op-
option. tion.
The amount of memory used for buffering files that are being scanned is The amount of memory used for buffering files that are being scanned is
controlled by a parameter that can be set by the --buffer-size option. controlled by a parameter that can be set by the --buffer-size option.
The default value for this parameter is specified when pcregrep is The default value for this parameter is specified when pcregrep is
built, with the default default being 20K. A block of memory three built, with the default default being 20K. A block of memory three
times this size is used (to allow for buffering "before" and "after" times this size is used (to allow for buffering "before" and "after"
lines). An error occurs if a line overflows the buffer. lines). An error occurs if a line overflows the buffer.
Patterns can be no longer than 8K or BUFSIZ bytes, whichever is the Patterns can be no longer than 8K or BUFSIZ bytes, whichever is the
greater. BUFSIZ is defined in <stdio.h>. When there is more than one greater. BUFSIZ is defined in <stdio.h>. When there is more than one
pattern (specified by the use of -e and/or -f), each pattern is applied pattern (specified by the use of -e and/or -f), each pattern is applied
to each line in the order in which they are defined, except that all to each line in the order in which they are defined, except that all
the -e patterns are tried before the -f patterns. the -e patterns are tried before the -f patterns.
By default, as soon as one pattern matches a line, no further patterns By default, as soon as one pattern matches a line, no further patterns
are considered. However, if --colour (or --color) is used to colour the are considered. However, if --colour (or --color) is used to colour the
matching substrings, or if --only-matching, --file-offsets, or --line- matching substrings, or if --only-matching, --file-offsets, or --line-
offsets is used to output only the part of the line that matched offsets is used to output only the part of the line that matched (ei-
(either shown literally, or as an offset), scanning resumes immediately ther shown literally, or as an offset), scanning resumes immediately
following the match, so that further matches on the same line can be following the match, so that further matches on the same line can be
found. If there are multiple patterns, they are all tried on the found. If there are multiple patterns, they are all tried on the re-
remainder of the line, but patterns that follow the one that matched mainder of the line, but patterns that follow the one that matched are
are not tried on the earlier part of the line. not tried on the earlier part of the line.
This behaviour means that the order in which multiple patterns are This behaviour means that the order in which multiple patterns are
specified can affect the output when one of the above options is used. specified can affect the output when one of the above options is used.
This is no longer the same behaviour as GNU grep, which now manages to This is no longer the same behaviour as GNU grep, which now manages to
display earlier matches for later patterns (as long as there is no display earlier matches for later patterns (as long as there is no
overlap). overlap).
Patterns that can match an empty string are accepted, but empty string Patterns that can match an empty string are accepted, but empty string
matches are never recognized. An example is the pattern matches are never recognized. An example is the pattern "(su-
"(super)?(man)?", in which all components are optional. This pattern per)?(man)?", in which all components are optional. This pattern finds
finds all occurrences of both "super" and "man"; the output differs all occurrences of both "super" and "man"; the output differs from
from matching with "super|man" when only the matching substrings are matching with "super|man" when only the matching substrings are being
being shown. shown.
If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses
the value to set a locale when calling the PCRE library. The --locale the value to set a locale when calling the PCRE library. The --locale
option can be used to override this. option can be used to override this.
SUPPORT FOR COMPRESSED FILES SUPPORT FOR COMPRESSED FILES
It is possible to compile pcregrep so that it uses libz or libbz2 to It is possible to compile pcregrep so that it uses libz or libbz2 to
read files whose names end in .gz or .bz2, respectively. You can find read files whose names end in .gz or .bz2, respectively. You can find
out whether your binary has support for one or both of these file types out whether your binary has support for one or both of these file types
by running it with the --help option. If the appropriate support is not by running it with the --help option. If the appropriate support is not
present, files are treated as plain text. The standard input is always present, files are treated as plain text. The standard input is always
so treated. so treated.
BINARY FILES BINARY FILES
By default, a file that contains a binary zero byte within the first By default, a file that contains a binary zero byte within the first
1024 bytes is identified as a binary file, and is processed specially. 1024 bytes is identified as a binary file, and is processed specially.
(GNU grep also identifies binary files in this manner.) See the (GNU grep also identifies binary files in this manner.) See the --bi-
--binary-files option for a means of changing the way binary files are nary-files option for a means of changing the way binary files are han-
handled. dled.
OPTIONS OPTIONS
The order in which some of the options appear can affect the output. The order in which some of the options appear can affect the output.
For example, both the -h and -l options affect the printing of file For example, both the -h and -l options affect the printing of file
names. Whichever comes later in the command line will be the one that names. Whichever comes later in the command line will be the one that
takes effect. Similarly, except where noted below, if an option is takes effect. Similarly, except where noted below, if an option is
given twice, the later setting is used. Numerical values for options given twice, the later setting is used. Numerical values for options
may be followed by K or M, to signify multiplication by 1024 or may be followed by K or M, to signify multiplication by 1024 or
1024*1024 respectively. 1024*1024 respectively.
skipping to change at line 148 skipping to change at line 148
filenames and/or line numbers are being output, a hyphen sep- filenames and/or line numbers are being output, a hyphen sep-
arator is used instead of a colon for the context lines. A arator is used instead of a colon for the context lines. A
line containing "--" is output between each group of lines, line containing "--" is output between each group of lines,
unless they are in fact contiguous in the input file. The unless they are in fact contiguous in the input file. The
value of number is expected to be relatively small. However, value of number is expected to be relatively small. However,
pcregrep guarantees to have up to 8K of preceding text avail- pcregrep guarantees to have up to 8K of preceding text avail-
able for context output. able for context output.
--binary-files=word --binary-files=word
Specify how binary files are to be processed. If the word is Specify how binary files are to be processed. If the word is
"binary" (the default), pattern matching is performed on "binary" (the default), pattern matching is performed on bi-
binary files, but the only output is "Binary file <name> nary files, but the only output is "Binary file <name>
matches" when a match succeeds. If the word is "text", which matches" when a match succeeds. If the word is "text", which
is equivalent to the -a or --text option, binary files are is equivalent to the -a or --text option, binary files are
processed in the same way as any other file. In this case, processed in the same way as any other file. In this case,
when a match succeeds, the output may be binary garbage, when a match succeeds, the output may be binary garbage,
which can have nasty effects if sent to a terminal. If the which can have nasty effects if sent to a terminal. If the
word is "without-match", which is equivalent to the -I word is "without-match", which is equivalent to the -I op-
option, binary files are not processed at all; they are tion, binary files are not processed at all; they are assumed
assumed not to be of interest. not to be of interest.
--buffer-size=number --buffer-size=number
Set the parameter that controls how much memory is used for Set the parameter that controls how much memory is used for
buffering files that are being scanned. buffering files that are being scanned.
-C number, --context=number -C number, --context=number
Output number lines of context both before and after each Output number lines of context both before and after each
matching line. This is equivalent to setting both -A and -B matching line. This is equivalent to setting both -A and -B
to the same value. to the same value.
skipping to change at line 198 skipping to change at line 198
the latter case, colouring happens only if the standard out- the latter case, colouring happens only if the standard out-
put is connected to a terminal. More resources are used when put is connected to a terminal. More resources are used when
colouring is enabled, because pcregrep has to search for all colouring is enabled, because pcregrep has to search for all
possible matches in a line, not just one, in order to colour possible matches in a line, not just one, in order to colour
them all. them all.
The colour that is used can be specified by setting the envi- The colour that is used can be specified by setting the envi-
ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
of this variable should be a string of two numbers, separated of this variable should be a string of two numbers, separated
by a semicolon. They are copied directly into the control by a semicolon. They are copied directly into the control
string for setting colour on a terminal, so it is your string for setting colour on a terminal, so it is your re-
responsibility to ensure that they make sense. If neither of sponsibility to ensure that they make sense. If neither of
the environment variables is set, the default is "1;31", the environment variables is set, the default is "1;31",
which gives red. which gives red.
-D action, --devices=action -D action, --devices=action
If an input path is not a regular file or a directory, If an input path is not a regular file or a directory, "ac-
"action" specifies how it is to be processed. Valid values tion" specifies how it is to be processed. Valid values are
are "read" (the default) or "skip" (silently skip the path). "read" (the default) or "skip" (silently skip the path).
-d action, --directories=action -d action, --directories=action
If an input path is a directory, "action" specifies how it is If an input path is a directory, "action" specifies how it is
to be processed. Valid values are "read" (the default in to be processed. Valid values are "read" (the default in
non-Windows environments, for compatibility with GNU grep), non-Windows environments, for compatibility with GNU grep),
"recurse" (equivalent to the -r option), or "skip" (silently "recurse" (equivalent to the -r option), or "skip" (silently
skip the path, the default in Windows environments). In the skip the path, the default in Windows environments). In the
"read" case, directories are read as if they were ordinary "read" case, directories are read as if they were ordinary
files. In some operating systems the effect of reading a files. In some operating systems the effect of reading a di-
directory like this is an immediate end-of-file; in others it rectory like this is an immediate end-of-file; in others it
may provoke an error. may provoke an error.
-e pattern, --regex=pattern, --regexp=pattern -e pattern, --regex=pattern, --regexp=pattern
Specify a pattern to be matched. This option can be used mul- Specify a pattern to be matched. This option can be used mul-
tiple times in order to specify several patterns. It can also tiple times in order to specify several patterns. It can also
be used as a way of specifying a single pattern that starts be used as a way of specifying a single pattern that starts
with a hyphen. When -e is used, no argument pattern is taken with a hyphen. When -e is used, no argument pattern is taken
from the command line; all arguments are treated as file from the command line; all arguments are treated as file
names. There is no limit to the number of patterns. They are names. There is no limit to the number of patterns. They are
applied to each line in the order in which they are defined applied to each line in the order in which they are defined
skipping to change at line 246 skipping to change at line 246
even if it follows Y in the line. It finds Y only if there is even if it follows Y in the line. It finds Y only if there is
no X in the line. This matters only if you are using -o or no X in the line. This matters only if you are using -o or
--colo(u)r to show the part(s) of the line that matched. --colo(u)r to show the part(s) of the line that matched.
--exclude=pattern --exclude=pattern
Files (but not directories) whose names match the pattern are Files (but not directories) whose names match the pattern are
skipped without being processed. This applies to all files, skipped without being processed. This applies to all files,
whether listed on the command line, obtained from --file- whether listed on the command line, obtained from --file-
list, or by scanning a directory. The pattern is a PCRE regu- list, or by scanning a directory. The pattern is a PCRE regu-
lar expression, and is matched against the final component of lar expression, and is matched against the final component of
the file name, not the entire path. The -F, -w, and -x the file name, not the entire path. The -F, -w, and -x op-
options do not apply to this pattern. The option may be given tions do not apply to this pattern. The option may be given
any number of times in order to specify multiple patterns. If any number of times in order to specify multiple patterns. If
a file name matches both an --include and an --exclude pat- a file name matches both an --include and an --exclude pat-
tern, it is excluded. There is no short form for this option. tern, it is excluded. There is no short form for this option.
--exclude-from=filename --exclude-from=filename
Treat each non-empty line of the file as the data for an Treat each non-empty line of the file as the data for an
--exclude option. What constitutes a newline when reading the --exclude option. What constitutes a newline when reading the
file is the operating system's default. The --newline option file is the operating system's default. The --newline option
has no effect on this option. This option may be given more has no effect on this option. This option may be given more
than once in order to specify a number of files to read. than once in order to specify a number of files to read.
--exclude-dir=pattern --exclude-dir=pattern
Directories whose names match the pattern are skipped without Directories whose names match the pattern are skipped without
being processed, whatever the setting of the --recursive being processed, whatever the setting of the --recursive op-
option. This applies to all directories, whether listed on tion. This applies to all directories, whether listed on the
the command line, obtained from --file-list, or by scanning a command line, obtained from --file-list, or by scanning a
parent directory. The pattern is a PCRE regular expression, parent directory. The pattern is a PCRE regular expression,
and is matched against the final component of the directory and is matched against the final component of the directory
name, not the entire path. The -F, -w, and -x options do not name, not the entire path. The -F, -w, and -x options do not
apply to this pattern. The option may be given any number of apply to this pattern. The option may be given any number of
times in order to specify more than one pattern. If a direc- times in order to specify more than one pattern. If a direc-
tory matches both --include-dir and --exclude-dir, it is tory matches both --include-dir and --exclude-dir, it is ex-
excluded. There is no short form for this option. cluded. There is no short form for this option.
-F, --fixed-strings -F, --fixed-strings
Interpret each data-matching pattern as a list of fixed Interpret each data-matching pattern as a list of fixed
strings, separated by newlines, instead of as a regular strings, separated by newlines, instead of as a regular ex-
expression. What constitutes a newline for this purpose is pression. What constitutes a newline for this purpose is con-
controlled by the --newline option. The -w (match as a word) trolled by the --newline option. The -w (match as a word) and
and -x (match whole line) options can be used with -F. They -x (match whole line) options can be used with -F. They ap-
apply to each of the fixed strings. A line is selected if any ply to each of the fixed strings. A line is selected if any
of the fixed strings are found in it (subject to -w or -x, if of the fixed strings are found in it (subject to -w or -x, if
present). This option applies only to the patterns that are present). This option applies only to the patterns that are
matched against the contents of files; it does not apply to matched against the contents of files; it does not apply to
patterns specified by any of the --include or --exclude patterns specified by any of the --include or --exclude op-
options. tions.
-f filename, --file=filename -f filename, --file=filename
Read patterns from the file, one per line, and match them Read patterns from the file, one per line, and match them
against each line of input. What constitutes a newline when against each line of input. What constitutes a newline when
reading the file is the operating system's default. The reading the file is the operating system's default. The
--newline option has no effect on this option. Trailing white --newline option has no effect on this option. Trailing white
space is removed from each line, and blank lines are ignored. space is removed from each line, and blank lines are ignored.
An empty file contains no patterns and therefore matches An empty file contains no patterns and therefore matches
nothing. See also the comments about multiple patterns versus nothing. See also the comments about multiple patterns versus
a single pattern with alternatives in the description of -e a single pattern with alternatives in the description of -e
skipping to change at line 355 skipping to change at line 355
-I Treat binary files as never matching. This is equivalent to -I Treat binary files as never matching. This is equivalent to
--binary-files=without-match. --binary-files=without-match.
-i, --ignore-case -i, --ignore-case
Ignore upper/lower case distinctions during comparisons. Ignore upper/lower case distinctions during comparisons.
--include=pattern --include=pattern
If any --include patterns are specified, the only files that If any --include patterns are specified, the only files that
are processed are those that match one of the patterns (and are processed are those that match one of the patterns (and
do not match an --exclude pattern). This option does not do not match an --exclude pattern). This option does not af-
affect directories, but it applies to all files, whether fect directories, but it applies to all files, whether listed
listed on the command line, obtained from --file-list, or by on the command line, obtained from --file-list, or by scan-
scanning a directory. The pattern is a PCRE regular expres- ning a directory. The pattern is a PCRE regular expression,
sion, and is matched against the final component of the file and is matched against the final component of the file name,
name, not the entire path. The -F, -w, and -x options do not not the entire path. The -F, -w, and -x options do not apply
apply to this pattern. The option may be given any number of to this pattern. The option may be given any number of times.
times. If a file name matches both an --include and an If a file name matches both an --include and an --exclude
--exclude pattern, it is excluded. There is no short form pattern, it is excluded. There is no short form for this op-
for this option. tion.
--include-from=filename --include-from=filename
Treat each non-empty line of the file as the data for an Treat each non-empty line of the file as the data for an
--include option. What constitutes a newline for this purpose --include option. What constitutes a newline for this purpose
is the operating system's default. The --newline option has is the operating system's default. The --newline option has
no effect on this option. This option may be given any number no effect on this option. This option may be given any number
of times; all the files are read. of times; all the files are read.
--include-dir=pattern --include-dir=pattern
If any --include-dir patterns are specified, the only direc- If any --include-dir patterns are specified, the only direc-
tories that are processed are those that match one of the tories that are processed are those that match one of the
patterns (and do not match an --exclude-dir pattern). This patterns (and do not match an --exclude-dir pattern). This
applies to all directories, whether listed on the command applies to all directories, whether listed on the command
line, obtained from --file-list, or by scanning a parent line, obtained from --file-list, or by scanning a parent di-
directory. The pattern is a PCRE regular expression, and is rectory. The pattern is a PCRE regular expression, and is
matched against the final component of the directory name, matched against the final component of the directory name,
not the entire path. The -F, -w, and -x options do not apply not the entire path. The -F, -w, and -x options do not apply
to this pattern. The option may be given any number of times. to this pattern. The option may be given any number of times.
If a directory matches both --include-dir and --exclude-dir, If a directory matches both --include-dir and --exclude-dir,
it is excluded. There is no short form for this option. it is excluded. There is no short form for this option.
-L, --files-without-match -L, --files-without-match
Instead of outputting lines from the files, just output the Instead of outputting lines from the files, just output the
names of the files that do not contain any lines that would names of the files that do not contain any lines that would
have been output. Each file name is output once, on a sepa- have been output. Each file name is output once, on a sepa-
skipping to change at line 410 skipping to change at line 410
with their counts. Using this option with -c is a way of sup- with their counts. Using this option with -c is a way of sup-
pressing the listing of files with no matches. pressing the listing of files with no matches.
--label=name --label=name
This option supplies a name to be used for the standard input This option supplies a name to be used for the standard input
when file names are being output. If not supplied, "(standard when file names are being output. If not supplied, "(standard
input)" is used. There is no short form for this option. input)" is used. There is no short form for this option.
--line-buffered --line-buffered
When this option is given, input is read and processed line When this option is given, input is read and processed line
by line, and the output is flushed after each write. By by line, and the output is flushed after each write. By de-
default, input is read in large chunks, unless pcregrep can fault, input is read in large chunks, unless pcregrep can de-
determine that it is reading from a terminal (which is cur- termine that it is reading from a terminal (which is cur-
rently possible only in Unix-like environments). Output to rently possible only in Unix-like environments). Output to
terminal is normally automatically flushed by the operating terminal is normally automatically flushed by the operating
system. This option can be useful when the input or output is system. This option can be useful when the input or output is
attached to a pipe and you do not want pcregrep to buffer up attached to a pipe and you do not want pcregrep to buffer up
large amounts of data. However, its use will affect perfor- large amounts of data. However, its use will affect perfor-
mance, and the -M (multiline) option ceases to work. mance, and the -M (multiline) option ceases to work.
--line-offsets --line-offsets
Instead of showing lines or parts of lines that match, show Instead of showing lines or parts of lines that match, show
each match as a line number, the offset from the start of the each match as a line number, the offset from the start of the
skipping to change at line 434 skipping to change at line 434
(as usual; see the -n option), and the offset and length are (as usual; see the -n option), and the offset and length are
separated by a comma. In this mode, no context is shown. separated by a comma. In this mode, no context is shown.
That is, the -A, -B, and -C options are ignored. If there is That is, the -A, -B, and -C options are ignored. If there is
more than one match in a line, each of them is shown sepa- more than one match in a line, each of them is shown sepa-
rately. This option is mutually exclusive with --file-offsets rately. This option is mutually exclusive with --file-offsets
and --only-matching. and --only-matching.
--locale=locale-name --locale=locale-name
This option specifies a locale to be used for pattern match- This option specifies a locale to be used for pattern match-
ing. It overrides the value in the LC_ALL or LC_CTYPE envi- ing. It overrides the value in the LC_ALL or LC_CTYPE envi-
ronment variables. If no locale is specified, the PCRE ronment variables. If no locale is specified, the PCRE li-
library's default (usually the "C" locale) is used. There is brary's default (usually the "C" locale) is used. There is no
no short form for this option. short form for this option.
--match-limit=number --match-limit=number
Processing some regular expression patterns can require a Processing some regular expression patterns can require a
very large amount of memory, leading in some cases to a pro- very large amount of memory, leading in some cases to a pro-
gram crash if not enough is available. Other patterns may gram crash if not enough is available. Other patterns may
take a very long time to search for all possible matching take a very long time to search for all possible matching
strings. The pcre_exec() function that is called by pcregrep strings. The pcre_exec() function that is called by pcregrep
to do the matching has two parameters that can limit the to do the matching has two parameters that can limit the re-
resources that it uses. sources that it uses.
The --match-limit option provides a means of limiting The --match-limit option provides a means of limiting re-
resource usage when processing patterns that are not going to source usage when processing patterns that are not going to
match, but which have a very large number of possibilities in match, but which have a very large number of possibilities in
their search trees. The classic example is a pattern that their search trees. The classic example is a pattern that
uses nested unlimited repeats. Internally, PCRE uses a func- uses nested unlimited repeats. Internally, PCRE uses a func-
tion called match() which it calls repeatedly (sometimes tion called match() which it calls repeatedly (sometimes re-
recursively). The limit set by --match-limit is imposed on cursively). The limit set by --match-limit is imposed on the
the number of times this function is called during a match, number of times this function is called during a match, which
which has the effect of limiting the amount of backtracking has the effect of limiting the amount of backtracking that
that can take place. can take place.
The --recursion-limit option is similar to --match-limit, but The --recursion-limit option is similar to --match-limit, but
instead of limiting the total number of times that match() is instead of limiting the total number of times that match() is
called, it limits the depth of recursive calls, which in turn called, it limits the depth of recursive calls, which in turn
limits the amount of memory that can be used. The recursion limits the amount of memory that can be used. The recursion
depth is a smaller number than the total number of calls, depth is a smaller number than the total number of calls, be-
because not all calls to match() are recursive. This limit is cause not all calls to match() are recursive. This limit is
of use only if it is set smaller than --match-limit. of use only if it is set smaller than --match-limit.
There are no short forms for these options. The default set- There are no short forms for these options. The default set-
tings are specified when the PCRE library is compiled, with tings are specified when the PCRE library is compiled, with
the default default being 10 million. the default default being 10 million.
-M, --multiline -M, --multiline
Allow patterns to match more than one line. When this option Allow patterns to match more than one line. When this option
is given, patterns may usefully contain literal newline char- is given, patterns may usefully contain literal newline char-
acters and internal occurrences of ^ and $ characters. The acters and internal occurrences of ^ and $ characters. The
skipping to change at line 491 skipping to change at line 491
can be matched, imposed by the way that pcregrep buffers the can be matched, imposed by the way that pcregrep buffers the
input file as it scans it. However, pcregrep ensures that at input file as it scans it. However, pcregrep ensures that at
least 8K characters or the rest of the document (whichever is least 8K characters or the rest of the document (whichever is
the shorter) are available for forward matching, and simi- the shorter) are available for forward matching, and simi-
larly the previous 8K characters (or all the previous charac- larly the previous 8K characters (or all the previous charac-
ters, if fewer than 8K) are guaranteed to be available for ters, if fewer than 8K) are guaranteed to be available for
lookbehind assertions. This option does not work when input lookbehind assertions. This option does not work when input
is read line by line (see --line-buffered.) is read line by line (see --line-buffered.)
-N newline-type, --newline=newline-type -N newline-type, --newline=newline-type
The PCRE library supports five different conventions for The PCRE library supports five different conventions for in-
indicating the ends of lines. They are the single-character dicating the ends of lines. They are the single-character se-
sequences CR (carriage return) and LF (linefeed), the two- quences CR (carriage return) and LF (linefeed), the two-char-
character sequence CRLF, an "anycrlf" convention, which rec- acter sequence CRLF, an "anycrlf" convention, which recog-
ognizes any of the preceding three types, and an "any" con- nizes any of the preceding three types, and an "any" conven-
vention, in which any Unicode line ending sequence is assumed tion, in which any Unicode line ending sequence is assumed to
to end a line. The Unicode sequences are the three just men- end a line. The Unicode sequences are the three just men-
tioned, plus VT (vertical tab, U+000B), FF (form feed, tioned, plus VT (vertical tab, U+000B), FF (form feed,
U+000C), NEL (next line, U+0085), LS (line separator, U+000C), NEL (next line, U+0085), LS (line separator,
U+2028), and PS (paragraph separator, U+2029). U+2028), and PS (paragraph separator, U+2029).
When the PCRE library is built, a default line-ending When the PCRE library is built, a default line-ending se-
sequence is specified. This is normally the standard quence is specified. This is normally the standard sequence
sequence for the operating system. Unless otherwise specified for the operating system. Unless otherwise specified by this
by this option, pcregrep uses the library's default. The option, pcregrep uses the library's default. The possible
possible values for this option are CR, LF, CRLF, ANYCRLF, or values for this option are CR, LF, CRLF, ANYCRLF, or ANY.
ANY. This makes it possible to use pcregrep to scan files This makes it possible to use pcregrep to scan files that
that have come from other environments without having to mod- have come from other environments without having to modify
ify their line endings. If the data that is being scanned their line endings. If the data that is being scanned does
does not agree with the convention set by this option, pcre- not agree with the convention set by this option, pcregrep
grep may behave in strange ways. Note that this option does may behave in strange ways. Note that this option does not
not apply to files specified by the -f, --exclude-from, or apply to files specified by the -f, --exclude-from, or --in-
--include-from options, which are expected to use the operat- clude-from options, which are expected to use the operating
ing system's standard newline sequence. system's standard newline sequence.
-n, --line-number -n, --line-number
Precede each output line by its line number in the file, fol- Precede each output line by its line number in the file, fol-
lowed by a colon for matching lines or a hyphen for context lowed by a colon for matching lines or a hyphen for context
lines. If the filename is also being output, it precedes the lines. If the filename is also being output, it precedes the
line number. This option is forced if --line-offsets is used. line number. This option is forced if --line-offsets is used.
--no-jit If the PCRE library is built with support for just-in-time --no-jit If the PCRE library is built with support for just-in-time
compiling (which speeds up matching), pcregrep automatically compiling (which speeds up matching), pcregrep automatically
makes use of this, unless it was explicitly disabled at build makes use of this, unless it was explicitly disabled at build
time. This option can be used to disable the use of JIT at time. This option can be used to disable the use of JIT at
run time. It is provided for testing and working round prob- run time. It is provided for testing and working round prob-
lems. It should never be needed in normal use. lems. It should never be needed in normal use.
-o, --only-matching -o, --only-matching
Show only the part of the line that matched a pattern instead Show only the part of the line that matched a pattern instead
of the whole line. In this mode, no context is shown. That of the whole line. In this mode, no context is shown. That
is, the -A, -B, and -C options are ignored. If there is more is, the -A, -B, and -C options are ignored. If there is more
than one match in a line, each of them is shown separately. than one match in a line, each of them is shown separately.
If -o is combined with -v (invert the sense of the match to If -o is combined with -v (invert the sense of the match to
find non-matching lines), no output is generated, but the find non-matching lines), no output is generated, but the re-
return code is set appropriately. If the matched portion of turn code is set appropriately. If the matched portion of the
the line is empty, nothing is output unless the file name or line is empty, nothing is output unless the file name or line
line number are being printed, in which case they are shown number are being printed, in which case they are shown on an
on an otherwise empty line. This option is mutually exclusive otherwise empty line. This option is mutually exclusive with
with --file-offsets and --line-offsets. --file-offsets and --line-offsets.
-onumber, --only-matching=number -onumber, --only-matching=number
Show only the part of the line that matched the capturing Show only the part of the line that matched the capturing
parentheses of the given number. Up to 32 capturing parenthe- parentheses of the given number. Up to 32 capturing parenthe-
ses are supported, and -o0 is equivalent to -o without a num- ses are supported, and -o0 is equivalent to -o without a num-
ber. Because these options can be given without an argument ber. Because these options can be given without an argument
(see above), if an argument is present, it must be given in (see above), if an argument is present, it must be given in
the same shell item, for example, -o3 or --only-matching=2. the same shell item, for example, -o3 or --only-matching=2.
The comments given for the non-argument case above also apply The comments given for the non-argument case above also apply
to this case. If the specified capturing parentheses do not to this case. If the specified capturing parentheses do not
skipping to change at line 576 skipping to change at line 576
-q, --quiet -q, --quiet
Work quietly, that is, display nothing except error messages. Work quietly, that is, display nothing except error messages.
The exit status indicates whether or not any matches were The exit status indicates whether or not any matches were
found. found.
-r, --recursive -r, --recursive
If any given path is a directory, recursively scan the files If any given path is a directory, recursively scan the files
it contains, taking note of any --include and --exclude set- it contains, taking note of any --include and --exclude set-
tings. By default, a directory is read as a normal file; in tings. By default, a directory is read as a normal file; in
some operating systems this gives an immediate end-of-file. some operating systems this gives an immediate end-of-file.
This option is a shorthand for setting the -d option to This option is a shorthand for setting the -d option to "re-
"recurse". curse".
--recursion-limit=number --recursion-limit=number
See --match-limit above. See --match-limit above.
-s, --no-messages -s, --no-messages
Suppress error messages about non-existent or unreadable Suppress error messages about non-existent or unreadable
files. Such files are quietly skipped. However, the return files. Such files are quietly skipped. However, the return
code is still 2, even if matches were found in other files. code is still 2, even if matches were found in other files.
-u, --utf-8 -u, --utf-8
skipping to change at line 622 skipping to change at line 622
at the beginning of a line) and in addition, require them to at the beginning of a line) and in addition, require them to
match entire lines. This is equivalent to having ^ and $ match entire lines. This is equivalent to having ^ and $
characters at the start and end of each alternative branch in characters at the start and end of each alternative branch in
every pattern. This option applies only to the patterns that every pattern. This option applies only to the patterns that
are matched against the contents of files; it does not apply are matched against the contents of files; it does not apply
to patterns specified by any of the --include or --exclude to patterns specified by any of the --include or --exclude
options. options.
ENVIRONMENT VARIABLES ENVIRONMENT VARIABLES
The environment variables LC_ALL and LC_CTYPE are examined, in that The environment variables LC_ALL and LC_CTYPE are examined, in that or-
order, for a locale. The first one that is set is used. This can be der, for a locale. The first one that is set is used. This can be over-
overridden by the --locale option. If no locale is set, the PCRE ridden by the --locale option. If no locale is set, the PCRE library's
library's default (usually the "C" locale) is used. default (usually the "C" locale) is used.
NEWLINES NEWLINES
The -N (--newline) option allows pcregrep to scan files with different The -N (--newline) option allows pcregrep to scan files with different
newline conventions from the default. Any parts of the input files that newline conventions from the default. Any parts of the input files that
are written to the standard output are copied identically, with what- are written to the standard output are copied identically, with what-
ever newline sequences they have in the input. However, the setting of ever newline sequences they have in the input. However, the setting of
this option does not affect the interpretation of files specified by this option does not affect the interpretation of files specified by
the -f, --exclude-from, or --include-from options, which are assumed to the -f, --exclude-from, or --include-from options, which are assumed to
use the operating system's standard newline sequence, nor does it use the operating system's standard newline sequence, nor does it af-
affect the way in which pcregrep writes informational messages to the fect the way in which pcregrep writes informational messages to the
standard error and output streams. For these it uses the string "\n" to standard error and output streams. For these it uses the string "\n" to
indicate newlines, relying on the C I/O library to convert this to an indicate newlines, relying on the C I/O library to convert this to an
appropriate sequence. appropriate sequence.
OPTIONS COMPATIBILITY OPTIONS COMPATIBILITY
Many of the short and long forms of pcregrep's options are the same as Many of the short and long forms of pcregrep's options are the same as
in the GNU grep program. Any long option of the form --xxx-regexp (GNU in the GNU grep program. Any long option of the form --xxx-regexp (GNU
terminology) is also available as --xxx-regex (PCRE terminology). How- terminology) is also available as --xxx-regex (PCRE terminology). How-
ever, the --file-list, --file-offsets, --include-dir, --line-offsets, ever, the --file-list, --file-offsets, --include-dir, --line-offsets,
skipping to change at line 680 skipping to change at line 680
same item, for example -o3. same item, for example -o3.
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
line item, separated by an equals character, or (with two exceptions) line item, separated by an equals character, or (with two exceptions)
it may appear in the next command line item. For example: it may appear in the next command line item. For example:
--file=/some/file --file=/some/file
--file /some/file --file /some/file
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 ~
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 di-
directory, you must separate the file name from the option, because the rectory, you must separate the file name from the option, because the
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.
The exceptions to the above are the --colour (or --color) and --only- The exceptions to the above are the --colour (or --color) and --only-
matching options, for which the data is optional. If one of these matching options, for which the data is optional. If one of these op-
options does have data, it must be given in the first form, using an tions does have data, it must be given in the first form, using an
equals character. Otherwise pcregrep will assume that it has no data. equals character. Otherwise pcregrep will assume that it has no data.
MATCHING ERRORS MATCHING ERRORS
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
time to fail to match certain lines. Such patterns normally involve time to fail to match certain lines. Such patterns normally involve
nested indefinite repeats, for example: (a+)*\d when matched against a nested indefinite repeats, for example: (a+)*\d when matched against a
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 re-
resource limit that causes it to abort in these circumstances. If this source limit that causes it to abort in these circumstances. If this
happens, pcregrep outputs an error message and the line that caused the happens, pcregrep outputs an error message and the line that caused the
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
errors, pcregrep gives up. errors, pcregrep gives up.
The --match-limit option of pcregrep can be used to set the overall The --match-limit option of pcregrep can be used to set the overall re-
resource limit; there is a second option called --recursion-limit that source limit; there is a second option called --recursion-limit that
sets a limit on the amount of memory (usually stack) that is used (see sets a limit on the amount of memory (usually stack) that is used (see
the discussion of these options above). the discussion of these options above).
DIAGNOSTICS DIAGNOSTICS
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,
and 2 for syntax errors, overlong lines, non-existent or inaccessible and 2 for syntax errors, overlong lines, non-existent or inaccessible
files (even if matches were found in other files) or too many matching files (even if matches were found in other files) or too many matching
errors. Using the -s option to suppress error messages about inaccessi- errors. Using the -s option to suppress error messages about inaccessi-
ble files does not affect the return code. ble files does not affect the return code.
 End of changes. 35 change blocks. 
116 lines changed or deleted 116 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)