/[pcre]/code/trunk/doc/pcregrep.1

Diff of /code/trunk/doc/pcregrep.1

Parent Directory | Revision Log | View Patch Patch

-revision 281 by ph10,
Fri Dec  7 15:57:05 2007 UTC
+revision 583 by ph10,
Tue Jan 11 16:49:55 2011 UTC
 Line 47 
 possible to search for patterns that spa
  boundary is controlled by the \fB-N\fP (\fB--newline\fP) option.
  .P
  Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.
  BUFSIZ is defined in \fB<stdio.h>\fP. When there is more than one pattern
  (specified by the use of \fB-e\fP and/or \fB-f\fP), each pattern is applied to
  each line in the order in which they are defined, except that all the \fB-e\fP
- patterns are tried before the \fB-f\fP patterns. As soon as one pattern matches
+ patterns are tried before the \fB-f\fP patterns.
- (or fails to match when \fB-v\fP is used), no further patterns are considered.
  .P
- When \fB--only-matching\fP, \fB--file-offsets\fP, or \fB--line-offsets\fP
+ By default, as soon as one pattern matches (or fails to match when \fB-v\fP is
- is used, the output is the part of the line that matched (either shown
+ used), no further patterns are considered. However, if \fB--colour\fP (or
- literally, or as an offset). In this case, scanning resumes immediately
+ \fB--color\fP) is used to colour the matching substrings, or if
- following the match, so that further matches on the same line can be found.
+ \fB--only-matching\fP, \fB--file-offsets\fP, or \fB--line-offsets\fP is used to
- If there are multiple patterns, they are all tried on the remainder of the
+ output only the part of the line that matched (either shown literally, or as an
- line. However, patterns that follow the one that matched are not tried on the
+ offset), scanning resumes immediately following the match, so that further
- earlier part of the line.
+ matches on the same line can be found. If there are multiple patterns, they are
+ all tried on the remainder of the line, but patterns that follow the one that
+ matched are not tried on the earlier part of the line.
+ .P
+ This is the same behaviour as GNU grep, but it does mean that the order in
+ which multiple patterns are specified can affect the output when one of the
+ above options is used.
+ .P
+ Patterns that can match an empty string are accepted, but empty string
+ matches are never recognized. An example is the pattern "(super)?(man)?", in
+ which all components are optional. This pattern finds all occurrences of both
+ "super" and "man"; the output differs from matching with "super|man" when only
+ the matching substrings are being shown.
  .P
  If the \fBLC_ALL\fP or \fBLC_CTYPE\fP environment variable is set,
  \fBpcregrep\fP uses the value to set a locale when calling the PCRE library.
  The \fB--locale\fP option can be used to override this.
  .
+ .SH "SUPPORT FOR COMPRESSED FILES"
+ .rs
+ .sp
+ It is possible to compile \fBpcregrep\fP so that it uses \fBlibz\fP or
+ \fBlibbz2\fP to read files whose names end in \fB.gz\fP or \fB.bz2\fP,
+ respectively. You can find out whether your binary has support for one or both
+ of these file types by running it with the \fB--help\fP option. If the
+ appropriate support is not present, files are treated as plain text. The
+ standard input is always so treated.
+ .
  .SH OPTIONS
  .rs
+ .sp
+ The order in which some of the options appear can affect the output. For
+ example, both the \fB-h\fP and \fB-l\fP options affect the printing of file
+ names. Whichever comes later in the command line will be the one that takes
+ effect.
  .TP 10
  \fB--\fP
  This terminate the list of options. It is useful if the next item on the
-Line 94 
 Output \fInumber\fP lines of context bot
+Line 120 
 Output \fInumber\fP lines of context bot
  This is equivalent to setting both \fB-A\fP and \fB-B\fP to the same value.
  .TP
  \fB-c\fP, \fB--count\fP
- Do not output individual lines; instead just output a count of the number of
+ Do not output individual lines from the files that are being scanned; instead
- lines that would otherwise have been output. If several files are given, a
+ output the number of lines that would otherwise have been shown. If no lines
- count is output for each of them. In this mode, the \fB-A\fP, \fB-B\fP, and
+ are selected, the number zero is output. If several files are are being
- \fB-C\fP options are ignored.
+ scanned, a count is output for each of them. However, if the
+ \fB--files-with-matches\fP option is also used, only those files whose counts
+ are greater than zero are listed. When \fB-c\fP is used, the \fB-A\fP,
+ \fB-B\fP, and \fB-C\fP options are ignored.
  .TP
  \fB--colour\fP, \fB--color\fP
  If this option is given without any data, it is equivalent to "--colour=auto".
-Line 105 
 If data is required, it must be given in
+Line 134 
 If data is required, it must be given in
  equals sign.
  .TP
  \fB--colour=\fP\fIvalue\fP, \fB--color=\fP\fIvalue\fP
- This option specifies under what circumstances the part of a line that matched
+ This option specifies under what circumstances the parts of a line that matched
- a pattern should be coloured in the output. The value may be "never" (the
+ a pattern should be coloured in the output. By default, the output is not
- default), "always", or "auto". In the latter case, colouring happens only if
+ coloured. The value (which is optional, see above) may be "never", "always", or
- the standard output is connected to a terminal. The colour can be specified by
+ "auto". In the latter case, colouring happens only if the standard output is
- setting the environment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
+ connected to a terminal. More resources are used when colouring is enabled,
- of this variable should be a string of two numbers, separated by a semicolon.
+ because \fBpcregrep\fP has to search for all possible matches in a line, not
- They are copied directly into the control string for setting colour on a
+ just one, in order to colour them all.
- terminal, so it is your responsibility to ensure that they make sense. If
+ .sp
- neither of the environment variables is set, the default is "1;31", which gives
+ The colour that is used can be specified by setting the environment variable
- red.
+ PCREGREP_COLOUR or PCREGREP_COLOR. The value of this variable should be a
+ string of two numbers, separated by a semicolon. They are copied directly into
+ the control string for setting colour on a terminal, so it is your
+ responsibility to ensure that they make sense. If neither of the environment
+ variables is set, the default is "1;31", which gives red.
  .TP
  \fB-D\fP \fIaction\fP, \fB--devices=\fP\fIaction\fP
  If an input path is not a regular file or a directory, "action" specifies how
-Line 128 
 option), or "skip" (silently skip the pa
+Line 161 
 option), or "skip" (silently skip the pa
  are read as if they were ordinary files. In some operating systems the effect
  of reading a directory like this is an immediate end-of-file.
  .TP
  \fB-e\fP \fIpattern\fP, \fB--regex=\fP\fIpattern\fP, \fB--regexp=\fP\fIpattern\fP
  Specify a pattern to be matched. This option can be used multiple times in
  order to specify several patterns. It can also be used as a way of specifying a
  single pattern that starts with a hyphen. When \fB-e\fP is used, no argument
-Line 147 
 that matched.
+Line 180 
 that matched.
  .TP
  \fB--exclude\fP=\fIpattern\fP
  When \fBpcregrep\fP is searching the files in a directory as a consequence of
- the \fB-r\fP (recursive search) option, any files whose names match the pattern
+ the \fB-r\fP (recursive search) option, any regular files whose names match the
- are excluded. The pattern is a PCRE regular expression. If a file name matches
+ pattern are excluded. Subdirectories are not excluded by this option; they are
- both \fB--include\fP and \fB--exclude\fP, it is excluded. There is no short
+ searched recursively, subject to the \fB--exclude-dir\fP and
- form for this option.
+ \fB--include_dir\fP options. The pattern is a PCRE regular expression, and is
+ matched against the final component of the file name (not the entire path). If
+ a file name matches both \fB--include\fP and \fB--exclude\fP, it is excluded.
+ There is no short form for this option.
+ .TP
+ \fB--exclude-dir\fP=\fIpattern\fP
+ When \fBpcregrep\fP is searching the contents of a directory as a consequence
+ of the \fB-r\fP (recursive search) option, any subdirectories whose names match
+ the pattern are excluded. (Note that the \fP--exclude\fP option does not affect
+ subdirectories.) The pattern is a PCRE regular expression, and is matched
+ against the final component of the name (not the entire path). If a
+ subdirectory name matches both \fB--include-dir\fP and \fB--exclude-dir\fP, it
+ is excluded. There is no short form for this option.
  .TP
  \fB-F\fP, \fB--fixed-strings\fP
  Interpret each pattern as a list of fixed strings, separated by newlines,
-Line 168 
 present; they are tested before the file
+Line 213 
 present; they are tested before the file
  is taken from the command line; all arguments are treated as file names. There
  is an overall maximum of 100 patterns. Trailing white space is removed from
  each line, and blank lines are ignored. An empty file contains no patterns and
  therefore matches nothing. See also the comments about multiple patterns versus
  a single pattern with alternatives in the description of \fB-e\fP above.
  .TP
  \fB--file-offsets\fP
-Line 182 
 and \fB--only-matching\fP.
+Line 227 
 and \fB--only-matching\fP.
  \fB-H\fP, \fB--with-filename\fP
  Force the inclusion of the filename at the start of output lines when searching
  a single file. By default, the filename is not shown in this case. For matching
- lines, the filename is followed by a colon and a space; for context lines, a
+ lines, the filename is followed by a colon; for context lines, a hyphen
- hyphen separator is used. If a line number is also being output, it follows the
+ separator is used. If a line number is also being output, it follows the file
- file name without a space.
+ name.
  .TP
  \fB-h\fP, \fB--no-filename\fP
  Suppress the output filenames when searching multiple files. By default,
  filenames are shown when multiple files are searched. For matching lines, the
- filename is followed by a colon and a space; for context lines, a hyphen
+ filename is followed by a colon; for context lines, a hyphen separator is used.
- separator is used. If a line number is also being output, it follows the file
+ If a line number is also being output, it follows the file name.
- name without a space.
  .TP
  \fB--help\fP
- Output a brief help message and exit.
+ Output a help message, giving brief details of the command options and file
+ type support, and then exit.
  .TP
  \fB-i\fP, \fB--ignore-case\fP
  Ignore upper/lower case distinctions during comparisons.
  .TP
  \fB--include\fP=\fIpattern\fP
  When \fBpcregrep\fP is searching the files in a directory as a consequence of
- the \fB-r\fP (recursive search) option, only those files whose names match the
+ the \fB-r\fP (recursive search) option, only those regular files whose names
- pattern are included. The pattern is a PCRE regular expression. If a file name
+ match the pattern are included. Subdirectories are always included and searched
- matches both \fB--include\fP and \fB--exclude\fP, it is excluded. There is no
+ recursively, subject to the \fP--include-dir\fP and \fB--exclude-dir\fP
- short form for this option.
+ options. The pattern is a PCRE regular expression, and is matched against the
+ final component of the file name (not the entire path). If a file name matches
+ both \fB--include\fP and \fB--exclude\fP, it is excluded. There is no short
+ form for this option.
+ .TP
+ \fB--include-dir\fP=\fIpattern\fP
+ When \fBpcregrep\fP is searching the contents of a directory as a consequence
+ of the \fB-r\fP (recursive search) option, only those subdirectories whose
+ names match the pattern are included. (Note that the \fB--include\fP option
+ does not affect subdirectories.) The pattern is a PCRE regular expression, and
+ is matched against the final component of the name (not the entire path). If a
+ subdirectory name matches both \fB--include-dir\fP and \fB--exclude-dir\fP, it
+ is excluded. There is no short form for this option.
  .TP
  \fB-L\fP, \fB--files-without-match\fP
  Instead of outputting lines from the files, just output the names of the files
-Line 214 
 output once, on a separate line.
+Line 271 
 output once, on a separate line.
  \fB-l\fP, \fB--files-with-matches\fP
  Instead of outputting lines from the files, just output the names of the files
  containing lines that would have been output. Each file name is output
- once, on a separate line. Searching stops as soon as a matching line is found
+ once, on a separate line. Searching normally stops as soon as a matching line
- in a file.
+ is found in a file. However, if the \fB-c\fP (count) option is also used,
+ matching continues in order to obtain the correct count, and those files that
+ have at least one match are listed along with their counts. Using this option
+ with \fB-c\fP is a way of suppressing the listing of files with no matches.
  .TP
  \fB--label\fP=\fIname\fP
  This option supplies a name to be used for the standard input when file names
  are being output. If not supplied, "(standard input)" is used. There is no
  short form for this option.
  .TP
+ \fB--line-buffered\fP
+ When this option is given, input is read and processed line by line, and the
+ output is flushed after each write. By default, input is read in large chunks,
+ unless \fBpcregrep\fP can determine that it is reading from a terminal (which
+ is currently possible only in Unix environments). Output to terminal is
+ normally automatically flushed by the operating system. This option can be
+ useful when the input or output is attached to a pipe and you do not want
+ \fBpcregrep\fP to buffer up large amounts of data. However, its use will affect
+ performance, and the \fB-M\fP (multiline) option ceases to work.
+ .TP
  \fB--line-offsets\fP
  Instead of showing lines or parts of lines that match, show each match as a
  line number, the offset from the start of the line, and a length. The line
  number is terminated by a colon (as usual; see the \fB-n\fP option), and the
  offset and length are separated by a comma. In this mode, no context is shown.
  That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP options are ignored. If there is
  more than one match in a line, each of them is shown separately. This option is
-Line 237 
 the value in the \fBLC_ALL\fP or \fBLC_C
+Line 307 
 the value in the \fBLC_ALL\fP or \fBLC_C
  locale is specified, the PCRE library's default (usually the "C" locale) is
  used. There is no short form for this option.
  .TP
+ \fB--match-limit\fP=\fInumber\fP
+ Processing some regular expression patterns can require a very large amount of
+ memory, leading in some cases to a program crash if not enough is available.
+ Other patterns may take a very long time to search for all possible matching
+ strings. The \fBpcre_exec()\fP function that is called by \fBpcregrep\fP to do
+ the matching has two parameters that can limit the resources that it uses.
+ .sp
+ The \fB--match-limit\fP option provides a means of limiting resource usage
+ when processing patterns that are not going to match, but which have a very
+ large number of possibilities in their search trees. The classic example is a
+ pattern that uses nested unlimited repeats. Internally, PCRE uses a function
+ called \fBmatch()\fP which it calls repeatedly (sometimes recursively). The
+ limit set by \fB--match-limit\fP is imposed on the number of times this
+ function is called during a match, which has the effect of limiting the amount
+ of backtracking that can take place.
+ .sp
+ The \fB--recursion-limit\fP option is similar to \fB--match-limit\fP, but
+ instead of limiting the total number of times that \fBmatch()\fP is called, it
+ limits the depth of recursive calls, which in turn limits the amount of memory
+ that can be used. The recursion depth is a smaller number than the total number
+ of calls, because not all calls to \fBmatch()\fP are recursive. This limit is
+ of use only if it is set smaller than \fB--match-limit\fP.
+ .sp
+ There are no short forms for these options. The default settings are specified
+ when the PCRE library is compiled, with the default default being 10 million.
+ .TP
  \fB-M\fP, \fB--multiline\fP
  Allow patterns to match more than one line. When this option is given, patterns
  may usefully contain literal newline characters and internal occurrences of ^
-Line 247 
 that \fBpcregrep\fP buffers the input fi
+Line 343 
 that \fBpcregrep\fP buffers the input fi
  \fBpcregrep\fP ensures that at least 8K characters or the rest of the document
  (whichever is the shorter) are available for forward matching, and similarly
  the previous 8K characters (or all the previous characters, if fewer than 8K)
- are guaranteed to be available for lookbehind assertions.
+ are guaranteed to be available for lookbehind assertions. This option does not
+ work when input is read line by line (see \fP--line-buffered\fP.)
  .TP
- \fB-N\fP \fInewline-type\fP, \fB--newline=\fP\fInewline-type\fP
+ \fB-N\fP \fInewline-type\fP, \fB--newline\fP=\fInewline-type\fP
  The PCRE library supports five different conventions for indicating
  the ends of lines. They are the single-character sequences CR (carriage return)
  and LF (linefeed), the two-character sequence CRLF, an "anycrlf" convention,
-Line 270 
 being scanned does not agree with the co
+Line 367 
 being scanned does not agree with the co
  .TP
  \fB-n\fP, \fB--line-number\fP
  Precede each output line by its line number in the file, followed by a colon
- and a space for matching lines or a hyphen and a space for context lines. If
+ for matching lines or a hyphen for context lines. If the filename is also being
- the filename is also being output, it precedes the line number. This option is
+ output, it precedes the line number. This option is forced if
- forced if \fB--line-offsets\fP is used.
+ \fB--line-offsets\fP is used.
  .TP
  \fB-o\fP, \fB--only-matching\fP
- Show only the part of the line that matched a pattern. In this mode, no
+ Show only the part of the line that matched a pattern instead of the whole
- context is shown. That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP options are
+ line. In this mode, no context is shown. That is, the \fB-A\fP, \fB-B\fP, and
- ignored. If there is more than one match in a line, each of them is shown
+ \fB-C\fP options are ignored. If there is more than one match in a line, each
- separately. If \fB-o\fP is combined with \fB-v\fP (invert the sense of the
+ of them is shown separately. If \fB-o\fP is combined with \fB-v\fP (invert the
- match to find non-matching lines), no output is generated, but the return code
+ sense of the match to find non-matching lines), no output is generated, but the
- is set appropriately. This option is mutually exclusive with
+ return code is set appropriately. If the matched portion of the line is empty,
- \fB--file-offsets\fP and \fB--line-offsets\fP.
+ nothing is output unless the file name or line number are being printed, in
+ which case they are shown on an otherwise empty line. This option is mutually
+ exclusive with \fB--file-offsets\fP and \fB--line-offsets\fP.
+ .TP
+ \fB-o\fP\fInumber\fP, \fB--only-matching\fP=\fInumber\fP
+ Show only the part of the line that matched the capturing parentheses of the
+ given number. Up to 32 capturing parentheses are supported. Because these
+ options can be given without an argument (see above), if an argument is
+ present, it must be given in the same shell item, for example, -o3 or
+ --only-matching=2. The comments given for the non-argument case above also
+ apply to this case. If the specified capturing parentheses do not exist in the
+ pattern, or were not set in the match, nothing is output unless the file name
+ or line number are being printed.
  .TP
  \fB-q\fP, \fB--quiet\fP
  Work quietly, that is, display nothing except error messages. The exit
-Line 294 
 directory is read as a normal file; in s
+Line 403 
 directory is read as a normal file; in s
  immediate end-of-file. This option is a shorthand for setting the \fB-d\fP
  option to "recurse".
  .TP
+ \fB--recursion-limit\fP=\fInumber\fP
+ See \fB--match-limit\fP above.
+ .TP
  \fB-s\fP, \fB--no-messages\fP
  Suppress error messages about non-existent or unreadable files. Such files are
  quietly skipped. However, the return code is still 2, even if matches were
-Line 346 
 convert this to an appropriate sequence
+Line 458 
 convert this to an appropriate sequence
  .SH "OPTIONS COMPATIBILITY"
  .rs
  .sp
- The majority of short and long forms of \fBpcregrep\fP's options are the same
+ Many of the short and long forms of \fBpcregrep\fP's options are the same
- as in the GNU \fBgrep\fP program. Any long option of the form
+ as in the GNU \fBgrep\fP program (version 2.5.4). Any long option of the form
  \fB--xxx-regexp\fP (GNU terminology) is also available as \fB--xxx-regex\fP
- (PCRE terminology). However, the \fB--locale\fP, \fB-M\fP, \fB--multiline\fP,
+ (PCRE terminology). However, the \fB--file-offsets\fP, \fB--include-dir\fP,
- \fB-u\fP, and \fB--utf-8\fP options are specific to \fBpcregrep\fP.
+ \fB--line-offsets\fP, \fB--locale\fP, \fB--match-limit\fP, \fB-M\fP,
+ \fB--multiline\fP, \fB-N\fP, \fB--newline\fP, \fB--recursion-limit\fP,
+ \fB-u\fP, and \fB--utf-8\fP options are specific to \fBpcregrep\fP, as is the
+ use of the \fB--only-matching\fP option with a capturing parentheses number.
+ .P
+ Although most of the common options work the same way, a few are different in
+ \fBpcregrep\fP. For example, the \fB--include\fP option's argument is a glob
+ for GNU \fBgrep\fP, but a regular expression for \fBpcregrep\fP. If both the
+ \fB-c\fP and \fB-l\fP options are given, GNU grep lists only file names,
+ without counts, but \fBpcregrep\fP gives the counts.
  .
  .
  .SH "OPTIONS WITH DATA"
  .rs
  .sp
  There are four different ways in which an option with data can be specified.
- If a short form option is used, the data may follow immediately, or in the next
+ If a short form option is used, the data may follow immediately, or (with one
- command line item. For example:
+ exception) in the next command line item. For example:
  .sp
    -f/some/file
    -f /some/file
  .sp
+ The exception is the \fB-o\fP option, which may appear with or without data.
+ Because of this, if data is present, it must follow immediately in the same
+ item, for example -o3.
+ .P
  If a long form option is used, the data may appear in the same command line
- item, separated by an equals character, or (with one exception) it may appear
+ item, separated by an equals character, or (with two exceptions) it may appear
  in the next command line item. For example:
  .sp
    --file=/some/file
-Line 375 
 in a shell command, and have the shell e
+Line 500 
 in a shell command, and have the shell e
  separate the file name from the option, because the shell does not treat ~
  specially unless it is at the start of an item.
  .P
- The exception to the above is the \fB--colour\fP (or \fB--color\fP) option,
+ The exceptions to the above are the \fB--colour\fP (or \fB--color\fP) and
- for which the data is optional. If this option does have data, it must be given
+ \fB--only-matching\fP options, for which the data is optional. If one of these
- in the first form, using an equals character. Otherwise it will be assumed that
+ options does have data, it must be given in the first form, using an equals
- it has no data.
+ character. Otherwise \fBpcregrep\fP will assume that it has no data.
  .
  .
  .SH "MATCHING ERRORS"
-Line 391 
 digit. The PCRE matching function has a
+Line 516 
 digit. The PCRE matching function has a
  in these circumstances. If this happens, \fBpcregrep\fP outputs an error
  message and the line that caused the problem to the standard error stream. If
  there are more than 20 such errors, \fBpcregrep\fP gives up.
+ .P
+ The \fB--match-limit\fP option of \fBpcregrep\fP can be used to set the overall
+ resource limit; there is a second option called \fB--recursion-limit\fP that
+ sets a limit on the amount of memory (usually stack) that is used (see the
+ discussion of these options above).
  .
  .
  .SH DIAGNOSTICS
-Line 423 
 Cambridge CB2 3QH, England.
+Line 553 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 07 December 2007
+ Last updated: 16 November 2010
- Copyright (c) 1997-2007 University of Cambridge.
+ Copyright (c) 1997-2010 University of Cambridge.
  .fi

 Legend:



Removed from v.281
 


changed lines


 
Added in v.583
 Legend:



Removed from v.281
 


changed lines


 
Added in v.583
-Removed from v.281
+Added in v.583

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12