| <html> |
| <head> |
| <title>pcre2grep specification</title> |
| </head> |
| <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> |
| <h1>pcre2grep man page</h1> |
| <p> |
| Return to the <a href="index.html">PCRE2 index page</a>. |
| </p> |
| <p> |
| This page is part of the PCRE2 HTML documentation. It was generated |
| automatically from the original man page. If there is any nonsense in it, |
| please consult the man page, in case the conversion went wrong. |
| <br> |
| <ul> |
| <li><a name="TOC1" href="#SEC1">SYNOPSIS</a> |
| <li><a name="TOC2" href="#SEC2">DESCRIPTION</a> |
| <li><a name="TOC3" href="#SEC3">SUPPORT FOR COMPRESSED FILES</a> |
| <li><a name="TOC4" href="#SEC4">BINARY FILES</a> |
| <li><a name="TOC5" href="#SEC5">BINARY ZEROS IN PATTERNS</a> |
| <li><a name="TOC6" href="#SEC6">OPTIONS</a> |
| <li><a name="TOC7" href="#SEC7">ENVIRONMENT VARIABLES</a> |
| <li><a name="TOC8" href="#SEC8">NEWLINES</a> |
| <li><a name="TOC9" href="#SEC9">OPTIONS COMPATIBILITY</a> |
| <li><a name="TOC10" href="#SEC10">OPTIONS WITH DATA</a> |
| <li><a name="TOC11" href="#SEC11">USING PCRE2'S CALLOUT FACILITY</a> |
| <li><a name="TOC12" href="#SEC12">MATCHING ERRORS</a> |
| <li><a name="TOC13" href="#SEC13">DIAGNOSTICS</a> |
| <li><a name="TOC14" href="#SEC14">SEE ALSO</a> |
| <li><a name="TOC15" href="#SEC15">AUTHOR</a> |
| <li><a name="TOC16" href="#SEC16">REVISION</a> |
| </ul> |
| <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> |
| <P> |
| <b>pcre2grep [options] [long options] [pattern] [path1 path2 ...]</b> |
| </P> |
| <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> |
| <P> |
| <b>pcre2grep</b> searches files for character patterns, in the same way as other |
| grep commands do, but it uses the PCRE2 regular expression library to support |
| patterns that are compatible with the regular expressions of Perl 5. See |
| <a href="pcre2syntax.html"><b>pcre2syntax</b>(3)</a> |
| for a quick-reference summary of pattern syntax, or |
| <a href="pcre2pattern.html"><b>pcre2pattern</b>(3)</a> |
| for a full description of the syntax and semantics of the regular expressions |
| that PCRE2 supports. |
| </P> |
| <P> |
| Patterns, whether supplied on the command line or in a separate file, are given |
| without delimiters. For example: |
| <pre> |
| pcre2grep Thursday /etc/motd |
| </pre> |
| If you attempt to use delimiters (for example, by surrounding a pattern 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 on the command line |
| because they are interpreted by the shell, and indeed quotes are required if a |
| pattern contains white space or shell metacharacters. |
| </P> |
| <P> |
| The first argument that follows any option settings is treated as the single |
| pattern to be matched when neither <b>-e</b> nor <b>-f</b> is present. |
| Conversely, when one or both of these options are used to specify patterns, all |
| arguments are treated as path names. At least one of <b>-e</b>, <b>-f</b>, or an |
| argument pattern must be provided. |
| </P> |
| <P> |
| If no files are specified, <b>pcre2grep</b> reads the standard input. The |
| standard input can also be referenced by a name consisting of a single hyphen. |
| For example: |
| <pre> |
| pcre2grep some-pattern file1 - file3 |
| </pre> |
| Input files are searched line by line. 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 the start of each line, followed by a colon. |
| However, there are options that can change how <b>pcre2grep</b> behaves. In |
| particular, the <b>-M</b> option makes it possible to search for strings that |
| span line boundaries. What defines a line boundary is controlled by the |
| <b>-N</b> (<b>--newline</b>) option. |
| </P> |
| <P> |
| The amount of memory used for buffering files that are being scanned is |
| controlled by parameters that can be set by the <b>--buffer-size</b> and |
| <b>--max-buffer-size</b> options. The first of these sets the size of buffer |
| that is obtained at the start of processing. If an input file contains very |
| long lines, a larger buffer may be needed; this is handled by automatically |
| extending the buffer, up to the limit specified by <b>--max-buffer-size</b>. The |
| default values for these parameters can be set when <b>pcre2grep</b> is |
| built; if nothing is specified, the defaults are set to 20KiB and 1MiB |
| respectively. An error occurs if a line is too long and the buffer can no |
| longer be expanded. |
| </P> |
| <P> |
| The block of memory that is actually used is three times the "buffer size", to |
| allow for buffering "before" and "after" lines. If the buffer size is too |
| small, fewer than requested "before" and "after" lines may be output. |
| </P> |
| <P> |
| Patterns can be no longer than 8KiB or BUFSIZ bytes, whichever is the greater. |
| BUFSIZ is defined in <b><stdio.h></b>. When there is more than one pattern |
| (specified by the use of <b>-e</b> and/or <b>-f</b>), each pattern is applied to |
| each line in the order in which they are defined, except that all the <b>-e</b> |
| patterns are tried before the <b>-f</b> patterns. |
| </P> |
| <P> |
| By default, as soon as one pattern matches a line, no further patterns are |
| considered. However, if <b>--colour</b> (or <b>--color</b>) is used to colour the |
| matching substrings, or if <b>--only-matching</b>, <b>--file-offsets</b>, or |
| <b>--line-offsets</b> is used to output only the part of the line that matched |
| (either shown literally, or as an offset), scanning resumes immediately |
| 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 remainder of the line, |
| but patterns that follow the one that matched are not tried on the earlier |
| matched part of the line. |
| </P> |
| <P> |
| This behaviour means that the order in which multiple patterns are 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 display earlier matches |
| for later patterns (as long as there is no overlap). |
| </P> |
| <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> |
| <P> |
| If the <b>LC_ALL</b> or <b>LC_CTYPE</b> environment variable is set, |
| <b>pcre2grep</b> uses the value to set a locale when calling the PCRE2 library. |
| The <b>--locale</b> option can be used to override this. |
| </P> |
| <br><a name="SEC3" href="#TOC1">SUPPORT FOR COMPRESSED FILES</a><br> |
| <P> |
| It is possible to compile <b>pcre2grep</b> so that it uses <b>libz</b> or |
| <b>libbz2</b> to read compressed files whose names end in <b>.gz</b> or |
| <b>.bz2</b>, respectively. You can find out whether your <b>pcre2grep</b> binary |
| has support for one or both of these file types by running it with the |
| <b>--help</b> option. If the appropriate support is not present, all files are |
| treated as plain text. The standard input is always so treated. When input is |
| from a compressed .gz or .bz2 file, the <b>--line-buffered</b> option is |
| ignored. |
| </P> |
| <br><a name="SEC4" href="#TOC1">BINARY FILES</a><br> |
| <P> |
| 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. However, if the |
| newline type is specified as NUL, that is, the line terminator is a binary |
| zero, the test for a binary file is not applied. See the <b>--binary-files</b> |
| option for a means of changing the way binary files are handled. |
| </P> |
| <br><a name="SEC5" href="#TOC1">BINARY ZEROS IN PATTERNS</a><br> |
| <P> |
| Patterns passed from the command line are strings that are terminated by a |
| binary zero, so cannot contain internal zeros. However, patterns that are read |
| from a file via the <b>-f</b> option may contain binary zeros. |
| </P> |
| <br><a name="SEC6" href="#TOC1">OPTIONS</a><br> |
| <P> |
| The order in which some of the options appear can affect the output. For |
| example, both the <b>-H</b> and <b>-l</b> options affect the printing of file |
| names. Whichever comes later in the command line will be the one that takes |
| effect. Similarly, except where noted below, if an option is given twice, the |
| later setting is used. Numerical values for options may be followed by K or M, |
| to signify multiplication by 1024 or 1024*1024 respectively. |
| </P> |
| <P> |
| <b>--</b> |
| This terminates the list of options. It is useful if the next item on the |
| command line starts with a hyphen but is not an option. This allows for the |
| processing of patterns and file names that start with hyphens. |
| </P> |
| <P> |
| <b>-A</b> <i>number</i>, <b>--after-context=</b><i>number</i> |
| Output up to <i>number</i> lines of context after each matching line. Fewer |
| lines are output if the next match or the end of the file is reached, or if the |
| processing buffer size has been set too small. If file names and/or line |
| numbers are being output, a hyphen separator is used instead of a colon for the |
| context lines. A line containing "--" is output between each group of lines, |
| unless they are in fact contiguous in the input file. The value of <i>number</i> |
| is expected to be relatively small. When <b>-c</b> is used, <b>-A</b> is ignored. |
| </P> |
| <P> |
| <b>-a</b>, <b>--text</b> |
| Treat binary files as text. This is equivalent to |
| <b>--binary-files</b>=<i>text</i>. |
| </P> |
| <P> |
| <b>--allow-lookaround-bsk</b> |
| PCRE2 now forbids the use of \K in lookarounds by default, in line with Perl. |
| This option causes <b>pcre2grep</b> to set the PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK |
| option, which enables this somewhat dangerous usage. |
| </P> |
| <P> |
| <b>-B</b> <i>number</i>, <b>--before-context=</b><i>number</i> |
| Output up to <i>number</i> lines of context before each matching line. Fewer |
| lines are output if the previous match or the start of the file is within |
| <i>number</i> lines, or if the processing buffer size has been set too small. If |
| file names and/or line numbers are being output, a hyphen separator is used |
| instead of a colon for the context lines. A line containing "--" is output |
| between each group of lines, unless they are in fact contiguous in the input |
| file. The value of <i>number</i> is expected to be relatively small. When |
| <b>-c</b> is used, <b>-B</b> is ignored. |
| </P> |
| <P> |
| <b>--binary-files=</b><i>word</i> |
| Specify how binary files are to be processed. If the word is "binary" (the |
| default), pattern matching is performed on binary files, but the only output is |
| "Binary file <name> matches" when a match succeeds. If the word is "text", |
| which is equivalent to the <b>-a</b> or <b>--text</b> option, binary files are |
| processed in the same way as any other file. In this case, when a match |
| succeeds, the output may be binary garbage, which can have nasty effects if |
| sent to a terminal. If the word is "without-match", which is equivalent to the |
| <b>-I</b> option, binary files are not processed at all; they are assumed not to |
| be of interest and are skipped without causing any output or affecting the |
| return code. |
| </P> |
| <P> |
| <b>--buffer-size=</b><i>number</i> |
| Set the parameter that controls how much memory is obtained at the start of |
| processing for buffering files that are being scanned. See also |
| <b>--max-buffer-size</b> below. |
| </P> |
| <P> |
| <b>-C</b> <i>number</i>, <b>--context=</b><i>number</i> |
| Output <i>number</i> lines of context both before and after each matching line. |
| This is equivalent to setting both <b>-A</b> and <b>-B</b> to the same value. |
| </P> |
| <P> |
| <b>-c</b>, <b>--count</b> |
| Do not output lines from the files that are being scanned; instead output the |
| number of lines that would have been shown, either because they matched, or, if |
| <b>-v</b> is set, because they failed to match. By default, this count is |
| exactly the same as the number of lines that would have been output, but if the |
| <b>-M</b> (multiline) option is used (without <b>-v</b>), there may be more |
| suppressed lines than the count (that is, the number of matches). |
| <br> |
| <br> |
| If no lines are selected, the number zero is output. If several files are are |
| being scanned, a count is output for each of them and the <b>-t</b> option can |
| be used to cause a total to be output at the end. However, if the |
| <b>--files-with-matches</b> option is also used, only those files whose counts |
| are greater than zero are listed. When <b>-c</b> is used, the <b>-A</b>, |
| <b>-B</b>, and <b>-C</b> options are ignored. |
| </P> |
| <P> |
| <b>--colour</b>, <b>--color</b> |
| If this option is given without any data, it is equivalent to "--colour=auto". |
| If data is required, it must be given in the same shell item, separated by an |
| equals sign. |
| </P> |
| <P> |
| <b>--colour=</b><i>value</i>, <b>--color=</b><i>value</i> |
| This option specifies under what circumstances the parts of a line that matched |
| a pattern should be coloured in the output. By default, the output is not |
| coloured. The value (which is optional, see above) may be "never", "always", or |
| "auto". In the latter case, colouring happens only if the standard output is |
| connected to a terminal. More resources are used when colouring is enabled, |
| because <b>pcre2grep</b> has to search for all possible matches in a line, not |
| just one, in order to colour them all. |
| <br> |
| <br> |
| The colour that is used can be specified by setting one of the environment |
| variables PCRE2GREP_COLOUR, PCRE2GREP_COLOR, PCREGREP_COLOUR, or |
| PCREGREP_COLOR, which are checked in that order. If none of these are set, |
| <b>pcre2grep</b> looks for GREP_COLORS or GREP_COLOR (in that order). The value |
| of the variable should be a string of two numbers, separated by a semicolon, |
| except in the case of GREP_COLORS, which must start with "ms=" or "mt=" |
| followed by two semicolon-separated colours, terminated by the end of the |
| string or by a colon. If GREP_COLORS does not start with "ms=" or "mt=" it is |
| ignored, and GREP_COLOR is checked. |
| <br> |
| <br> |
| If the string obtained from one of the above variables contains any characters |
| other than semicolon or digits, the setting is ignored and the default colour |
| is used. The string is copied directly into the control string for setting |
| colour on a terminal, so it is your responsibility to ensure that the values |
| make sense. If no relevant environment variable is set, the default is "1;31", |
| which gives red. |
| </P> |
| <P> |
| <b>-D</b> <i>action</i>, <b>--devices=</b><i>action</i> |
| If an input path is not a regular file or a directory, "action" specifies how |
| it is to be processed. Valid values are "read" (the default) or "skip" |
| (silently skip the path). |
| </P> |
| <P> |
| <b>-d</b> <i>action</i>, <b>--directories=</b><i>action</i> |
| If an input path is a directory, "action" specifies how it is to be processed. |
| Valid values are "read" (the default in non-Windows environments, for |
| compatibility with GNU grep), "recurse" (equivalent to the <b>-r</b> option), or |
| "skip" (silently skip the path, the default in Windows environments). In the |
| "read" case, directories 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; in others it may provoke an error. |
| </P> |
| <P> |
| <b>--depth-limit</b>=<i>number</i> |
| See <b>--match-limit</b> below. |
| </P> |
| <P> |
| <b>-e</b> <i>pattern</i>, <b>--regex=</b><i>pattern</i>, <b>--regexp=</b><i>pattern</i> |
| 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 <b>-e</b> is used, no argument |
| pattern is taken from the command line; all arguments are treated as file |
| names. There is no limit to the number of patterns. They are applied to each |
| line in the order in which they are defined until one matches. |
| <br> |
| <br> |
| If <b>-f</b> is used with <b>-e</b>, the command line patterns are matched first, |
| followed by the patterns from the file(s), independent of the order in which |
| these options are specified. Note that multiple use of <b>-e</b> is not the same |
| as a single pattern with alternatives. For example, X|Y finds the first |
| character in a line that is X or Y, whereas if the two patterns are given |
| separately, with X first, <b>pcre2grep</b> finds X if it is present, 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 <b>-o</b> or <b>--colo(u)r</b> to show the part(s) |
| of the line that matched. |
| </P> |
| <P> |
| <b>--exclude</b>=<i>pattern</i> |
| Files (but not directories) whose names match the pattern are skipped without |
| being processed. This applies to all files, whether listed on the command line, |
| obtained from <b>--file-list</b>, or by scanning a directory. The pattern is a |
| PCRE2 regular expression, and is matched against the final component of the |
| file name, not the entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do |
| not apply to this pattern. The option may be given any number of times in order |
| to specify multiple patterns. If a file name matches both an <b>--include</b> |
| and an <b>--exclude</b> pattern, it is excluded. There is no short form for this |
| option. |
| </P> |
| <P> |
| <b>--exclude-from=</b><i>filename</i> |
| Treat each non-empty line of the file as the data for an <b>--exclude</b> |
| option. What constitutes a newline when reading the file is the operating |
| system's default. The <b>--newline</b> option has no effect on this option. This |
| option may be given more than once in order to specify a number of files to |
| read. |
| </P> |
| <P> |
| <b>--exclude-dir</b>=<i>pattern</i> |
| Directories whose names match the pattern are skipped without being processed, |
| whatever the setting of the <b>--recursive</b> option. This applies to all |
| directories, whether listed on the command line, obtained from |
| <b>--file-list</b>, or by scanning a parent directory. The pattern is a PCRE2 |
| regular expression, and is matched against the final component of the directory |
| name, not the entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do not |
| apply to this pattern. The option may be given any number of times in order to |
| specify more than one pattern. If a directory matches both <b>--include-dir</b> |
| and <b>--exclude-dir</b>, it is excluded. There is no short form for this |
| option. |
| </P> |
| <P> |
| <b>-F</b>, <b>--fixed-strings</b> |
| Interpret each data-matching pattern as a list of fixed strings, separated by |
| newlines, instead of as a regular expression. What constitutes a newline for |
| this purpose is controlled by the <b>--newline</b> option. The <b>-w</b> (match |
| as a word) and <b>-x</b> (match whole line) options can be used with <b>-F</b>. |
| They apply to each of the fixed strings. A line is selected if any of the fixed |
| strings are found in it (subject to <b>-w</b> or <b>-x</b>, if present). This |
| option applies only to the patterns that are matched against the contents of |
| files; it does not apply to patterns specified by any of the <b>--include</b> or |
| <b>--exclude</b> options. |
| </P> |
| <P> |
| <b>-f</b> <i>filename</i>, <b>--file=</b><i>filename</i> |
| Read patterns from the file, one per line, and match them against each line of |
| input. As is the case with patterns on the command line, no delimiters should |
| be used. What constitutes a newline when reading the file is the operating |
| system's default interpretation of \n. The <b>--newline</b> option has no |
| effect on this option. Trailing white space is removed from each line, and |
| blank lines are ignored. An empty file contains no patterns and therefore |
| matches nothing. Patterns read from a file in this way may contain binary |
| zeros, which are treated as ordinary data characters. See also the comments |
| about multiple patterns versus a single pattern with alternatives in the |
| description of <b>-e</b> above. |
| <br> |
| <br> |
| If this option is given more than once, all the specified files are read. A |
| data line is output if any of the patterns match it. A file name can be given |
| as "-" to refer to the standard input. When <b>-f</b> is used, patterns |
| specified on the command line using <b>-e</b> may also be present; they are |
| tested before the file's patterns. However, no other pattern is taken from the |
| command line; all arguments are treated as the names of paths to be searched. |
| </P> |
| <P> |
| <b>--file-list</b>=<i>filename</i> |
| Read a list of files and/or directories that are to be scanned from the given |
| file, one per line. What constitutes a newline when reading the file is the |
| operating system's default. Trailing white space is removed from each line, and |
| blank lines are ignored. These paths are processed before any that are listed |
| on the command line. The file name can be given as "-" to refer to the standard |
| input. If <b>--file</b> and <b>--file-list</b> are both specified as "-", |
| patterns are read first. This is useful only when the standard input is a |
| terminal, from which further lines (the list of files) can be read after an |
| end-of-file indication. If this option is given more than once, all the |
| specified files are read. |
| </P> |
| <P> |
| <b>--file-offsets</b> |
| Instead of showing lines or parts of lines that match, show each match as an |
| offset from the start of the file and a length, separated by a comma. In this |
| mode, no context is shown. That is, the <b>-A</b>, <b>-B</b>, and <b>-C</b> |
| options are ignored. If there is more than one match in a line, each of them is |
| shown separately. This option is mutually exclusive with <b>--output</b>, |
| <b>--line-offsets</b>, and <b>--only-matching</b>. |
| </P> |
| <P> |
| <b>-H</b>, <b>--with-filename</b> |
| Force the inclusion of the file name at the start of output lines when |
| searching a single file. By default, the file name is not shown in this case. |
| For matching lines, the file name is followed by a colon; for context lines, a |
| hyphen separator is used. If a line number is also being output, it follows the |
| file name. When the <b>-M</b> option causes a pattern to match more than one |
| line, only the first is preceded by the file name. This option overrides any |
| previous <b>-h</b>, <b>-l</b>, or <b>-L</b> options. |
| </P> |
| <P> |
| <b>-h</b>, <b>--no-filename</b> |
| Suppress the output file names when searching multiple files. By default, |
| file names are shown when multiple files are searched. For matching lines, the |
| file name is followed by a colon; for context lines, a hyphen separator is used. |
| If a line number is also being output, it follows the file name. This option |
| overrides any previous <b>-H</b>, <b>-L</b>, or <b>-l</b> options. |
| </P> |
| <P> |
| <b>--heap-limit</b>=<i>number</i> |
| See <b>--match-limit</b> below. |
| </P> |
| <P> |
| <b>--help</b> |
| Output a help message, giving brief details of the command options and file |
| type support, and then exit. Anything else on the command line is |
| ignored. |
| </P> |
| <P> |
| <b>-I</b> |
| Ignore binary files. This is equivalent to |
| <b>--binary-files</b>=<i>without-match</i>. |
| </P> |
| <P> |
| <b>-i</b>, <b>--ignore-case</b> |
| Ignore upper/lower case distinctions during comparisons. |
| </P> |
| <P> |
| <b>--include</b>=<i>pattern</i> |
| If any <b>--include</b> patterns are specified, the only files that are |
| processed are those whose names match one of the patterns and do not match an |
| <b>--exclude</b> pattern. This option does not affect directories, but it |
| applies to all files, whether listed on the command line, obtained from |
| <b>--file-list</b>, or by scanning a directory. The pattern is a PCRE2 regular |
| expression, and is matched against the final component of the file name, not |
| the entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do not apply to |
| this pattern. The option may be given any number of times. If a file name |
| matches both an <b>--include</b> and an <b>--exclude</b> pattern, it is excluded. |
| There is no short form for this option. |
| </P> |
| <P> |
| <b>--include-from=</b><i>filename</i> |
| Treat each non-empty line of the file as the data for an <b>--include</b> |
| option. What constitutes a newline for this purpose is the operating system's |
| default. The <b>--newline</b> option has no effect on this option. This option |
| may be given any number of times; all the files are read. |
| </P> |
| <P> |
| <b>--include-dir</b>=<i>pattern</i> |
| If any <b>--include-dir</b> patterns are specified, the only directories that |
| are processed are those whose names match one of the patterns and do not match |
| an <b>--exclude-dir</b> pattern. This applies to all directories, whether listed |
| on the command line, obtained from <b>--file-list</b>, or by scanning a parent |
| directory. The pattern is a PCRE2 regular expression, and is matched against |
| the final component of the directory name, not the entire path. The <b>-F</b>, |
| <b>-w</b>, and <b>-x</b> options do not apply to this pattern. The option may be |
| given any number of times. If a directory matches both <b>--include-dir</b> and |
| <b>--exclude-dir</b>, it is excluded. There is no short form for this option. |
| </P> |
| <P> |
| <b>-L</b>, <b>--files-without-match</b> |
| Instead of outputting lines from the files, just output the names of the files |
| that do not contain any lines that would have been output. Each file name is |
| output once, on a separate line. This option overrides any previous <b>-H</b>, |
| <b>-h</b>, or <b>-l</b> options. |
| </P> |
| <P> |
| <b>-l</b>, <b>--files-with-matches</b> |
| 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 normally stops as soon as a matching line is found |
| in a file. However, if the <b>-c</b> (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 |
| <b>-c</b> is a way of suppressing the listing of files with no matches that |
| occurs with <b>-c</b> on its own. This option overrides any previous <b>-H</b>, |
| <b>-h</b>, or <b>-L</b> options. |
| </P> |
| <P> |
| <b>--label</b>=<i>name</i> |
| 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. |
| </P> |
| <P> |
| <b>--line-buffered</b> |
| When this option is given, non-compressed 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 <b>pcre2grep</b> can determine that it is reading from a |
| terminal, which is currently possible only in Unix-like environments or |
| Windows. 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 <b>pcre2grep</b> to buffer up large amounts of data. |
| However, its use will affect performance, and the <b>-M</b> (multiline) option |
| ceases to work. When input is from a compressed .gz or .bz2 file, |
| <b>--line-buffered</b> is ignored. |
| </P> |
| <P> |
| <b>--line-offsets</b> |
| 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 <b>-n</b> option), and the |
| offset and length are separated by a comma. In this mode, no context is shown. |
| That is, the <b>-A</b>, <b>-B</b>, and <b>-C</b> options are ignored. If there is |
| more than one match in a line, each of them is shown separately. This option is |
| mutually exclusive with <b>--output</b>, <b>--file-offsets</b>, and |
| <b>--only-matching</b>. |
| </P> |
| <P> |
| <b>--locale</b>=<i>locale-name</i> |
| This option specifies a locale to be used for pattern matching. It overrides |
| the value in the <b>LC_ALL</b> or <b>LC_CTYPE</b> environment variables. If no |
| locale is specified, the PCRE2 library's default (usually the "C" locale) is |
| used. There is no short form for this option. |
| </P> |
| <P> |
| <b>-M</b>, <b>--multiline</b> |
| Allow patterns to match more than one line. When this option is set, the PCRE2 |
| library is called in "multiline" mode. This allows a matched string to extend |
| past the end of a line and continue on one or more subsequent lines. Patterns |
| used with <b>-M</b> may usefully contain literal newline characters and internal |
| occurrences of ^ and $ characters. The output for a successful match may |
| consist of more than one line. The first line is the line in which the match |
| started, and the last line is the line in which the match ended. If the matched |
| string ends with a newline sequence, the output ends at the end of that line. |
| If <b>-v</b> is set, none of the lines in a multi-line match are output. Once a |
| match has been handled, scanning restarts at the beginning of the line after |
| the one in which the match ended. |
| <br> |
| <br> |
| The newline sequence that separates multiple lines must be matched as part of |
| the pattern. For example, to find the phrase "regular expression" in a file |
| where "regular" might be at the end of a line and "expression" at the start of |
| the next line, you could use this command: |
| <pre> |
| pcre2grep -M 'regular\s+expression' <file> |
| </pre> |
| The \s escape sequence matches any white space character, including newlines, |
| and is followed by + so as to match trailing white space on the first line as |
| well as possibly handling a two-character newline sequence. |
| <br> |
| <br> |
| There is a limit to the number of lines that can be matched, imposed by the way |
| that <b>pcre2grep</b> buffers the input file as it scans it. With a sufficiently |
| large processing buffer, this should not be a problem, but the <b>-M</b> option |
| does not work when input is read line by line (see <b>--line-buffered</b>.) |
| </P> |
| <P> |
| <b>-m</b> <i>number</i>, <b>--max-count</b>=<i>number</i> |
| Stop processing after finding <i>number</i> matching lines, or non-matching |
| lines if <b>-v</b> is also set. Any trailing context lines are output after the |
| final match. In multiline mode, each multiline match counts as just one line |
| for this purpose. If this limit is reached when reading the standard input from |
| a regular file, the file is left positioned just after the last matching line. |
| If <b>-c</b> is also set, the count that is output is never greater than |
| <i>number</i>. This option has no effect if used with <b>-L</b>, <b>-l</b>, or |
| <b>-q</b>, or when just checking for a match in a binary file. |
| </P> |
| <P> |
| <b>--match-limit</b>=<i>number</i> |
| Processing some regular expression patterns may take a very long time to search |
| for all possible matching strings. Others may require a very large amount of |
| memory. There are three options that set resource limits for matching. |
| <br> |
| <br> |
| The <b>--match-limit</b> option provides a means of limiting computing 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, PCRE2 has a |
| counter that is incremented each time around its main processing loop. If the |
| value set by <b>--match-limit</b> is reached, an error occurs. |
| <br> |
| <br> |
| The <b>--heap-limit</b> option specifies, as a number of kibibytes (units of |
| 1024 bytes), the amount of heap memory that may be used for matching. Heap |
| memory is needed only if matching the pattern requires a significant number of |
| nested backtracking points to be remembered. This parameter can be set to zero |
| to forbid the use of heap memory altogether. |
| <br> |
| <br> |
| The <b>--depth-limit</b> option limits the depth of nested backtracking points, |
| which indirectly limits the amount of memory that is used. The amount of memory |
| needed for each backtracking point depends on the number of capturing |
| parentheses in the pattern, so the amount of memory that is used before this |
| limit acts varies from pattern to pattern. This limit is of use only if it is |
| set smaller than <b>--match-limit</b>. |
| <br> |
| <br> |
| There are no short forms for these options. The default limits can be set |
| when the PCRE2 library is compiled; if they are not specified, the defaults |
| are very large and so effectively unlimited. |
| </P> |
| <P> |
| <b>--max-buffer-size</b>=<i>number</i> |
| This limits the expansion of the processing buffer, whose initial size can be |
| set by <b>--buffer-size</b>. The maximum buffer size is silently forced to be no |
| smaller than the starting buffer size. |
| </P> |
| <P> |
| <b>-N</b> <i>newline-type</i>, <b>--newline</b>=<i>newline-type</i> |
| Six different conventions for indicating the ends of lines in scanned files are |
| supported. For example: |
| <pre> |
| pcre2grep -N CRLF 'some pattern' <file> |
| </pre> |
| The newline type may be specified in upper, lower, or mixed case. If the |
| newline type is NUL, lines are separated by binary zero characters. The other |
| types are the single-character sequences CR (carriage return) and LF |
| (linefeed), the two-character sequence CRLF, an "anycrlf" type, which |
| recognizes any of the preceding three types, and an "any" type, for which any |
| Unicode line ending sequence is assumed to end a line. The Unicode sequences |
| are the three just mentioned, plus VT (vertical tab, U+000B), FF (form feed, |
| U+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS |
| (paragraph separator, U+2029). |
| <br> |
| <br> |
| When the PCRE2 library is built, a default line-ending sequence is specified. |
| This is normally the standard sequence for the operating system. Unless |
| otherwise specified by this option, <b>pcre2grep</b> uses the library's default. |
| <br> |
| <br> |
| This option makes it possible to use <b>pcre2grep</b> to scan files that have |
| come from other environments without having to modify their line endings. If |
| the data that is being scanned does not agree with the convention set by this |
| option, <b>pcre2grep</b> may behave in strange ways. Note that this option does |
| not apply to files specified by the <b>-f</b>, <b>--exclude-from</b>, or |
| <b>--include-from</b> options, which are expected to use the operating system's |
| standard newline sequence. |
| </P> |
| <P> |
| <b>-n</b>, <b>--line-number</b> |
| Precede each output line by its line number in the file, followed by a colon |
| for matching lines or a hyphen for context lines. If the file name is also |
| being output, it precedes the line number. When the <b>-M</b> option causes a |
| pattern to match more than one line, only the first is preceded by its line |
| number. This option is forced if <b>--line-offsets</b> is used. |
| </P> |
| <P> |
| <b>--no-jit</b> |
| If the PCRE2 library is built with support for just-in-time compiling (which |
| speeds up matching), <b>pcre2grep</b> automatically makes use of this, unless it |
| was explicitly disabled at build time. This option can be used to disable the |
| use of JIT at run time. It is provided for testing and working round problems. |
| It should never be needed in normal use. |
| </P> |
| <P> |
| <b>-O</b> <i>text</i>, <b>--output</b>=<i>text</i> |
| When there is a match, instead of outputting the line that matched, output just |
| the text specified in this option, followed by an operating-system standard |
| newline. In this mode, no context is shown. That is, the <b>-A</b>, <b>-B</b>, |
| and <b>-C</b> options are ignored. The <b>--newline</b> option has no effect on |
| this option, which is mutually exclusive with <b>--only-matching</b>, |
| <b>--file-offsets</b>, and <b>--line-offsets</b>. However, like |
| <b>--only-matching</b>, if there is more than one match in a line, each of them |
| causes a line of output. |
| <br> |
| <br> |
| Escape sequences starting with a dollar character may be used to insert the |
| contents of the matched part of the line and/or captured substrings into the |
| text. |
| <br> |
| <br> |
| $<digits> or ${<digits>} is replaced by the captured substring of the given |
| decimal number; zero substitutes the whole match. If the number is greater than |
| the number of capturing substrings, or if the capture is unset, the replacement |
| is empty. |
| <br> |
| <br> |
| $a is replaced by bell; $b by backspace; $e by escape; $f by form feed; $n by |
| newline; $r by carriage return; $t by tab; $v by vertical tab. |
| <br> |
| <br> |
| $o<digits> or $o{<digits>} is replaced by the character whose code point is the |
| given octal number. In the first form, up to three octal digits are processed. |
| When more digits are needed in Unicode mode to specify a wide character, the |
| second form must be used. |
| <br> |
| <br> |
| $x<digits> or $x{<digits>} is replaced by the character represented by the |
| given hexadecimal number. In the first form, up to two hexadecimal digits are |
| processed. When more digits are needed in Unicode mode to specify a wide |
| character, the second form must be used. |
| <br> |
| <br> |
| Any other character is substituted by itself. In particular, $$ is replaced by |
| a single dollar. |
| </P> |
| <P> |
| <b>-o</b>, <b>--only-matching</b> |
| Show only the part of the line that matched a pattern instead of the whole |
| line. In this mode, no context is shown. That is, the <b>-A</b>, <b>-B</b>, and |
| <b>-C</b> options are ignored. If there is more than one match in a line, each |
| of them is shown separately, on a separate line of output. If <b>-o</b> is |
| combined with <b>-v</b> (invert the sense of the match to find non-matching |
| lines), no output is generated, but the return code is set appropriately. If |
| the matched portion of the line is empty, 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 <b>--output</b>, |
| <b>--file-offsets</b> and <b>--line-offsets</b>. |
| </P> |
| <P> |
| <b>-o</b><i>number</i>, <b>--only-matching</b>=<i>number</i> |
| Show only the part of the line that matched the capturing parentheses of the |
| given number. Up to 50 capturing parentheses are supported by default. This |
| limit can be changed via the <b>--om-capture</b> option. A pattern may contain |
| any number of capturing parentheses, but only those whose number is within the |
| limit can be accessed by <b>-o</b>. An error occurs if the number specified by |
| <b>-o</b> is greater than the limit. |
| <br> |
| <br> |
| -o0 is the same as <b>-o</b> without a number. 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 option. 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 output. |
| <br> |
| <br> |
| If this option is given multiple times, multiple substrings are output for each |
| match, in the order the options are given, and all on one line. For example, |
| -o3 -o1 -o3 causes the substrings matched by capturing parentheses 3 and 1 and |
| then 3 again to be output. By default, there is no separator (but see the next |
| but one option). |
| </P> |
| <P> |
| <b>--om-capture</b>=<i>number</i> |
| Set the number of capturing parentheses that can be accessed by <b>-o</b>. The |
| default is 50. |
| </P> |
| <P> |
| <b>--om-separator</b>=<i>text</i> |
| Specify a separating string for multiple occurrences of <b>-o</b>. The default |
| is an empty string. Separating strings are never coloured. |
| </P> |
| <P> |
| <b>-q</b>, <b>--quiet</b> |
| Work quietly, that is, display nothing except error messages. The exit |
| status indicates whether or not any matches were found. |
| </P> |
| <P> |
| <b>-r</b>, <b>--recursive</b> |
| If any given path is a directory, recursively scan the files it contains, |
| taking note of any <b>--include</b> and <b>--exclude</b> settings. By default, a |
| directory is read as a normal file; in some operating systems this gives an |
| immediate end-of-file. This option is a shorthand for setting the <b>-d</b> |
| option to "recurse". |
| </P> |
| <P> |
| <b>--recursion-limit</b>=<i>number</i> |
| This is an obsolete synonym for <b>--depth-limit</b>. See <b>--match-limit</b> |
| above for details. |
| </P> |
| <P> |
| <b>-s</b>, <b>--no-messages</b> |
| 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 |
| found in other files. |
| </P> |
| <P> |
| <b>-t</b>, <b>--total-count</b> |
| This option is useful when scanning more than one file. If used on its own, |
| <b>-t</b> suppresses all output except for a grand total number of matching |
| lines (or non-matching lines if <b>-v</b> is used) in all the files. If <b>-t</b> |
| is used with <b>-c</b>, a grand total is output except when the previous output |
| is just one line. In other words, it is not output when just one file's count |
| is listed. If file names are being output, the grand total is preceded by |
| "TOTAL:". Otherwise, it appears as just another number. The <b>-t</b> option is |
| ignored when used with <b>-L</b> (list files without matches), because the grand |
| total would always be zero. |
| </P> |
| <P> |
| <b>-u</b>, <b>--utf</b> |
| Operate in UTF-8 mode. This option is available only if PCRE2 has been compiled |
| with UTF-8 support. All patterns (including those for any <b>--exclude</b> and |
| <b>--include</b> options) and all lines that are scanned must be valid strings |
| of UTF-8 characters. If an invalid UTF-8 string is encountered, an error |
| occurs. |
| </P> |
| <P> |
| <b>-U</b>, <b>--utf-allow-invalid</b> |
| As <b>--utf</b>, but in addition subject lines may contain invalid UTF-8 code |
| unit sequences. These can never form part of any pattern match. Patterns |
| themselves, however, must still be valid UTF-8 strings. This facility allows |
| valid UTF-8 strings to be sought within arbitrary byte sequences in executable |
| or other binary files. For more details about matching in non-valid UTF-8 |
| strings, see the |
| <a href="pcre2unicode.html"><b>pcre2unicode</b>(3)</a> |
| documentation. |
| </P> |
| <P> |
| <b>-V</b>, <b>--version</b> |
| Write the version numbers of <b>pcre2grep</b> and the PCRE2 library to the |
| standard output and then exit. Anything else on the command line is |
| ignored. |
| </P> |
| <P> |
| <b>-v</b>, <b>--invert-match</b> |
| Invert the sense of the match, so that lines which do <i>not</i> match any of |
| the patterns are the ones that are found. When this option is set, options such |
| as <b>--only-matching</b> and <b>--output</b>, which specify parts of a match |
| that are to be output, are ignored. |
| </P> |
| <P> |
| <b>-w</b>, <b>--word-regex</b>, <b>--word-regexp</b> |
| Force the patterns only to match "words". That is, there must be a word |
| boundary at the start and end of each matched string. This is equivalent to |
| having "\b(?:" at the start of each pattern, and ")\b" at the end. This |
| option applies only to the patterns that are matched against the contents of |
| files; it does not apply to patterns specified by any of the <b>--include</b> or |
| <b>--exclude</b> options. |
| </P> |
| <P> |
| <b>-x</b>, <b>--line-regex</b>, <b>--line-regexp</b> |
| Force the patterns to start matching only at the beginnings of lines, and in |
| addition, require them to match entire lines. In multiline mode the match may |
| be more than one line. This is equivalent to having "^(?:" at the start of each |
| pattern and ")$" at the end. This option applies only to the patterns that are |
| matched against the contents of files; it does not apply to patterns specified |
| by any of the <b>--include</b> or <b>--exclude</b> options. |
| </P> |
| <br><a name="SEC7" href="#TOC1">ENVIRONMENT VARIABLES</a><br> |
| <P> |
| The environment variables <b>LC_ALL</b> and <b>LC_CTYPE</b> are examined, in that |
| order, for a locale. The first one that is set is used. This can be overridden |
| by the <b>--locale</b> option. If no locale is set, the PCRE2 library's default |
| (usually the "C" locale) is used. |
| </P> |
| <br><a name="SEC8" href="#TOC1">NEWLINES</a><br> |
| <P> |
| The <b>-N</b> (<b>--newline</b>) option allows <b>pcre2grep</b> to scan files with |
| newline conventions that differ from the default. This option affects only the |
| way scanned files are processed. It does not affect the interpretation of files |
| specified by the <b>-f</b>, <b>--file-list</b>, <b>--exclude-from</b>, or |
| <b>--include-from</b> options. |
| </P> |
| <P> |
| Any parts of the scanned input files that are written to the standard output |
| are copied with whatever newline sequences they have in the input. However, if |
| the final line of a file is output, and it does not end with a newline |
| sequence, a newline sequence is added. If the newline setting is CR, LF, CRLF |
| or NUL, that line ending is output; for the other settings (ANYCRLF or ANY) a |
| single NL is used. |
| </P> |
| <P> |
| The newline setting does not affect the way in which <b>pcre2grep</b> writes |
| newlines in informational messages to the standard output and error streams. |
| Under Windows, the standard output is set to be binary, so that "\r\n" at the |
| ends of output lines that are copied from the input is not converted to |
| "\r\r\n" by the C I/O library. This means that any messages written to the |
| standard output must end with "\r\n". For all other operating systems, and |
| for all messages to the standard error stream, "\n" is used. |
| </P> |
| <br><a name="SEC9" href="#TOC1">OPTIONS COMPATIBILITY</a><br> |
| <P> |
| Many of the short and long forms of <b>pcre2grep</b>'s options are the same |
| as in the GNU <b>grep</b> program. Any long option of the form |
| <b>--xxx-regexp</b> (GNU terminology) is also available as <b>--xxx-regex</b> |
| (PCRE2 terminology). However, the <b>--depth-limit</b>, <b>--file-list</b>, |
| <b>--file-offsets</b>, <b>--heap-limit</b>, <b>--include-dir</b>, |
| <b>--line-offsets</b>, <b>--locale</b>, <b>--match-limit</b>, <b>-M</b>, |
| <b>--multiline</b>, <b>-N</b>, <b>--newline</b>, <b>--om-separator</b>, |
| <b>--output</b>, <b>-u</b>, <b>--utf</b>, <b>-U</b>, and <b>--utf-allow-invalid</b> |
| options are specific to <b>pcre2grep</b>, as is the use of the |
| <b>--only-matching</b> option with a capturing parentheses number. |
| </P> |
| <P> |
| Although most of the common options work the same way, a few are different in |
| <b>pcre2grep</b>. For example, the <b>--include</b> option's argument is a glob |
| for GNU <b>grep</b>, but a regular expression for <b>pcre2grep</b>. If both the |
| <b>-c</b> and <b>-l</b> options are given, GNU grep lists only file names, |
| without counts, but <b>pcre2grep</b> gives the counts as well. |
| </P> |
| <br><a name="SEC10" href="#TOC1">OPTIONS WITH DATA</a><br> |
| <P> |
| 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 (with one |
| exception) in the next command line item. For example: |
| <pre> |
| -f/some/file |
| -f /some/file |
| </pre> |
| The exception is the <b>-o</b> 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> |
| <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 two exceptions) it may appear |
| in the next command line item. For example: |
| <pre> |
| --file=/some/file |
| --file /some/file |
| </pre> |
| 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 directory, 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. |
| </P> |
| <P> |
| The exceptions to the above are the <b>--colour</b> (or <b>--color</b>) and |
| <b>--only-matching</b> options, for which the data is optional. If one of these |
| options does have data, it must be given in the first form, using an equals |
| character. Otherwise <b>pcre2grep</b> will assume that it has no data. |
| </P> |
| <br><a name="SEC11" href="#TOC1">USING PCRE2'S CALLOUT FACILITY</a><br> |
| <P> |
| <b>pcre2grep</b> has, by default, support for calling external programs or |
| scripts or echoing specific strings during matching by making use of PCRE2's |
| callout facility. However, this support can be completely or partially disabled |
| when <b>pcre2grep</b> is built. You can find out whether your binary has support |
| for callouts by running it with the <b>--help</b> option. If callout support is |
| completely disabled, all callouts in patterns are ignored by <b>pcre2grep</b>. |
| If the facility is partially disabled, calling external programs is not |
| supported, and callouts that request it are ignored. |
| </P> |
| <P> |
| A callout in a PCRE2 pattern is of the form (?C<arg>) where the argument is |
| either a number or a quoted string (see the |
| <a href="pcre2callout.html"><b>pcre2callout</b></a> |
| documentation for details). Numbered callouts are ignored by <b>pcre2grep</b>; |
| only callouts with string arguments are useful. |
| </P> |
| <br><b> |
| Echoing a specific string |
| </b><br> |
| <P> |
| Starting the callout string with a pipe character invokes an echoing facility |
| that avoids calling an external program or script. This facility is always |
| available, provided that callouts were not completely disabled when |
| <b>pcre2grep</b> was built. The rest of the callout string is processed as a |
| zero-terminated string, which means it should not contain any internal binary |
| zeros. It is written to the output, having first been passed through the same |
| escape processing as text from the <b>--output</b> (<b>-O</b>) option (see |
| above). However, $0 cannot be used to insert a matched substring because the |
| match is still in progress. Instead, the single character '0' is inserted. Any |
| syntax errors in the string (for example, a dollar not followed by another |
| character) causes the callout to be ignored. No terminator is added to the |
| output string, so if you want a newline, you must include it explicitly using |
| the escape $n. For example: |
| <pre> |
| pcre2grep '(.)(..(.))(?C"|[$1] [$2] [$3]$n")' <some file> |
| </pre> |
| Matching continues normally after the string is output. If you want to see only |
| the callout output but not any output from an actual match, you should end the |
| pattern with (*FAIL). |
| </P> |
| <br><b> |
| Calling external programs or scripts |
| </b><br> |
| <P> |
| This facility can be independently disabled when <b>pcre2grep</b> is built. It |
| is supported for Windows, where a call to <b>_spawnvp()</b> is used, for VMS, |
| where <b>lib$spawn()</b> is used, and for any Unix-like environment where |
| <b>fork()</b> and <b>execv()</b> are available. |
| </P> |
| <P> |
| If the callout string does not start with a pipe (vertical bar) character, it |
| is parsed into a list of substrings separated by pipe characters. The first |
| substring must be an executable name, with the following substrings specifying |
| arguments: |
| <pre> |
| executable_name|arg1|arg2|... |
| </pre> |
| Any substring (including the executable name) may contain escape sequences |
| started by a dollar character. These are the same as for the <b>--output</b> |
| (<b>-O</b>) option documented above, except that $0 cannot insert the matched |
| string because the match is still in progress. Instead, the character '0' |
| is inserted. If you need a literal dollar or pipe character in any |
| substring, use $$ or $| respectively. Here is an example: |
| <pre> |
| echo -e "abcde\n12345" | pcre2grep \ |
| '(?x)(.)(..(.)) |
| (?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' - |
| |
| Output: |
| |
| Arg1: [a] [bcd] [d] Arg2: |a| () |
| abcde |
| Arg1: [1] [234] [4] Arg2: |1| () |
| 12345 |
| </pre> |
| The parameters for the system call that is used to run the program or script |
| are zero-terminated strings. This means that binary zero characters in the |
| callout argument will cause premature termination of their substrings, and |
| therefore should not be present. Any syntax errors in the string (for example, |
| a dollar not followed by another character) causes the callout to be ignored. |
| If running the program fails for any reason (including the non-existence of the |
| executable), a local matching failure occurs and the matcher backtracks in the |
| normal way. |
| </P> |
| <br><a name="SEC12" href="#TOC1">MATCHING ERRORS</a><br> |
| <P> |
| It is possible to supply a regular expression that takes a very long time to |
| fail to match certain lines. Such patterns normally involve nested indefinite |
| repeats, for example: (a+)*\d when matched against a line of a's with no final |
| digit. The PCRE2 matching function has a resource limit that causes it to abort |
| in these circumstances. If this happens, <b>pcre2grep</b> outputs an error |
| message and the line that caused the problem to the standard error stream. If |
| there are more than 20 such errors, <b>pcre2grep</b> gives up. |
| </P> |
| <P> |
| The <b>--match-limit</b> option of <b>pcre2grep</b> can be used to set the |
| overall resource limit. There are also other limits that affect the amount of |
| memory used during matching; see the discussion of <b>--heap-limit</b> and |
| <b>--depth-limit</b> above. |
| </P> |
| <br><a name="SEC13" href="#TOC1">DIAGNOSTICS</a><br> |
| <P> |
| 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 files (even if |
| matches were found in other files) or too many matching errors. Using the |
| <b>-s</b> option to suppress error messages about inaccessible files does not |
| affect the return code. |
| </P> |
| <P> |
| When run under VMS, the return code is placed in the symbol PCRE2GREP_RC |
| because VMS does not distinguish between exit(0) and exit(1). |
| </P> |
| <br><a name="SEC14" href="#TOC1">SEE ALSO</a><br> |
| <P> |
| <b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3), |
| <b>pcre2unicode</b>(3). |
| </P> |
| <br><a name="SEC15" href="#TOC1">AUTHOR</a><br> |
| <P> |
| Philip Hazel |
| <br> |
| Retired from University Computing Service |
| <br> |
| Cambridge, England. |
| <br> |
| </P> |
| <br><a name="SEC16" href="#TOC1">REVISION</a><br> |
| <P> |
| Last updated: 31 August 2021 |
| <br> |
| Copyright © 1997-2021 University of Cambridge. |
| <br> |
| <p> |
| Return to the <a href="index.html">PCRE2 index page</a>. |
| </p> |