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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 91 by nigel, Sat Feb 24 21:41:34 2007 UTC revision 579 by ph10, Wed Nov 24 17:39:25 2010 UTC
# Line 11  pcregrep - a grep with Perl-compatible r Line 11  pcregrep - a grep with Perl-compatible r
11  grep commands do, but it uses the PCRE regular expression library to support  grep commands do, but it uses the PCRE regular expression library to support
12  patterns that are compatible with the regular expressions of Perl 5. See  patterns that are compatible with the regular expressions of Perl 5. See
13  .\" HREF  .\" HREF
14  \fBpcrepattern\fP  \fBpcrepattern\fP(3)
15  .\"  .\"
16  for a full description of syntax and semantics of the regular expressions that  for a full description of syntax and semantics of the regular expressions
17  PCRE supports.  that PCRE supports.
18  .P  .P
19  Patterns, whether supplied on the command line or in a separate file, are given  Patterns, whether supplied on the command line or in a separate file, are given
20  without delimiters. For example:  without delimiters. For example:
# Line 23  without delimiters. For example: Line 23  without delimiters. For example:
23  .sp  .sp
24  If you attempt to use delimiters (for example, by surrounding a pattern with  If you attempt to use delimiters (for example, by surrounding a pattern with
25  slashes, as is common in Perl scripts), they are interpreted as part of the  slashes, as is common in Perl scripts), they are interpreted as part of the
26  pattern. Quotes can of course be used on the command line because they are  pattern. Quotes can of course be used to delimit patterns on the command line
27  interpreted by the shell, and indeed they are required if a pattern contains  because they are interpreted by the shell, and indeed they are required if a
28  white space or shell metacharacters.  pattern contains white space or shell metacharacters.
29  .P  .P
30  The first argument that follows any option settings is treated as the single  The first argument that follows any option settings is treated as the single
31  pattern to be matched when neither \fB-e\fP nor \fB-f\fP is present.  pattern to be matched when neither \fB-e\fP nor \fB-f\fP is present.
# Line 39  For example: Line 39  For example:
39  .sp  .sp
40    pcregrep some-pattern /file1 - /file3    pcregrep some-pattern /file1 - /file3
41  .sp  .sp
42  By default, each line that matches the pattern is copied to the standard  By default, each line that matches a pattern is copied to the standard
43  output, and if there is more than one file, the file name is output at the  output, and if there is more than one file, the file name is output at the
44  start of each line. However, there are options that can change how  start of each line, followed by a colon. However, there are options that can
45  \fBpcregrep\fP behaves. In particular, the \fB-M\fP option makes it possible to  change how \fBpcregrep\fP behaves. In particular, the \fB-M\fP option makes it
46  search for patterns that span line boundaries. What defines a line boundary is  possible to search for patterns that span line boundaries. What defines a line
47  controlled by the \fB-N\fP (\fB--newline\fP) option.  boundary is controlled by the \fB-N\fP (\fB--newline\fP) option.
48  .P  .P
49  Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.  Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.
50  BUFSIZ is defined in \fB<stdio.h>\fP.  BUFSIZ is defined in \fB<stdio.h>\fP. When there is more than one pattern
51    (specified by the use of \fB-e\fP and/or \fB-f\fP), each pattern is applied to
52    each line in the order in which they are defined, except that all the \fB-e\fP
53    patterns are tried before the \fB-f\fP patterns.
54    .P
55    By default, as soon as one pattern matches (or fails to match when \fB-v\fP is
56    used), no further patterns are considered. However, if \fB--colour\fP (or
57    \fB--color\fP) is used to colour the matching substrings, or if
58    \fB--only-matching\fP, \fB--file-offsets\fP, or \fB--line-offsets\fP is used to
59    output only the part of the line that matched (either shown literally, or as an
60    offset), scanning resumes immediately following the match, so that further
61    matches on the same line can be found. If there are multiple patterns, they are
62    all tried on the remainder of the line, but patterns that follow the one that
63    matched are not tried on the earlier part of the line.
64    .P
65    This is the same behaviour as GNU grep, but it does mean that the order in
66    which multiple patterns are specified can affect the output when one of the
67    above options is used.
68    .P
69    Patterns that can match an empty string are accepted, but empty string
70    matches are never recognized. An example is the pattern "(super)?(man)?", in
71    which all components are optional. This pattern finds all occurrences of both
72    "super" and "man"; the output differs from matching with "super|man" when only
73    the matching substrings are being shown.
74  .P  .P
75  If the \fBLC_ALL\fP or \fBLC_CTYPE\fP environment variable is set,  If the \fBLC_ALL\fP or \fBLC_CTYPE\fP environment variable is set,
76  \fBpcregrep\fP uses the value to set a locale when calling the PCRE library.  \fBpcregrep\fP uses the value to set a locale when calling the PCRE library.
77  The \fB--locale\fP option can be used to override this.  The \fB--locale\fP option can be used to override this.
78  .  .
79    .SH "SUPPORT FOR COMPRESSED FILES"
80    .rs
81    .sp
82    It is possible to compile \fBpcregrep\fP so that it uses \fBlibz\fP or
83    \fBlibbz2\fP to read files whose names end in \fB.gz\fP or \fB.bz2\fP,
84    respectively. You can find out whether your binary has support for one or both
85    of these file types by running it with the \fB--help\fP option. If the
86    appropriate support is not present, files are treated as plain text. The
87    standard input is always so treated.
88    .
89  .SH OPTIONS  .SH OPTIONS
90  .rs  .rs
91    .sp
92    The order in which some of the options appear can affect the output. For
93    example, both the \fB-h\fP and \fB-l\fP options affect the printing of file
94    names. Whichever comes later in the command line will be the one that takes
95    effect.
96  .TP 10  .TP 10
97  \fB--\fP  \fB--\fP
98  This terminate the list of options. It is useful if the next item on the  This terminate the list of options. It is useful if the next item on the
# Line 82  Output \fInumber\fP lines of context bot Line 120  Output \fInumber\fP lines of context bot
120  This is equivalent to setting both \fB-A\fP and \fB-B\fP to the same value.  This is equivalent to setting both \fB-A\fP and \fB-B\fP to the same value.
121  .TP  .TP
122  \fB-c\fP, \fB--count\fP  \fB-c\fP, \fB--count\fP
123  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
124  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
125  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
126  \fB-C\fP options are ignored.  scanned, a count is output for each of them. However, if the
127    \fB--files-with-matches\fP option is also used, only those files whose counts
128    are greater than zero are listed. When \fB-c\fP is used, the \fB-A\fP,
129    \fB-B\fP, and \fB-C\fP options are ignored.
130  .TP  .TP
131  \fB--colour\fP, \fB--color\fP  \fB--colour\fP, \fB--color\fP
132  If this option is given without any data, it is equivalent to "--colour=auto".  If this option is given without any data, it is equivalent to "--colour=auto".
# Line 93  If data is required, it must be given in Line 134  If data is required, it must be given in
134  equals sign.  equals sign.
135  .TP  .TP
136  \fB--colour=\fP\fIvalue\fP, \fB--color=\fP\fIvalue\fP  \fB--colour=\fP\fIvalue\fP, \fB--color=\fP\fIvalue\fP
137  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
138  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
139  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
140  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
141  setting the environment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value  connected to a terminal. More resources are used when colouring is enabled,
142  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
143  They are copied directly into the control string for setting colour on a  just one, in order to colour them all.
144  terminal, so it is your responsibility to ensure that they make sense. If  .sp
145  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
146  red.  PCREGREP_COLOUR or PCREGREP_COLOR. The value of this variable should be a
147    string of two numbers, separated by a semicolon. They are copied directly into
148    the control string for setting colour on a terminal, so it is your
149    responsibility to ensure that they make sense. If neither of the environment
150    variables is set, the default is "1;31", which gives red.
151  .TP  .TP
152  \fB-D\fP \fIaction\fP, \fB--devices=\fP\fIaction\fP  \fB-D\fP \fIaction\fP, \fB--devices=\fP\fIaction\fP
153  If an input path is not a regular file or a directory, "action" specifies how  If an input path is not a regular file or a directory, "action" specifies how
# Line 116  option), or "skip" (silently skip the pa Line 161  option), or "skip" (silently skip the pa
161  are read as if they were ordinary files. In some operating systems the effect  are read as if they were ordinary files. In some operating systems the effect
162  of reading a directory like this is an immediate end-of-file.  of reading a directory like this is an immediate end-of-file.
163  .TP  .TP
164  \fB-e\fP \fIpattern\fP, \fB--regex=\fP\fIpattern\fP,  \fB-e\fP \fIpattern\fP, \fB--regex=\fP\fIpattern\fP, \fB--regexp=\fP\fIpattern\fP
165  \fB--regexp=\fP\fIpattern\fP Specify a pattern to be matched. This option can  Specify a pattern to be matched. This option can be used multiple times in
166  be used multiple times in order to specify several patterns. It can also be  order to specify several patterns. It can also be used as a way of specifying a
167  used as a way of specifying a single pattern that starts with a hyphen. When  single pattern that starts with a hyphen. When \fB-e\fP is used, no argument
168  \fB-e\fP is used, no argument pattern is taken from the command line; all  pattern is taken from the command line; all arguments are treated as file
169  arguments are treated as file names. There is an overall maximum of 100  names. There is an overall maximum of 100 patterns. They are applied to each
170  patterns. They are applied to each line in the order in which they are defined  line in the order in which they are defined until one matches (or fails to
171  until one matches (or fails to match if \fB-v\fP is used). If \fB-f\fP is used  match if \fB-v\fP is used). If \fB-f\fP is used with \fB-e\fP, the command line
172  with \fB-e\fP, the command line patterns are matched first, followed by the  patterns are matched first, followed by the patterns from the file, independent
173  patterns from the file, independent of the order in which these options are  of the order in which these options are specified. Note that multiple use of
174  specified. Note that multiple use of \fB-e\fP is not the same as a single  \fB-e\fP is not the same as a single pattern with alternatives. For example,
175  pattern with alternatives. For example, X|Y finds the first character in a line  X|Y finds the first character in a line that is X or Y, whereas if the two
176  that is X or Y, whereas if the two patterns are given separately,  patterns are given separately, \fBpcregrep\fP finds X if it is present, even if
177  \fBpcregrep\fP finds X if it is present, even if it follows Y in the line. It  it follows Y in the line. It finds Y only if there is no X in the line. This
178  finds Y only if there is no X in the line. This really matters only if you are  really matters only if you are using \fB-o\fP to show the part(s) of the line
179  using \fB-o\fP to show the portion of the line that matched.  that matched.
180  .TP  .TP
181  \fB--exclude\fP=\fIpattern\fP  \fB--exclude\fP=\fIpattern\fP
182  When \fBpcregrep\fP is searching the files in a directory as a consequence of  When \fBpcregrep\fP is searching the files in a directory as a consequence of
183  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
184  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
185  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
186  form for this option.  \fB--include_dir\fP options. The pattern is a PCRE regular expression, and is
187    matched against the final component of the file name (not the entire path). If
188    a file name matches both \fB--include\fP and \fB--exclude\fP, it is excluded.
189    There is no short form for this option.
190    .TP
191    \fB--exclude-dir\fP=\fIpattern\fP
192    When \fBpcregrep\fP is searching the contents of a directory as a consequence
193    of the \fB-r\fP (recursive search) option, any subdirectories whose names match
194    the pattern are excluded. (Note that the \fP--exclude\fP option does not affect
195    subdirectories.) The pattern is a PCRE regular expression, and is matched
196    against the final component of the name (not the entire path). If a
197    subdirectory name matches both \fB--include-dir\fP and \fB--exclude-dir\fP, it
198    is excluded. There is no short form for this option.
199  .TP  .TP
200  \fB-F\fP, \fB--fixed-strings\fP  \fB-F\fP, \fB--fixed-strings\fP
201  Interpret each pattern as a list of fixed strings, separated by newlines,  Interpret each pattern as a list of fixed strings, separated by newlines,
# Line 156  present; they are tested before the file Line 213  present; they are tested before the file
213  is taken from the command line; all arguments are treated as file names. There  is taken from the command line; all arguments are treated as file names. There
214  is an overall maximum of 100 patterns. Trailing white space is removed from  is an overall maximum of 100 patterns. Trailing white space is removed from
215  each line, and blank lines are ignored. An empty file contains no patterns and  each line, and blank lines are ignored. An empty file contains no patterns and
216  therefore matches nothing.  therefore matches nothing. See also the comments about multiple patterns versus
217    a single pattern with alternatives in the description of \fB-e\fP above.
218    .TP
219    \fB--file-offsets\fP
220    Instead of showing lines or parts of lines that match, show each match as an
221    offset from the start of the file and a length, separated by a comma. In this
222    mode, no context is shown. That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP
223    options are ignored. If there is more than one match in a line, each of them is
224    shown separately. This option is mutually exclusive with \fB--line-offsets\fP
225    and \fB--only-matching\fP.
226  .TP  .TP
227  \fB-H\fP, \fB--with-filename\fP  \fB-H\fP, \fB--with-filename\fP
228  Force the inclusion of the filename at the start of output lines when searching  Force the inclusion of the filename at the start of output lines when searching
229  a single file. By default, the filename is not shown in this case. For matching  a single file. By default, the filename is not shown in this case. For matching
230  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
231  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
232  file name without a space.  name.
233  .TP  .TP
234  \fB-h\fP, \fB--no-filename\fP  \fB-h\fP, \fB--no-filename\fP
235  Suppress the output filenames when searching multiple files. By default,  Suppress the output filenames when searching multiple files. By default,
236  filenames are shown when multiple files are searched. For matching lines, the  filenames are shown when multiple files are searched. For matching lines, the
237  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.
238  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.  
239  .TP  .TP
240  \fB--help\fP  \fB--help\fP
241  Output a brief help message and exit.  Output a help message, giving brief details of the command options and file
242    type support, and then exit.
243  .TP  .TP
244  \fB-i\fP, \fB--ignore-case\fP  \fB-i\fP, \fB--ignore-case\fP
245  Ignore upper/lower case distinctions during comparisons.  Ignore upper/lower case distinctions during comparisons.
246  .TP  .TP
247  \fB--include\fP=\fIpattern\fP  \fB--include\fP=\fIpattern\fP
248  When \fBpcregrep\fP is searching the files in a directory as a consequence of  When \fBpcregrep\fP is searching the files in a directory as a consequence of
249  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
250  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
251  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
252  short form for this option.  options. The pattern is a PCRE regular expression, and is matched against the
253    final component of the file name (not the entire path). If a file name matches
254    both \fB--include\fP and \fB--exclude\fP, it is excluded. There is no short
255    form for this option.
256    .TP
257    \fB--include-dir\fP=\fIpattern\fP
258    When \fBpcregrep\fP is searching the contents of a directory as a consequence
259    of the \fB-r\fP (recursive search) option, only those subdirectories whose
260    names match the pattern are included. (Note that the \fB--include\fP option
261    does not affect subdirectories.) The pattern is a PCRE regular expression, and
262    is matched against the final component of the name (not the entire path). If a
263    subdirectory name matches both \fB--include-dir\fP and \fB--exclude-dir\fP, it
264    is excluded. There is no short form for this option.
265  .TP  .TP
266  \fB-L\fP, \fB--files-without-match\fP  \fB-L\fP, \fB--files-without-match\fP
267  Instead of outputting lines from the files, just output the names of the files  Instead of outputting lines from the files, just output the names of the files
# Line 193  output once, on a separate line. Line 271  output once, on a separate line.
271  \fB-l\fP, \fB--files-with-matches\fP  \fB-l\fP, \fB--files-with-matches\fP
272  Instead of outputting lines from the files, just output the names of the files  Instead of outputting lines from the files, just output the names of the files
273  containing lines that would have been output. Each file name is output  containing lines that would have been output. Each file name is output
274  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
275  in a file.  is found in a file. However, if the \fB-c\fP (count) option is also used,
276    matching continues in order to obtain the correct count, and those files that
277    have at least one match are listed along with their counts. Using this option
278    with \fB-c\fP is a way of suppressing the listing of files with no matches.
279  .TP  .TP
280  \fB--label\fP=\fIname\fP  \fB--label\fP=\fIname\fP
281  This option supplies a name to be used for the standard input when file names  This option supplies a name to be used for the standard input when file names
282  are being output. If not supplied, "(standard input)" is used. There is no  are being output. If not supplied, "(standard input)" is used. There is no
283  short form for this option.  short form for this option.
284  .TP  .TP
285    \fB--line-buffered\fP
286    When this option is given, input is read and processed line by line, and the
287    output is flushed after each write. By default, input is read in large chunks,
288    unless \fBpcregrep\fP can determine that it is reading from a terminal (which
289    is currently possible only in Unix environments). Output to terminal is
290    normally automatically flushed by the operating system. This option can be
291    useful when the input or output is attached to a pipe and you do not want
292    \fBpcregrep\fP to buffer up large amounts of data. However, its use will affect
293    performance, and the \fB-M\fP (multiline) option ceases to work.
294    .TP
295    \fB--line-offsets\fP
296    Instead of showing lines or parts of lines that match, show each match as a
297    line number, the offset from the start of the line, and a length. The line
298    number is terminated by a colon (as usual; see the \fB-n\fP option), and the
299    offset and length are separated by a comma. In this mode, no context is shown.
300    That is, the \fB-A\fP, \fB-B\fP, and \fB-C\fP options are ignored. If there is
301    more than one match in a line, each of them is shown separately. This option is
302    mutually exclusive with \fB--file-offsets\fP and \fB--only-matching\fP.
303    .TP
304  \fB--locale\fP=\fIlocale-name\fP  \fB--locale\fP=\fIlocale-name\fP
305  This option specifies a locale to be used for pattern matching. It overrides  This option specifies a locale to be used for pattern matching. It overrides
306  the value in the \fBLC_ALL\fP or \fBLC_CTYPE\fP environment variables. If no  the value in the \fBLC_ALL\fP or \fBLC_CTYPE\fP environment variables. If no
307  locale is specified, the PCRE library's default (usually the "C" locale) is  locale is specified, the PCRE library's default (usually the "C" locale) is
308  used. There is no short form for this option.  used. There is no short form for this option.
309  .TP  .TP
310    \fB--match-limit\fP=\fInumber\fP
311    Processing some regular expression patterns can require a very large amount of
312    memory, leading in some cases to a program crash if not enough is available.
313    Other patterns may take a very long time to search for all possible matching
314    strings. The \fBpcre_exec()\fP function that is called by \fBpcregrep\fP to do
315    the matching has two parameters that can limit the resources that it uses.
316    .sp
317    The \fB--match-limit\fP option provides a means of limiting resource usage
318    when processing patterns that are not going to match, but which have a very
319    large number of possibilities in their search trees. The classic example is a
320    pattern that uses nested unlimited repeats. Internally, PCRE uses a function
321    called \fBmatch()\fP which it calls repeatedly (sometimes recursively). The
322    limit set by \fb--match-limit\fP is imposed on the number of times this
323    function is called during a match, which has the effect of limiting the amount
324    of backtracking that can take place.
325    .sp
326    The \fB--recursion-limit\fP option is similar to \fB--match-limit\fP, but
327    instead of limiting the total number of times that \fBmatch()\fP is called, it
328    limits the depth of recursive calls, which in turn limits the amount of memory
329    that can be used. The recursion depth is a smaller number than the total number
330    of calls, because not all calls to \fBmatch()\fP are recursive. This limit is
331    of use only if it is set smaller than \fB--match-limit\fP.
332    .sp
333    There are no short forms for these options. The default settings are specified
334    when the PCRE library is compiled, with the default default being 10 million.
335    .TP
336  \fB-M\fP, \fB--multiline\fP  \fB-M\fP, \fB--multiline\fP
337  Allow patterns to match more than one line. When this option is given, patterns  Allow patterns to match more than one line. When this option is given, patterns
338  may usefully contain literal newline characters and internal occurrences of ^  may usefully contain literal newline characters and internal occurrences of ^
# Line 217  that \fBpcregrep\fP buffers the input fi Line 343  that \fBpcregrep\fP buffers the input fi
343  \fBpcregrep\fP ensures that at least 8K characters or the rest of the document  \fBpcregrep\fP ensures that at least 8K characters or the rest of the document
344  (whichever is the shorter) are available for forward matching, and similarly  (whichever is the shorter) are available for forward matching, and similarly
345  the previous 8K characters (or all the previous characters, if fewer than 8K)  the previous 8K characters (or all the previous characters, if fewer than 8K)
346  are guaranteed to be available for lookbehind assertions.  are guaranteed to be available for lookbehind assertions. This option does not
347    work when input is read line by line (see \fP--line-buffered\fP.)
348  .TP  .TP
349  \fB-N\fP \fInewline-type\fP, \fB--newline=\fP\fInewline-type\fP  \fB-N\fP \fInewline-type\fP, \fB--newline\fP=\fInewline-type\fP
350  The PCRE library supports three different character sequences for indicating  The PCRE library supports five different conventions for indicating
351  the ends of lines. They are the single-character sequences CR (carriage return)  the ends of lines. They are the single-character sequences CR (carriage return)
352  and LF (linefeed), and the two-character sequence CR, LF. When the library is  and LF (linefeed), the two-character sequence CRLF, an "anycrlf" convention,
353  built, a default line-ending sequence is specified. This is normally the  which recognizes any of the preceding three types, and an "any" convention, in
354  standard sequence for the operating system. Unless otherwise specified by this  which any Unicode line ending sequence is assumed to end a line. The Unicode
355  option, \fBpcregrep\fP uses the default. The possible values for this option  sequences are the three just mentioned, plus VT (vertical tab, U+000B), FF
356  are CR, LF, or CRLF. This makes it possible to use \fBpcregrep\fP on files that  (formfeed, U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and
357  have come from other environments without having to modify their line endings.  PS (paragraph separator, U+2029).
358  If the data that is being scanned does not agree with the convention set by  .sp
359  this option, \fBpcregrep\fP may behave in strange ways.  When the PCRE library is built, a default line-ending sequence is specified.
360    This is normally the standard sequence for the operating system. Unless
361    otherwise specified by this option, \fBpcregrep\fP uses the library's default.
362    The possible values for this option are CR, LF, CRLF, ANYCRLF, or ANY. This
363    makes it possible to use \fBpcregrep\fP on files that have come from other
364    environments without having to modify their line endings. If the data that is
365    being scanned does not agree with the convention set by this option,
366    \fBpcregrep\fP may behave in strange ways.
367  .TP  .TP
368  \fB-n\fP, \fB--line-number\fP  \fB-n\fP, \fB--line-number\fP
369  Precede each output line by its line number in the file, followed by a colon  Precede each output line by its line number in the file, followed by a colon
370  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
371  the filename is also being output, it precedes the line number.  output, it precedes the line number. This option is forced if
372    \fB--line-offsets\fP is used.
373  .TP  .TP
374  \fB-o\fP, \fB--only-matching\fP  \fB-o\fP, \fB--only-matching\fP
375  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
376  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
377  ignored.  \fB-C\fP options are ignored. If there is more than one match in a line, each
378    of them is shown separately. If \fB-o\fP is combined with \fB-v\fP (invert the
379    sense of the match to find non-matching lines), no output is generated, but the
380    return code is set appropriately. If the matched portion of the line is empty,
381    nothing is output unless the file name or line number are being printed, in
382    which case they are shown on an otherwise empty line. This option is mutually
383    exclusive with \fB--file-offsets\fP and \fB--line-offsets\fP.
384    .TP
385    \fB-o\fP\fInumber\fP, \fB--only-matching\fP=\fInumber\fP
386    Show only the part of the line that matched the capturing parentheses of the
387    given number. Up to 32 capturing parentheses are supported. Because these
388    options can be given without an argument (see above), if an argument is
389    present, it must be given in the same shell item, for example, -o3 or
390    --only-matching=2. The comments given for the non-argument case above also
391    apply to this case. If the specified capturing parentheses do not exist in the
392    pattern, or were not set in the match, nothing is output unless the file name
393    or line number are being printed.
394  .TP  .TP
395  \fB-q\fP, \fB--quiet\fP  \fB-q\fP, \fB--quiet\fP
396  Work quietly, that is, display nothing except error messages. The exit  Work quietly, that is, display nothing except error messages. The exit
# Line 252  directory is read as a normal file; in s Line 403  directory is read as a normal file; in s
403  immediate end-of-file. This option is a shorthand for setting the \fB-d\fP  immediate end-of-file. This option is a shorthand for setting the \fB-d\fP
404  option to "recurse".  option to "recurse".
405  .TP  .TP
406    \fB--recursion-limit\fP=\fInumber\fP
407    See \fB--match-limit\fP above.
408    .TP
409  \fB-s\fP, \fB--no-messages\fP  \fB-s\fP, \fB--no-messages\fP
410  Suppress error messages about non-existent or unreadable files. Such files are  Suppress error messages about non-existent or unreadable files. Such files are
411  quietly skipped. However, the return code is still 2, even if matches were  quietly skipped. However, the return code is still 2, even if matches were
# Line 274  the patterns are the ones that are found Line 428  the patterns are the ones that are found
428  Force the patterns to match only whole words. This is equivalent to having \eb  Force the patterns to match only whole words. This is equivalent to having \eb
429  at the start and end of the pattern.  at the start and end of the pattern.
430  .TP  .TP
431  \fB-x\fP, \fB--line-regex\fP, \fP--line-regexp\fP  \fB-x\fP, \fB--line-regex\fP, \fB--line-regexp\fP
432  Force the patterns to be anchored (each must start matching at the beginning of  Force the patterns to be anchored (each must start matching at the beginning of
433  a line) and in addition, require them to match entire lines. This is  a line) and in addition, require them to match entire lines. This is
434  equivalent to having ^ and $ characters at the start and end of each  equivalent to having ^ and $ characters at the start and end of each
# Line 304  convert this to an appropriate sequence Line 458  convert this to an appropriate sequence
458  .SH "OPTIONS COMPATIBILITY"  .SH "OPTIONS COMPATIBILITY"
459  .rs  .rs
460  .sp  .sp
461  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
462  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
463  \fB--xxx-regexp\fP (GNU terminology) is also available as \fB--xxx-regex\fP  \fB--xxx-regexp\fP (GNU terminology) is also available as \fB--xxx-regex\fP
464  (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,
465  \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,
466    \fB--multiline\fP, \fB-N\fP, \fB--newline\fP, \fB--recursion-limit\fP,
467    \fB-u\fP, and \fB--utf-8\fP options are specific to \fBpcregrep\fP, as is the
468    use of the \fB--only-matching\fP option with a capturing parentheses number.
469    .P
470    Although most of the common options work the same way, a few are different in
471    \fBpcregrep\fP. For example, the \fB--include\fP option's argument is a glob
472    for GNU \fBgrep\fP, but a regular expression for \fBpcregrep\fP. If both the
473    \fB-c\fP and \fB-l\fP options are given, GNU grep lists only file names,
474    without counts, but \fBpcregrep\fP gives the counts.
475  .  .
476  .  .
477  .SH "OPTIONS WITH DATA"  .SH "OPTIONS WITH DATA"
478  .rs  .rs
479  .sp  .sp
480  There are four different ways in which an option with data can be specified.  There are four different ways in which an option with data can be specified.
481  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
482  command line item. For example:  exception) in the next command line item. For example:
483  .sp  .sp
484    -f/some/file    -f/some/file
485    -f /some/file    -f /some/file
486  .sp  .sp
487    The exception is the \fB-o\fP option, which may appear with or without data.
488    Because of this, if data is present, it must follow immediately in the same
489    item, for example -o3.
490    .P
491  If a long form option is used, the data may appear in the same command line  If a long form option is used, the data may appear in the same command line
492  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
493  in the next command line item. For example:  in the next command line item. For example:
494  .sp  .sp
495    --file=/some/file    --file=/some/file
# Line 333  in a shell command, and have the shell e Line 500  in a shell command, and have the shell e
500  separate the file name from the option, because the shell does not treat ~  separate the file name from the option, because the shell does not treat ~
501  specially unless it is at the start of an item.  specially unless it is at the start of an item.
502  .P  .P
503  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
504  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
505  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
506  it has no data.  character. Otherwise \fBpcregrep\fP will assume that it has no data.
507  .  .
508  .  .
509  .SH MATCHING ERRORS  .SH "MATCHING ERRORS"
510  .rs  .rs
511  .sp  .sp
512  It is possible to supply a regular expression that takes a very long time to  It is possible to supply a regular expression that takes a very long time to
# Line 349  digit. The PCRE matching function has a Line 516  digit. The PCRE matching function has a
516  in these circumstances. If this happens, \fBpcregrep\fP outputs an error  in these circumstances. If this happens, \fBpcregrep\fP outputs an error
517  message and the line that caused the problem to the standard error stream. If  message and the line that caused the problem to the standard error stream. If
518  there are more than 20 such errors, \fBpcregrep\fP gives up.  there are more than 20 such errors, \fBpcregrep\fP gives up.
519    .P
520    The \fB--match-limit\fP option of \fBpcregrep\fP can be used to set the overall
521    resource limit; there is a second option called \fB--recursion-limit\fP that
522    sets a limit on the amount of memory (usually stack) that is used (see the
523    discussion of these options above).
524  .  .
525  .  .
526  .SH DIAGNOSTICS  .SH DIAGNOSTICS
# Line 361  suppress error messages about inaccessbl Line 533  suppress error messages about inaccessbl
533  code.  code.
534  .  .
535  .  .
536    .SH "SEE ALSO"
537    .rs
538    .sp
539    \fBpcrepattern\fP(3), \fBpcretest\fP(1).
540    .
541    .
542  .SH AUTHOR  .SH AUTHOR
543  .rs  .rs
544  .sp  .sp
545    .nf
546  Philip Hazel  Philip Hazel
 .br  
547  University Computing Service  University Computing Service
548  .br  Cambridge CB2 3QH, England.
549  Cambridge CB2 3QG, England.  .fi
550  .P  .
551  .in 0  .
552  Last updated: 06 June 2006  .SH REVISION
553  .br  .rs
554  Copyright (c) 1997-2006 University of Cambridge.  .sp
555    .nf
556    Last updated: 16 November 2010
557    Copyright (c) 1997-2010 University of Cambridge.
558    .fi

Legend:
Removed from v.91  
changed lines
  Added in v.579

  ViewVC Help
Powered by ViewVC 1.1.5