1*22dc650dSSadaf Ebrahimi<html> 2*22dc650dSSadaf Ebrahimi<head> 3*22dc650dSSadaf Ebrahimi<title>pcre2grep specification</title> 4*22dc650dSSadaf Ebrahimi</head> 5*22dc650dSSadaf Ebrahimi<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6*22dc650dSSadaf Ebrahimi<h1>pcre2grep man page</h1> 7*22dc650dSSadaf Ebrahimi<p> 8*22dc650dSSadaf EbrahimiReturn to the <a href="index.html">PCRE2 index page</a>. 9*22dc650dSSadaf Ebrahimi</p> 10*22dc650dSSadaf Ebrahimi<p> 11*22dc650dSSadaf EbrahimiThis page is part of the PCRE2 HTML documentation. It was generated 12*22dc650dSSadaf Ebrahimiautomatically from the original man page. If there is any nonsense in it, 13*22dc650dSSadaf Ebrahimiplease consult the man page, in case the conversion went wrong. 14*22dc650dSSadaf Ebrahimi<br> 15*22dc650dSSadaf Ebrahimi<ul> 16*22dc650dSSadaf Ebrahimi<li><a name="TOC1" href="#SEC1">SYNOPSIS</a> 17*22dc650dSSadaf Ebrahimi<li><a name="TOC2" href="#SEC2">DESCRIPTION</a> 18*22dc650dSSadaf Ebrahimi<li><a name="TOC3" href="#SEC3">SUPPORT FOR COMPRESSED FILES</a> 19*22dc650dSSadaf Ebrahimi<li><a name="TOC4" href="#SEC4">BINARY FILES</a> 20*22dc650dSSadaf Ebrahimi<li><a name="TOC5" href="#SEC5">BINARY ZEROS IN PATTERNS</a> 21*22dc650dSSadaf Ebrahimi<li><a name="TOC6" href="#SEC6">OPTIONS</a> 22*22dc650dSSadaf Ebrahimi<li><a name="TOC7" href="#SEC7">ENVIRONMENT VARIABLES</a> 23*22dc650dSSadaf Ebrahimi<li><a name="TOC8" href="#SEC8">NEWLINES</a> 24*22dc650dSSadaf Ebrahimi<li><a name="TOC9" href="#SEC9">OPTIONS COMPATIBILITY WITH GNU GREP</a> 25*22dc650dSSadaf Ebrahimi<li><a name="TOC10" href="#SEC10">OPTIONS WITH DATA</a> 26*22dc650dSSadaf Ebrahimi<li><a name="TOC11" href="#SEC11">USING PCRE2'S CALLOUT FACILITY</a> 27*22dc650dSSadaf Ebrahimi<li><a name="TOC12" href="#SEC12">MATCHING ERRORS</a> 28*22dc650dSSadaf Ebrahimi<li><a name="TOC13" href="#SEC13">DIAGNOSTICS</a> 29*22dc650dSSadaf Ebrahimi<li><a name="TOC14" href="#SEC14">SEE ALSO</a> 30*22dc650dSSadaf Ebrahimi<li><a name="TOC15" href="#SEC15">AUTHOR</a> 31*22dc650dSSadaf Ebrahimi<li><a name="TOC16" href="#SEC16">REVISION</a> 32*22dc650dSSadaf Ebrahimi</ul> 33*22dc650dSSadaf Ebrahimi<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> 34*22dc650dSSadaf Ebrahimi<P> 35*22dc650dSSadaf Ebrahimi<b>pcre2grep [options] [long options] [pattern] [path1 path2 ...]</b> 36*22dc650dSSadaf Ebrahimi</P> 37*22dc650dSSadaf Ebrahimi<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> 38*22dc650dSSadaf Ebrahimi<P> 39*22dc650dSSadaf Ebrahimi<b>pcre2grep</b> searches files for character patterns, in the same way as other 40*22dc650dSSadaf Ebrahimigrep commands do, but it uses the PCRE2 regular expression library to support 41*22dc650dSSadaf Ebrahimipatterns that are compatible with the regular expressions of Perl 5. See 42*22dc650dSSadaf Ebrahimi<a href="pcre2syntax.html"><b>pcre2syntax</b>(3)</a> 43*22dc650dSSadaf Ebrahimifor a quick-reference summary of pattern syntax, or 44*22dc650dSSadaf Ebrahimi<a href="pcre2pattern.html"><b>pcre2pattern</b>(3)</a> 45*22dc650dSSadaf Ebrahimifor a full description of the syntax and semantics of the regular expressions 46*22dc650dSSadaf Ebrahimithat PCRE2 supports. 47*22dc650dSSadaf Ebrahimi</P> 48*22dc650dSSadaf Ebrahimi<P> 49*22dc650dSSadaf EbrahimiPatterns, whether supplied on the command line or in a separate file, are given 50*22dc650dSSadaf Ebrahimiwithout delimiters. For example: 51*22dc650dSSadaf Ebrahimi<pre> 52*22dc650dSSadaf Ebrahimi pcre2grep Thursday /etc/motd 53*22dc650dSSadaf Ebrahimi</pre> 54*22dc650dSSadaf EbrahimiIf you attempt to use delimiters (for example, by surrounding a pattern with 55*22dc650dSSadaf Ebrahimislashes, as is common in Perl scripts), they are interpreted as part of the 56*22dc650dSSadaf Ebrahimipattern. Quotes can of course be used to delimit patterns on the command line 57*22dc650dSSadaf Ebrahimibecause they are interpreted by the shell, and indeed quotes are required if a 58*22dc650dSSadaf Ebrahimipattern contains white space or shell metacharacters. 59*22dc650dSSadaf Ebrahimi</P> 60*22dc650dSSadaf Ebrahimi<P> 61*22dc650dSSadaf EbrahimiThe first argument that follows any option settings is treated as the single 62*22dc650dSSadaf Ebrahimipattern to be matched when neither <b>-e</b> nor <b>-f</b> is present. 63*22dc650dSSadaf EbrahimiConversely, when one or both of these options are used to specify patterns, all 64*22dc650dSSadaf Ebrahimiarguments are treated as path names. At least one of <b>-e</b>, <b>-f</b>, or an 65*22dc650dSSadaf Ebrahimiargument pattern must be provided. 66*22dc650dSSadaf Ebrahimi</P> 67*22dc650dSSadaf Ebrahimi<P> 68*22dc650dSSadaf EbrahimiIf no files are specified, <b>pcre2grep</b> reads the standard input. The 69*22dc650dSSadaf Ebrahimistandard input can also be referenced by a name consisting of a single hyphen. 70*22dc650dSSadaf EbrahimiFor example: 71*22dc650dSSadaf Ebrahimi<pre> 72*22dc650dSSadaf Ebrahimi pcre2grep some-pattern file1 - file3 73*22dc650dSSadaf Ebrahimi</pre> 74*22dc650dSSadaf EbrahimiBy default, input files are searched line by line, so pattern assertions about 75*22dc650dSSadaf Ebrahimithe beginning and end of a subject string (^, $, \A, \Z, and \z) match at 76*22dc650dSSadaf Ebrahimithe beginning and end of each line. When a line matches a pattern, it is copied 77*22dc650dSSadaf Ebrahimito the standard output, and if there is more than one file, the file name is 78*22dc650dSSadaf Ebrahimioutput at the start of each line, followed by a colon. However, there are 79*22dc650dSSadaf Ebrahimioptions that can change how <b>pcre2grep</b> behaves. For example, the <b>-M</b> 80*22dc650dSSadaf Ebrahimioption makes it possible to search for strings that span line boundaries. What 81*22dc650dSSadaf Ebrahimidefines a line boundary is controlled by the <b>-N</b> (<b>--newline</b>) option. 82*22dc650dSSadaf EbrahimiThe <b>-h</b> and <b>-H</b> options control whether or not file names are shown, 83*22dc650dSSadaf Ebrahimiand the <b>-Z</b> option changes the file name terminator to a zero byte. 84*22dc650dSSadaf Ebrahimi</P> 85*22dc650dSSadaf Ebrahimi<P> 86*22dc650dSSadaf EbrahimiThe amount of memory used for buffering files that are being scanned is 87*22dc650dSSadaf Ebrahimicontrolled by parameters that can be set by the <b>--buffer-size</b> and 88*22dc650dSSadaf Ebrahimi<b>--max-buffer-size</b> options. The first of these sets the size of buffer 89*22dc650dSSadaf Ebrahimithat is obtained at the start of processing. If an input file contains very 90*22dc650dSSadaf Ebrahimilong lines, a larger buffer may be needed; this is handled by automatically 91*22dc650dSSadaf Ebrahimiextending the buffer, up to the limit specified by <b>--max-buffer-size</b>. The 92*22dc650dSSadaf Ebrahimidefault values for these parameters can be set when <b>pcre2grep</b> is 93*22dc650dSSadaf Ebrahimibuilt; if nothing is specified, the defaults are set to 20KiB and 1MiB 94*22dc650dSSadaf Ebrahimirespectively. An error occurs if a line is too long and the buffer can no 95*22dc650dSSadaf Ebrahimilonger be expanded. 96*22dc650dSSadaf Ebrahimi</P> 97*22dc650dSSadaf Ebrahimi<P> 98*22dc650dSSadaf EbrahimiThe block of memory that is actually used is three times the "buffer size", to 99*22dc650dSSadaf Ebrahimiallow for buffering "before" and "after" lines. If the buffer size is too 100*22dc650dSSadaf Ebrahimismall, fewer than requested "before" and "after" lines may be output. 101*22dc650dSSadaf Ebrahimi</P> 102*22dc650dSSadaf Ebrahimi<P> 103*22dc650dSSadaf EbrahimiWhen matching with a multiline pattern, the size of the buffer must be at least 104*22dc650dSSadaf Ebrahimihalf of the maximum match expected or the pattern might fail to match. 105*22dc650dSSadaf Ebrahimi</P> 106*22dc650dSSadaf Ebrahimi<P> 107*22dc650dSSadaf EbrahimiPatterns can be no longer than 8KiB or BUFSIZ bytes, whichever is the greater. 108*22dc650dSSadaf EbrahimiBUFSIZ is defined in <b><stdio.h></b>. When there is more than one pattern 109*22dc650dSSadaf Ebrahimi(specified by the use of <b>-e</b> and/or <b>-f</b>), each pattern is applied to 110*22dc650dSSadaf Ebrahimieach line in the order in which they are defined, except that all the <b>-e</b> 111*22dc650dSSadaf Ebrahimipatterns are tried before the <b>-f</b> patterns. 112*22dc650dSSadaf Ebrahimi</P> 113*22dc650dSSadaf Ebrahimi<P> 114*22dc650dSSadaf EbrahimiBy default, as soon as one pattern matches a line, no further patterns are 115*22dc650dSSadaf Ebrahimiconsidered. However, if <b>--colour</b> (or <b>--color</b>) is used to colour the 116*22dc650dSSadaf Ebrahimimatching substrings, or if <b>--only-matching</b>, <b>--file-offsets</b>, 117*22dc650dSSadaf Ebrahimi<b>--line-offsets</b>, or <b>--output</b> is used to output only the part of the 118*22dc650dSSadaf Ebrahimiline that matched (either shown literally, or as an offset), the behaviour is 119*22dc650dSSadaf Ebrahimidifferent. In this situation, all the patterns are applied to the line. If 120*22dc650dSSadaf Ebrahimithere is more than one match, the one that begins nearest to the start of the 121*22dc650dSSadaf Ebrahimisubject is processed; if there is more than one match at that position, the one 122*22dc650dSSadaf Ebrahimiwith the longest matching substring is processed; if the matching substrings 123*22dc650dSSadaf Ebrahimiare equal, the first match found is processed. 124*22dc650dSSadaf Ebrahimi</P> 125*22dc650dSSadaf Ebrahimi<P> 126*22dc650dSSadaf EbrahimiScanning with all the patterns resumes immediately following the match, so that 127*22dc650dSSadaf Ebrahimilater matches on the same line can be found. Note, however, that an overlapping 128*22dc650dSSadaf Ebrahimimatch that starts in the middle of another match will not be processed. 129*22dc650dSSadaf Ebrahimi</P> 130*22dc650dSSadaf Ebrahimi<P> 131*22dc650dSSadaf EbrahimiThe above behaviour was changed at release 10.41 to be more compatible with GNU 132*22dc650dSSadaf Ebrahimigrep. In earlier releases, <b>pcre2grep</b> did not recognize matches from 133*22dc650dSSadaf Ebrahimilater patterns that were earlier in the subject. 134*22dc650dSSadaf Ebrahimi</P> 135*22dc650dSSadaf Ebrahimi<P> 136*22dc650dSSadaf EbrahimiPatterns that can match an empty string are accepted, but empty string 137*22dc650dSSadaf Ebrahimimatches are never recognized. An example is the pattern "(super)?(man)?", in 138*22dc650dSSadaf Ebrahimiwhich all components are optional. This pattern finds all occurrences of both 139*22dc650dSSadaf Ebrahimi"super" and "man"; the output differs from matching with "super|man" when only 140*22dc650dSSadaf Ebrahimithe matching substrings are being shown. 141*22dc650dSSadaf Ebrahimi</P> 142*22dc650dSSadaf Ebrahimi<P> 143*22dc650dSSadaf EbrahimiIf the <b>LC_ALL</b> or <b>LC_CTYPE</b> environment variable is set, 144*22dc650dSSadaf Ebrahimi<b>pcre2grep</b> uses the value to set a locale when calling the PCRE2 library. 145*22dc650dSSadaf EbrahimiThe <b>--locale</b> option can be used to override this. 146*22dc650dSSadaf Ebrahimi</P> 147*22dc650dSSadaf Ebrahimi<br><a name="SEC3" href="#TOC1">SUPPORT FOR COMPRESSED FILES</a><br> 148*22dc650dSSadaf Ebrahimi<P> 149*22dc650dSSadaf EbrahimiCompile-time options for <b>pcre2grep</b> can set it up to use <b>libz</b> or 150*22dc650dSSadaf Ebrahimi<b>libbz2</b> for reading compressed files whose names end in <b>.gz</b> or 151*22dc650dSSadaf Ebrahimi<b>.bz2</b>, respectively. You can find out whether your <b>pcre2grep</b> binary 152*22dc650dSSadaf Ebrahimihas support for one or both of these file types by running it with the 153*22dc650dSSadaf Ebrahimi<b>--help</b> option. If the appropriate support is not present, all files are 154*22dc650dSSadaf Ebrahimitreated as plain text. The standard input is always so treated. If a file with 155*22dc650dSSadaf Ebrahimia <b>.gz</b> or <b>.bz2</b> extension is not in fact compressed, it is read as a 156*22dc650dSSadaf Ebrahimiplain text file. When input is from a compressed .gz or .bz2 file, the 157*22dc650dSSadaf Ebrahimi<b>--line-buffered</b> option is ignored. 158*22dc650dSSadaf Ebrahimi</P> 159*22dc650dSSadaf Ebrahimi<br><a name="SEC4" href="#TOC1">BINARY FILES</a><br> 160*22dc650dSSadaf Ebrahimi<P> 161*22dc650dSSadaf EbrahimiBy default, a file that contains a binary zero byte within the first 1024 bytes 162*22dc650dSSadaf Ebrahimiis identified as a binary file, and is processed specially. However, if the 163*22dc650dSSadaf Ebrahiminewline type is specified as NUL, that is, the line terminator is a binary 164*22dc650dSSadaf Ebrahimizero, the test for a binary file is not applied. See the <b>--binary-files</b> 165*22dc650dSSadaf Ebrahimioption for a means of changing the way binary files are handled. 166*22dc650dSSadaf Ebrahimi</P> 167*22dc650dSSadaf Ebrahimi<br><a name="SEC5" href="#TOC1">BINARY ZEROS IN PATTERNS</a><br> 168*22dc650dSSadaf Ebrahimi<P> 169*22dc650dSSadaf EbrahimiPatterns passed from the command line are strings that are terminated by a 170*22dc650dSSadaf Ebrahimibinary zero, so cannot contain internal zeros. However, patterns that are read 171*22dc650dSSadaf Ebrahimifrom a file via the <b>-f</b> option may contain binary zeros. 172*22dc650dSSadaf Ebrahimi</P> 173*22dc650dSSadaf Ebrahimi<br><a name="SEC6" href="#TOC1">OPTIONS</a><br> 174*22dc650dSSadaf Ebrahimi<P> 175*22dc650dSSadaf EbrahimiThe order in which some of the options appear can affect the output. For 176*22dc650dSSadaf Ebrahimiexample, both the <b>-H</b> and <b>-l</b> options affect the printing of file 177*22dc650dSSadaf Ebrahiminames. Whichever comes later in the command line will be the one that takes 178*22dc650dSSadaf Ebrahimieffect. Similarly, except where noted below, if an option is given twice, the 179*22dc650dSSadaf Ebrahimilater setting is used. Numerical values for options may be followed by K or M, 180*22dc650dSSadaf Ebrahimito signify multiplication by 1024 or 1024*1024 respectively. 181*22dc650dSSadaf Ebrahimi</P> 182*22dc650dSSadaf Ebrahimi<P> 183*22dc650dSSadaf Ebrahimi<b>--</b> 184*22dc650dSSadaf EbrahimiThis terminates the list of options. It is useful if the next item on the 185*22dc650dSSadaf Ebrahimicommand line starts with a hyphen but is not an option. This allows for the 186*22dc650dSSadaf Ebrahimiprocessing of patterns and file names that start with hyphens. 187*22dc650dSSadaf Ebrahimi</P> 188*22dc650dSSadaf Ebrahimi<P> 189*22dc650dSSadaf Ebrahimi<b>-A</b> <i>number</i>, <b>--after-context=</b><i>number</i> 190*22dc650dSSadaf EbrahimiOutput up to <i>number</i> lines of context after each matching line. Fewer 191*22dc650dSSadaf Ebrahimilines are output if the next match or the end of the file is reached, or if the 192*22dc650dSSadaf Ebrahimiprocessing buffer size has been set too small. If file names and/or line 193*22dc650dSSadaf Ebrahiminumbers are being output, a hyphen separator is used instead of a colon for the 194*22dc650dSSadaf Ebrahimicontext lines (the <b>-Z</b> option can be used to change the file name 195*22dc650dSSadaf Ebrahimiterminator to a zero byte). A line containing "--" is output between each group 196*22dc650dSSadaf Ebrahimiof lines, unless they are in fact contiguous in the input file. The value of 197*22dc650dSSadaf Ebrahimi<i>number</i> is expected to be relatively small. When <b>-c</b> is used, 198*22dc650dSSadaf Ebrahimi<b>-A</b> is ignored. 199*22dc650dSSadaf Ebrahimi</P> 200*22dc650dSSadaf Ebrahimi<P> 201*22dc650dSSadaf Ebrahimi<b>-a</b>, <b>--text</b> 202*22dc650dSSadaf EbrahimiTreat binary files as text. This is equivalent to 203*22dc650dSSadaf Ebrahimi<b>--binary-files</b>=<i>text</i>. 204*22dc650dSSadaf Ebrahimi</P> 205*22dc650dSSadaf Ebrahimi<P> 206*22dc650dSSadaf Ebrahimi<b>--allow-lookaround-bsk</b> 207*22dc650dSSadaf EbrahimiPCRE2 now forbids the use of \K in lookarounds by default, in line with Perl. 208*22dc650dSSadaf EbrahimiThis option causes <b>pcre2grep</b> to set the PCRE2_EXTRA_ALLOW_LOOKAROUND_BSK 209*22dc650dSSadaf Ebrahimioption, which enables this somewhat dangerous usage. 210*22dc650dSSadaf Ebrahimi</P> 211*22dc650dSSadaf Ebrahimi<P> 212*22dc650dSSadaf Ebrahimi<b>-B</b> <i>number</i>, <b>--before-context=</b><i>number</i> 213*22dc650dSSadaf EbrahimiOutput up to <i>number</i> lines of context before each matching line. Fewer 214*22dc650dSSadaf Ebrahimilines are output if the previous match or the start of the file is within 215*22dc650dSSadaf Ebrahimi<i>number</i> lines, or if the processing buffer size has been set too small. If 216*22dc650dSSadaf Ebrahimifile names and/or line numbers are being output, a hyphen separator is used 217*22dc650dSSadaf Ebrahimiinstead of a colon for the context lines (the <b>-Z</b> option can be used to 218*22dc650dSSadaf Ebrahimichange the file name terminator to a zero byte). A line containing "--" is 219*22dc650dSSadaf Ebrahimioutput between each group of lines, unless they are in fact contiguous in the 220*22dc650dSSadaf Ebrahimiinput file. The value of <i>number</i> is expected to be relatively small. When 221*22dc650dSSadaf Ebrahimi<b>-c</b> is used, <b>-B</b> is ignored. 222*22dc650dSSadaf Ebrahimi</P> 223*22dc650dSSadaf Ebrahimi<P> 224*22dc650dSSadaf Ebrahimi<b>--binary-files=</b><i>word</i> 225*22dc650dSSadaf EbrahimiSpecify how binary files are to be processed. If the word is "binary" (the 226*22dc650dSSadaf Ebrahimidefault), pattern matching is performed on binary files, but the only output is 227*22dc650dSSadaf Ebrahimi"Binary file <name> matches" when a match succeeds. If the word is "text", 228*22dc650dSSadaf Ebrahimiwhich is equivalent to the <b>-a</b> or <b>--text</b> option, binary files are 229*22dc650dSSadaf Ebrahimiprocessed in the same way as any other file. In this case, when a match 230*22dc650dSSadaf Ebrahimisucceeds, the output may be binary garbage, which can have nasty effects if 231*22dc650dSSadaf Ebrahimisent to a terminal. If the word is "without-match", which is equivalent to the 232*22dc650dSSadaf Ebrahimi<b>-I</b> option, binary files are not processed at all; they are assumed not to 233*22dc650dSSadaf Ebrahimibe of interest and are skipped without causing any output or affecting the 234*22dc650dSSadaf Ebrahimireturn code. 235*22dc650dSSadaf Ebrahimi</P> 236*22dc650dSSadaf Ebrahimi<P> 237*22dc650dSSadaf Ebrahimi<b>--buffer-size=</b><i>number</i> 238*22dc650dSSadaf EbrahimiSet the parameter that controls how much memory is obtained at the start of 239*22dc650dSSadaf Ebrahimiprocessing for buffering files that are being scanned. See also 240*22dc650dSSadaf Ebrahimi<b>--max-buffer-size</b> below. 241*22dc650dSSadaf Ebrahimi</P> 242*22dc650dSSadaf Ebrahimi<P> 243*22dc650dSSadaf Ebrahimi<b>-C</b> <i>number</i>, <b>--context=</b><i>number</i> 244*22dc650dSSadaf EbrahimiOutput <i>number</i> lines of context both before and after each matching line. 245*22dc650dSSadaf EbrahimiThis is equivalent to setting both <b>-A</b> and <b>-B</b> to the same value. 246*22dc650dSSadaf Ebrahimi</P> 247*22dc650dSSadaf Ebrahimi<P> 248*22dc650dSSadaf Ebrahimi<b>-c</b>, <b>--count</b> 249*22dc650dSSadaf EbrahimiDo not output lines from the files that are being scanned; instead output the 250*22dc650dSSadaf Ebrahiminumber of lines that would have been shown, either because they matched, or, if 251*22dc650dSSadaf Ebrahimi<b>-v</b> is set, because they failed to match. By default, this count is 252*22dc650dSSadaf Ebrahimiexactly the same as the number of lines that would have been output, but if the 253*22dc650dSSadaf Ebrahimi<b>-M</b> (multiline) option is used (without <b>-v</b>), there may be more 254*22dc650dSSadaf Ebrahimisuppressed lines than the count (that is, the number of matches). 255*22dc650dSSadaf Ebrahimi<br> 256*22dc650dSSadaf Ebrahimi<br> 257*22dc650dSSadaf EbrahimiIf no lines are selected, the number zero is output. If several files are 258*22dc650dSSadaf Ebrahimibeing scanned, a count is output for each of them and the <b>-t</b> option can 259*22dc650dSSadaf Ebrahimibe used to cause a total to be output at the end. However, if the 260*22dc650dSSadaf Ebrahimi<b>--files-with-matches</b> option is also used, only those files whose counts 261*22dc650dSSadaf Ebrahimiare greater than zero are listed. When <b>-c</b> is used, the <b>-A</b>, 262*22dc650dSSadaf Ebrahimi<b>-B</b>, and <b>-C</b> options are ignored. 263*22dc650dSSadaf Ebrahimi</P> 264*22dc650dSSadaf Ebrahimi<P> 265*22dc650dSSadaf Ebrahimi<b>--colour</b>, <b>--color</b> 266*22dc650dSSadaf EbrahimiIf this option is given without any data, it is equivalent to "--colour=auto". 267*22dc650dSSadaf EbrahimiIf data is required, it must be given in the same shell item, separated by an 268*22dc650dSSadaf Ebrahimiequals sign. 269*22dc650dSSadaf Ebrahimi</P> 270*22dc650dSSadaf Ebrahimi<P> 271*22dc650dSSadaf Ebrahimi<b>--colour=</b><i>value</i>, <b>--color=</b><i>value</i> 272*22dc650dSSadaf EbrahimiThis option specifies under what circumstances the parts of a line that matched 273*22dc650dSSadaf Ebrahimia pattern should be coloured in the output. It is ignored if 274*22dc650dSSadaf Ebrahimi<b>--file-offsets</b>, <b>--line-offsets</b>, or <b>--output</b> is set. By 275*22dc650dSSadaf Ebrahimidefault, output is not coloured. The value for the <b>--colour</b> option (which 276*22dc650dSSadaf Ebrahimiis optional, see above) may be "never", "always", or "auto". In the latter 277*22dc650dSSadaf Ebrahimicase, colouring happens only if the standard output is connected to a terminal. 278*22dc650dSSadaf EbrahimiMore resources are used when colouring is enabled, because <b>pcre2grep</b> has 279*22dc650dSSadaf Ebrahimito search for all possible matches in a line, not just one, in order to colour 280*22dc650dSSadaf Ebrahimithem all. 281*22dc650dSSadaf Ebrahimi<br> 282*22dc650dSSadaf Ebrahimi<br> 283*22dc650dSSadaf EbrahimiThe colour that is used can be specified by setting one of the environment 284*22dc650dSSadaf Ebrahimivariables PCRE2GREP_COLOUR, PCRE2GREP_COLOR, PCREGREP_COLOUR, or 285*22dc650dSSadaf EbrahimiPCREGREP_COLOR, which are checked in that order. If none of these are set, 286*22dc650dSSadaf Ebrahimi<b>pcre2grep</b> looks for GREP_COLORS or GREP_COLOR (in that order). The value 287*22dc650dSSadaf Ebrahimiof the variable should be a string of two numbers, separated by a semicolon, 288*22dc650dSSadaf Ebrahimiexcept in the case of GREP_COLORS, which must start with "ms=" or "mt=" 289*22dc650dSSadaf Ebrahimifollowed by two semicolon-separated colours, terminated by the end of the 290*22dc650dSSadaf Ebrahimistring or by a colon. If GREP_COLORS does not start with "ms=" or "mt=" it is 291*22dc650dSSadaf Ebrahimiignored, and GREP_COLOR is checked. 292*22dc650dSSadaf Ebrahimi<br> 293*22dc650dSSadaf Ebrahimi<br> 294*22dc650dSSadaf EbrahimiIf the string obtained from one of the above variables contains any characters 295*22dc650dSSadaf Ebrahimiother than semicolon or digits, the setting is ignored and the default colour 296*22dc650dSSadaf Ebrahimiis used. The string is copied directly into the control string for setting 297*22dc650dSSadaf Ebrahimicolour on a terminal, so it is your responsibility to ensure that the values 298*22dc650dSSadaf Ebrahimimake sense. If no relevant environment variable is set, the default is "1;31", 299*22dc650dSSadaf Ebrahimiwhich gives red. 300*22dc650dSSadaf Ebrahimi</P> 301*22dc650dSSadaf Ebrahimi<P> 302*22dc650dSSadaf Ebrahimi<b>-D</b> <i>action</i>, <b>--devices=</b><i>action</i> 303*22dc650dSSadaf EbrahimiIf an input path is not a regular file or a directory, "action" specifies how 304*22dc650dSSadaf Ebrahimiit is to be processed. Valid values are "read" (the default) or "skip" 305*22dc650dSSadaf Ebrahimi(silently skip the path). 306*22dc650dSSadaf Ebrahimi</P> 307*22dc650dSSadaf Ebrahimi<P> 308*22dc650dSSadaf Ebrahimi<b>-d</b> <i>action</i>, <b>--directories=</b><i>action</i> 309*22dc650dSSadaf EbrahimiIf an input path is a directory, "action" specifies how it is to be processed. 310*22dc650dSSadaf EbrahimiValid values are "read" (the default in non-Windows environments, for 311*22dc650dSSadaf Ebrahimicompatibility with GNU grep), "recurse" (equivalent to the <b>-r</b> option), or 312*22dc650dSSadaf Ebrahimi"skip" (silently skip the path, the default in Windows environments). In the 313*22dc650dSSadaf Ebrahimi"read" case, directories are read as if they were ordinary files. In some 314*22dc650dSSadaf Ebrahimioperating systems the effect of reading a directory like this is an immediate 315*22dc650dSSadaf Ebrahimiend-of-file; in others it may provoke an error. 316*22dc650dSSadaf Ebrahimi</P> 317*22dc650dSSadaf Ebrahimi<P> 318*22dc650dSSadaf Ebrahimi<b>--depth-limit</b>=<i>number</i> 319*22dc650dSSadaf EbrahimiSee <b>--match-limit</b> below. 320*22dc650dSSadaf Ebrahimi</P> 321*22dc650dSSadaf Ebrahimi<P> 322*22dc650dSSadaf Ebrahimi<b>-E</b>, <b>--case-restrict</b> 323*22dc650dSSadaf EbrahimiWhen case distinctions are being ignored in Unicode mode, two ASCII letters (K 324*22dc650dSSadaf Ebrahimiand S) will by default match Unicode characters U+212A (Kelvin sign) and U+017F 325*22dc650dSSadaf Ebrahimi(long S) respectively, as well as their lower case ASCII counterparts. When 326*22dc650dSSadaf Ebrahimithis option is set, case equivalences are restricted such that no ASCII 327*22dc650dSSadaf Ebrahimicharacter matches a non-ASCII character, and vice versa. 328*22dc650dSSadaf Ebrahimi</P> 329*22dc650dSSadaf Ebrahimi<P> 330*22dc650dSSadaf Ebrahimi<b>-e</b> <i>pattern</i>, <b>--regex=</b><i>pattern</i>, <b>--regexp=</b><i>pattern</i> 331*22dc650dSSadaf EbrahimiSpecify a pattern to be matched. This option can be used multiple times in 332*22dc650dSSadaf Ebrahimiorder to specify several patterns. It can also be used as a way of specifying a 333*22dc650dSSadaf Ebrahimisingle pattern that starts with a hyphen. When <b>-e</b> is used, no argument 334*22dc650dSSadaf Ebrahimipattern is taken from the command line; all arguments are treated as file 335*22dc650dSSadaf Ebrahiminames. There is no limit to the number of patterns. They are applied to each 336*22dc650dSSadaf Ebrahimiline in the order in which they are defined. 337*22dc650dSSadaf Ebrahimi<br> 338*22dc650dSSadaf Ebrahimi<br> 339*22dc650dSSadaf EbrahimiIf <b>-f</b> is used with <b>-e</b>, the command line patterns are matched first, 340*22dc650dSSadaf Ebrahimifollowed by the patterns from the file(s), independent of the order in which 341*22dc650dSSadaf Ebrahimithese options are specified. 342*22dc650dSSadaf Ebrahimi</P> 343*22dc650dSSadaf Ebrahimi<P> 344*22dc650dSSadaf Ebrahimi<b>--exclude</b>=<i>pattern</i> 345*22dc650dSSadaf EbrahimiFiles (but not directories) whose names match the pattern are skipped without 346*22dc650dSSadaf Ebrahimibeing processed. This applies to all files, whether listed on the command line, 347*22dc650dSSadaf Ebrahimiobtained from <b>--file-list</b>, or by scanning a directory. The pattern is a 348*22dc650dSSadaf EbrahimiPCRE2 regular expression, and is matched against the final component of the 349*22dc650dSSadaf Ebrahimifile name, not the entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do 350*22dc650dSSadaf Ebrahiminot apply to this pattern. The option may be given any number of times in order 351*22dc650dSSadaf Ebrahimito specify multiple patterns. If a file name matches both an <b>--include</b> 352*22dc650dSSadaf Ebrahimiand an <b>--exclude</b> pattern, it is excluded. There is no short form for this 353*22dc650dSSadaf Ebrahimioption. 354*22dc650dSSadaf Ebrahimi</P> 355*22dc650dSSadaf Ebrahimi<P> 356*22dc650dSSadaf Ebrahimi<b>--exclude-from=</b><i>filename</i> 357*22dc650dSSadaf EbrahimiTreat each non-empty line of the file as the data for an <b>--exclude</b> 358*22dc650dSSadaf Ebrahimioption. What constitutes a newline when reading the file is the operating 359*22dc650dSSadaf Ebrahimisystem's default. The <b>--newline</b> option has no effect on this option. This 360*22dc650dSSadaf Ebrahimioption may be given more than once in order to specify a number of files to 361*22dc650dSSadaf Ebrahimiread. 362*22dc650dSSadaf Ebrahimi</P> 363*22dc650dSSadaf Ebrahimi<P> 364*22dc650dSSadaf Ebrahimi<b>--exclude-dir</b>=<i>pattern</i> 365*22dc650dSSadaf EbrahimiDirectories whose names match the pattern are skipped without being processed, 366*22dc650dSSadaf Ebrahimiwhatever the setting of the <b>--recursive</b> option. This applies to all 367*22dc650dSSadaf Ebrahimidirectories, whether listed on the command line, obtained from 368*22dc650dSSadaf Ebrahimi<b>--file-list</b>, or by scanning a parent directory. The pattern is a PCRE2 369*22dc650dSSadaf Ebrahimiregular expression, and is matched against the final component of the directory 370*22dc650dSSadaf Ebrahiminame, not the entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do not 371*22dc650dSSadaf Ebrahimiapply to this pattern. The option may be given any number of times in order to 372*22dc650dSSadaf Ebrahimispecify more than one pattern. If a directory matches both <b>--include-dir</b> 373*22dc650dSSadaf Ebrahimiand <b>--exclude-dir</b>, it is excluded. There is no short form for this 374*22dc650dSSadaf Ebrahimioption. 375*22dc650dSSadaf Ebrahimi</P> 376*22dc650dSSadaf Ebrahimi<P> 377*22dc650dSSadaf Ebrahimi<b>-F</b>, <b>--fixed-strings</b> 378*22dc650dSSadaf EbrahimiInterpret each data-matching pattern as a list of fixed strings, separated by 379*22dc650dSSadaf Ebrahiminewlines, instead of as a regular expression. What constitutes a newline for 380*22dc650dSSadaf Ebrahimithis purpose is controlled by the <b>--newline</b> option. The <b>-w</b> (match 381*22dc650dSSadaf Ebrahimias a word) and <b>-x</b> (match whole line) options can be used with <b>-F</b>. 382*22dc650dSSadaf EbrahimiThey apply to each of the fixed strings. A line is selected if any of the fixed 383*22dc650dSSadaf Ebrahimistrings are found in it (subject to <b>-w</b> or <b>-x</b>, if present). This 384*22dc650dSSadaf Ebrahimioption applies only to the patterns that are matched against the contents of 385*22dc650dSSadaf Ebrahimifiles; it does not apply to patterns specified by any of the <b>--include</b> or 386*22dc650dSSadaf Ebrahimi<b>--exclude</b> options. 387*22dc650dSSadaf Ebrahimi</P> 388*22dc650dSSadaf Ebrahimi<P> 389*22dc650dSSadaf Ebrahimi<b>-f</b> <i>filename</i>, <b>--file=</b><i>filename</i> 390*22dc650dSSadaf EbrahimiRead patterns from the file, one per line. As is the case with patterns on the 391*22dc650dSSadaf Ebrahimicommand line, no delimiters should be used. What constitutes a newline when 392*22dc650dSSadaf Ebrahimireading the file is the operating system's default interpretation of \n. The 393*22dc650dSSadaf Ebrahimi<b>--newline</b> option has no effect on this option. Trailing white space is 394*22dc650dSSadaf Ebrahimiremoved from each line, and blank lines are ignored. An empty file contains no 395*22dc650dSSadaf Ebrahimipatterns and therefore matches nothing. Patterns read from a file in this way 396*22dc650dSSadaf Ebrahimimay contain binary zeros, which are treated as ordinary data characters. 397*22dc650dSSadaf Ebrahimi<br> 398*22dc650dSSadaf Ebrahimi<br> 399*22dc650dSSadaf EbrahimiIf this option is given more than once, all the specified files are read. A 400*22dc650dSSadaf Ebrahimidata line is output if any of the patterns match it. A file name can be given 401*22dc650dSSadaf Ebrahimias "-" to refer to the standard input. When <b>-f</b> is used, patterns 402*22dc650dSSadaf Ebrahimispecified on the command line using <b>-e</b> may also be present; they are 403*22dc650dSSadaf Ebrahimimatched before the file's patterns. However, no pattern is taken from the 404*22dc650dSSadaf Ebrahimicommand line; all arguments are treated as the names of paths to be searched. 405*22dc650dSSadaf Ebrahimi</P> 406*22dc650dSSadaf Ebrahimi<P> 407*22dc650dSSadaf Ebrahimi<b>--file-list</b>=<i>filename</i> 408*22dc650dSSadaf EbrahimiRead a list of files and/or directories that are to be scanned from the given 409*22dc650dSSadaf Ebrahimifile, one per line. What constitutes a newline when reading the file is the 410*22dc650dSSadaf Ebrahimioperating system's default. Trailing white space is removed from each line, and 411*22dc650dSSadaf Ebrahimiblank lines are ignored. These paths are processed before any that are listed 412*22dc650dSSadaf Ebrahimion the command line. The file name can be given as "-" to refer to the standard 413*22dc650dSSadaf Ebrahimiinput. If <b>--file</b> and <b>--file-list</b> are both specified as "-", 414*22dc650dSSadaf Ebrahimipatterns are read first. This is useful only when the standard input is a 415*22dc650dSSadaf Ebrahimiterminal, from which further lines (the list of files) can be read after an 416*22dc650dSSadaf Ebrahimiend-of-file indication. If this option is given more than once, all the 417*22dc650dSSadaf Ebrahimispecified files are read. 418*22dc650dSSadaf Ebrahimi</P> 419*22dc650dSSadaf Ebrahimi<P> 420*22dc650dSSadaf Ebrahimi<b>--file-offsets</b> 421*22dc650dSSadaf EbrahimiInstead of showing lines or parts of lines that match, show each match as an 422*22dc650dSSadaf Ebrahimioffset from the start of the file and a length, separated by a comma. In this 423*22dc650dSSadaf Ebrahimimode, <b>--colour</b> has no effect, and no context is shown. That is, the 424*22dc650dSSadaf Ebrahimi<b>-A</b>, <b>-B</b>, and <b>-C</b> options are ignored. If there is more than one 425*22dc650dSSadaf Ebrahimimatch in a line, each of them is shown separately. This option is mutually 426*22dc650dSSadaf Ebrahimiexclusive with <b>--output</b>, <b>--line-offsets</b>, and <b>--only-matching</b>. 427*22dc650dSSadaf Ebrahimi</P> 428*22dc650dSSadaf Ebrahimi<P> 429*22dc650dSSadaf Ebrahimi<b>--group-separator</b>=<i>text</i> 430*22dc650dSSadaf EbrahimiOutput this text string instead of two hyphens between groups of lines when 431*22dc650dSSadaf Ebrahimi<b>-A</b>, <b>-B</b>, or <b>-C</b> is in use. See also <b>--no-group-separator</b>. 432*22dc650dSSadaf Ebrahimi</P> 433*22dc650dSSadaf Ebrahimi<P> 434*22dc650dSSadaf Ebrahimi<b>-H</b>, <b>--with-filename</b> 435*22dc650dSSadaf EbrahimiForce the inclusion of the file name at the start of output lines when 436*22dc650dSSadaf Ebrahimisearching a single file. The file name is not normally shown in this case. 437*22dc650dSSadaf EbrahimiBy default, for matching lines, the file name is followed by a colon; for 438*22dc650dSSadaf Ebrahimicontext lines, a hyphen separator is used. The <b>-Z</b> option can be used to 439*22dc650dSSadaf Ebrahimichange the terminator to a zero byte. If a line number is also being output, 440*22dc650dSSadaf Ebrahimiit follows the file name. When the <b>-M</b> option causes a pattern to match 441*22dc650dSSadaf Ebrahimimore than one line, only the first is preceded by the file name. This option 442*22dc650dSSadaf Ebrahimioverrides any previous <b>-h</b>, <b>-l</b>, or <b>-L</b> options. 443*22dc650dSSadaf Ebrahimi</P> 444*22dc650dSSadaf Ebrahimi<P> 445*22dc650dSSadaf Ebrahimi<b>-h</b>, <b>--no-filename</b> 446*22dc650dSSadaf EbrahimiSuppress the output file names when searching multiple files. File names are 447*22dc650dSSadaf Ebrahiminormally shown when multiple files are searched. By default, for matching 448*22dc650dSSadaf Ebrahimilines, the file name is followed by a colon; for context lines, a hyphen 449*22dc650dSSadaf Ebrahimiseparator is used. The <b>-Z</b> option can be used to change the terminator to 450*22dc650dSSadaf Ebrahimia zero byte. If a line number is also being output, it follows the file name. 451*22dc650dSSadaf EbrahimiThis option overrides any previous <b>-H</b>, <b>-L</b>, or <b>-l</b> options. 452*22dc650dSSadaf Ebrahimi</P> 453*22dc650dSSadaf Ebrahimi<P> 454*22dc650dSSadaf Ebrahimi<b>--heap-limit</b>=<i>number</i> 455*22dc650dSSadaf EbrahimiSee <b>--match-limit</b> below. 456*22dc650dSSadaf Ebrahimi</P> 457*22dc650dSSadaf Ebrahimi<P> 458*22dc650dSSadaf Ebrahimi<b>--help</b> 459*22dc650dSSadaf EbrahimiOutput a help message, giving brief details of the command options and file 460*22dc650dSSadaf Ebrahimitype support, and then exit. Anything else on the command line is 461*22dc650dSSadaf Ebrahimiignored. 462*22dc650dSSadaf Ebrahimi</P> 463*22dc650dSSadaf Ebrahimi<P> 464*22dc650dSSadaf Ebrahimi<b>-I</b> 465*22dc650dSSadaf EbrahimiIgnore binary files. This is equivalent to 466*22dc650dSSadaf Ebrahimi<b>--binary-files</b>=<i>without-match</i>. 467*22dc650dSSadaf Ebrahimi</P> 468*22dc650dSSadaf Ebrahimi<P> 469*22dc650dSSadaf Ebrahimi<b>-i</b>, <b>--ignore-case</b> 470*22dc650dSSadaf EbrahimiIgnore upper/lower case distinctions when pattern matching. This applies when 471*22dc650dSSadaf Ebrahimimatching path names for inclusion or exclusion as well as when matching lines 472*22dc650dSSadaf Ebrahimiin files. 473*22dc650dSSadaf Ebrahimi</P> 474*22dc650dSSadaf Ebrahimi<P> 475*22dc650dSSadaf Ebrahimi<b>--include</b>=<i>pattern</i> 476*22dc650dSSadaf EbrahimiIf any <b>--include</b> patterns are specified, the only files that are 477*22dc650dSSadaf Ebrahimiprocessed are those whose names match one of the patterns and do not match an 478*22dc650dSSadaf Ebrahimi<b>--exclude</b> pattern. This option does not affect directories, but it 479*22dc650dSSadaf Ebrahimiapplies to all files, whether listed on the command line, obtained from 480*22dc650dSSadaf Ebrahimi<b>--file-list</b>, or by scanning a directory. The pattern is a PCRE2 regular 481*22dc650dSSadaf Ebrahimiexpression, and is matched against the final component of the file name, not 482*22dc650dSSadaf Ebrahimithe entire path. The <b>-F</b>, <b>-w</b>, and <b>-x</b> options do not apply to 483*22dc650dSSadaf Ebrahimithis pattern. The option may be given any number of times. If a file name 484*22dc650dSSadaf Ebrahimimatches both an <b>--include</b> and an <b>--exclude</b> pattern, it is excluded. 485*22dc650dSSadaf EbrahimiThere is no short form for this option. 486*22dc650dSSadaf Ebrahimi</P> 487*22dc650dSSadaf Ebrahimi<P> 488*22dc650dSSadaf Ebrahimi<b>--include-from=</b><i>filename</i> 489*22dc650dSSadaf EbrahimiTreat each non-empty line of the file as the data for an <b>--include</b> 490*22dc650dSSadaf Ebrahimioption. What constitutes a newline for this purpose is the operating system's 491*22dc650dSSadaf Ebrahimidefault. The <b>--newline</b> option has no effect on this option. This option 492*22dc650dSSadaf Ebrahimimay be given any number of times; all the files are read. 493*22dc650dSSadaf Ebrahimi</P> 494*22dc650dSSadaf Ebrahimi<P> 495*22dc650dSSadaf Ebrahimi<b>--include-dir</b>=<i>pattern</i> 496*22dc650dSSadaf EbrahimiIf any <b>--include-dir</b> patterns are specified, the only directories that 497*22dc650dSSadaf Ebrahimiare processed are those whose names match one of the patterns and do not match 498*22dc650dSSadaf Ebrahimian <b>--exclude-dir</b> pattern. This applies to all directories, whether listed 499*22dc650dSSadaf Ebrahimion the command line, obtained from <b>--file-list</b>, or by scanning a parent 500*22dc650dSSadaf Ebrahimidirectory. The pattern is a PCRE2 regular expression, and is matched against 501*22dc650dSSadaf Ebrahimithe final component of the directory name, not the entire path. The <b>-F</b>, 502*22dc650dSSadaf Ebrahimi<b>-w</b>, and <b>-x</b> options do not apply to this pattern. The option may be 503*22dc650dSSadaf Ebrahimigiven any number of times. If a directory matches both <b>--include-dir</b> and 504*22dc650dSSadaf Ebrahimi<b>--exclude-dir</b>, it is excluded. There is no short form for this option. 505*22dc650dSSadaf Ebrahimi</P> 506*22dc650dSSadaf Ebrahimi<P> 507*22dc650dSSadaf Ebrahimi<b>-L</b>, <b>--files-without-match</b> 508*22dc650dSSadaf EbrahimiInstead of outputting lines from the files, just output the names of the files 509*22dc650dSSadaf Ebrahimithat do not contain any lines that would have been output. Each file name is 510*22dc650dSSadaf Ebrahimioutput once, on a separate line by default, but if the <b>-Z</b> option is set, 511*22dc650dSSadaf Ebrahimithey are separated by zero bytes instead of newlines. This option overrides any 512*22dc650dSSadaf Ebrahimiprevious <b>-H</b>, <b>-h</b>, or <b>-l</b> options. 513*22dc650dSSadaf Ebrahimi</P> 514*22dc650dSSadaf Ebrahimi<P> 515*22dc650dSSadaf Ebrahimi<b>-l</b>, <b>--files-with-matches</b> 516*22dc650dSSadaf EbrahimiInstead of outputting lines from the files, just output the names of the files 517*22dc650dSSadaf Ebrahimicontaining lines that would have been output. Each file name is output once, on 518*22dc650dSSadaf Ebrahimia separate line, but if the <b>-Z</b> option is set, they are separated by zero 519*22dc650dSSadaf Ebrahimibytes instead of newlines. Searching normally stops as soon as a matching line 520*22dc650dSSadaf Ebrahimiis found in a file. However, if the <b>-c</b> (count) option is also used, 521*22dc650dSSadaf Ebrahimimatching continues in order to obtain the correct count, and those files that 522*22dc650dSSadaf Ebrahimihave at least one match are listed along with their counts. Using this option 523*22dc650dSSadaf Ebrahimiwith <b>-c</b> is a way of suppressing the listing of files with no matches that 524*22dc650dSSadaf Ebrahimioccurs with <b>-c</b> on its own. This option overrides any previous <b>-H</b>, 525*22dc650dSSadaf Ebrahimi<b>-h</b>, or <b>-L</b> options. 526*22dc650dSSadaf Ebrahimi</P> 527*22dc650dSSadaf Ebrahimi<P> 528*22dc650dSSadaf Ebrahimi<b>--label</b>=<i>name</i> 529*22dc650dSSadaf EbrahimiThis option supplies a name to be used for the standard input when file names 530*22dc650dSSadaf Ebrahimiare being output. If not supplied, "(standard input)" is used. There is no 531*22dc650dSSadaf Ebrahimishort form for this option. 532*22dc650dSSadaf Ebrahimi</P> 533*22dc650dSSadaf Ebrahimi<P> 534*22dc650dSSadaf Ebrahimi<b>--line-buffered</b> 535*22dc650dSSadaf EbrahimiWhen this option is given, non-compressed input is read and processed line by 536*22dc650dSSadaf Ebrahimiline, and the output is flushed after each write. By default, input is read in 537*22dc650dSSadaf Ebrahimilarge chunks, unless <b>pcre2grep</b> can determine that it is reading from a 538*22dc650dSSadaf Ebrahimiterminal, which is currently possible only in Unix-like environments or 539*22dc650dSSadaf EbrahimiWindows. Output to terminal is normally automatically flushed by the operating 540*22dc650dSSadaf Ebrahimisystem. This option can be useful when the input or output is attached to a 541*22dc650dSSadaf Ebrahimipipe and you do not want <b>pcre2grep</b> to buffer up large amounts of data. 542*22dc650dSSadaf EbrahimiHowever, its use will affect performance, and the <b>-M</b> (multiline) option 543*22dc650dSSadaf Ebrahimiceases to work. When input is from a compressed .gz or .bz2 file, 544*22dc650dSSadaf Ebrahimi<b>--line-buffered</b> is ignored. 545*22dc650dSSadaf Ebrahimi</P> 546*22dc650dSSadaf Ebrahimi<P> 547*22dc650dSSadaf Ebrahimi<b>--line-offsets</b> 548*22dc650dSSadaf EbrahimiInstead of showing lines or parts of lines that match, show each match as a 549*22dc650dSSadaf Ebrahimiline number, the offset from the start of the line, and a length. The line 550*22dc650dSSadaf Ebrahiminumber is terminated by a colon (as usual; see the <b>-n</b> option), and the 551*22dc650dSSadaf Ebrahimioffset and length are separated by a comma. In this mode, <b>--colour</b> has no 552*22dc650dSSadaf Ebrahimieffect, and no context is shown. That is, the <b>-A</b>, <b>-B</b>, and <b>-C</b> 553*22dc650dSSadaf Ebrahimioptions are ignored. If there is more than one match in a line, each of them is 554*22dc650dSSadaf Ebrahimishown separately. This option is mutually exclusive with <b>--output</b>, 555*22dc650dSSadaf Ebrahimi<b>--file-offsets</b>, and <b>--only-matching</b>. 556*22dc650dSSadaf Ebrahimi</P> 557*22dc650dSSadaf Ebrahimi<P> 558*22dc650dSSadaf Ebrahimi<b>--locale</b>=<i>locale-name</i> 559*22dc650dSSadaf EbrahimiThis option specifies a locale to be used for pattern matching. It overrides 560*22dc650dSSadaf Ebrahimithe value in the <b>LC_ALL</b> or <b>LC_CTYPE</b> environment variables. If no 561*22dc650dSSadaf Ebrahimilocale is specified, the PCRE2 library's default (usually the "C" locale) is 562*22dc650dSSadaf Ebrahimiused. There is no short form for this option. 563*22dc650dSSadaf Ebrahimi</P> 564*22dc650dSSadaf Ebrahimi<P> 565*22dc650dSSadaf Ebrahimi<b>-M</b>, <b>--multiline</b> 566*22dc650dSSadaf EbrahimiAllow patterns to match more than one line. When this option is set, the PCRE2 567*22dc650dSSadaf Ebrahimilibrary is called in "multiline" mode, and a match is allowed to continue past 568*22dc650dSSadaf Ebrahimithe end of the initial line and onto one or more subsequent lines. 569*22dc650dSSadaf Ebrahimi<br> 570*22dc650dSSadaf Ebrahimi<br> 571*22dc650dSSadaf EbrahimiPatterns used with <b>-M</b> may usefully contain literal newline characters and 572*22dc650dSSadaf Ebrahimiinternal occurrences of ^ and $ characters, because in multiline mode these can 573*22dc650dSSadaf Ebrahimimatch at internal newlines. Because <b>pcre2grep</b> is scanning multiple lines, 574*22dc650dSSadaf Ebrahimithe \Z and \z assertions match only at the end of the last line in the file. 575*22dc650dSSadaf EbrahimiThe \A assertion matches at the start of the first line of a match. This can 576*22dc650dSSadaf Ebrahimibe any line in the file; it is not anchored to the first line. 577*22dc650dSSadaf Ebrahimi<br> 578*22dc650dSSadaf Ebrahimi<br> 579*22dc650dSSadaf EbrahimiThe output for a successful match may consist of more than one line. The first 580*22dc650dSSadaf Ebrahimiline is the line in which the match started, and the last line is the line in 581*22dc650dSSadaf Ebrahimiwhich the match ended. If the matched string ends with a newline sequence, the 582*22dc650dSSadaf Ebrahimioutput ends at the end of that line. If <b>-v</b> is set, none of the lines in a 583*22dc650dSSadaf Ebrahimimulti-line match are output. Once a match has been handled, scanning restarts 584*22dc650dSSadaf Ebrahimiat the beginning of the line after the one in which the match ended. 585*22dc650dSSadaf Ebrahimi<br> 586*22dc650dSSadaf Ebrahimi<br> 587*22dc650dSSadaf EbrahimiThe newline sequence that separates multiple lines must be matched as part of 588*22dc650dSSadaf Ebrahimithe pattern. For example, to find the phrase "regular expression" in a file 589*22dc650dSSadaf Ebrahimiwhere "regular" might be at the end of a line and "expression" at the start of 590*22dc650dSSadaf Ebrahimithe next line, you could use this command: 591*22dc650dSSadaf Ebrahimi<pre> 592*22dc650dSSadaf Ebrahimi pcre2grep -M 'regular\s+expression' <file> 593*22dc650dSSadaf Ebrahimi</pre> 594*22dc650dSSadaf EbrahimiThe \s escape sequence matches any white space character, including newlines, 595*22dc650dSSadaf Ebrahimiand is followed by + so as to match trailing white space on the first line as 596*22dc650dSSadaf Ebrahimiwell as possibly handling a two-character newline sequence. 597*22dc650dSSadaf Ebrahimi<br> 598*22dc650dSSadaf Ebrahimi<br> 599*22dc650dSSadaf EbrahimiThere is a limit to the number of lines that can be matched, imposed by the way 600*22dc650dSSadaf Ebrahimithat <b>pcre2grep</b> buffers the input file as it scans it. With a sufficiently 601*22dc650dSSadaf Ebrahimilarge processing buffer, this should not be a problem. 602*22dc650dSSadaf Ebrahimi<br> 603*22dc650dSSadaf Ebrahimi<br> 604*22dc650dSSadaf EbrahimiThe <b>-M</b> option does not work when input is read line by line (see 605*22dc650dSSadaf Ebrahimi<b>--line-buffered</b>.) 606*22dc650dSSadaf Ebrahimi</P> 607*22dc650dSSadaf Ebrahimi<P> 608*22dc650dSSadaf Ebrahimi<b>-m</b> <i>number</i>, <b>--max-count</b>=<i>number</i> 609*22dc650dSSadaf EbrahimiStop processing after finding <i>number</i> matching lines, or non-matching 610*22dc650dSSadaf Ebrahimilines if <b>-v</b> is also set. Any trailing context lines are output after the 611*22dc650dSSadaf Ebrahimifinal match. In multiline mode, each multiline match counts as just one line 612*22dc650dSSadaf Ebrahimifor this purpose. If this limit is reached when reading the standard input from 613*22dc650dSSadaf Ebrahimia regular file, the file is left positioned just after the last matching line. 614*22dc650dSSadaf EbrahimiIf <b>-c</b> is also set, the count that is output is never greater than 615*22dc650dSSadaf Ebrahimi<i>number</i>. This option has no effect if used with <b>-L</b>, <b>-l</b>, or 616*22dc650dSSadaf Ebrahimi<b>-q</b>, or when just checking for a match in a binary file. 617*22dc650dSSadaf Ebrahimi</P> 618*22dc650dSSadaf Ebrahimi<P> 619*22dc650dSSadaf Ebrahimi<b>--match-limit</b>=<i>number</i> 620*22dc650dSSadaf EbrahimiProcessing some regular expression patterns may take a very long time to search 621*22dc650dSSadaf Ebrahimifor all possible matching strings. Others may require a very large amount of 622*22dc650dSSadaf Ebrahimimemory. There are three options that set resource limits for matching. 623*22dc650dSSadaf Ebrahimi<br> 624*22dc650dSSadaf Ebrahimi<br> 625*22dc650dSSadaf EbrahimiThe <b>--match-limit</b> option provides a means of limiting computing resource 626*22dc650dSSadaf Ebrahimiusage when processing patterns that are not going to match, but which have a 627*22dc650dSSadaf Ebrahimivery large number of possibilities in their search trees. The classic example 628*22dc650dSSadaf Ebrahimiis a pattern that uses nested unlimited repeats. Internally, PCRE2 has a 629*22dc650dSSadaf Ebrahimicounter that is incremented each time around its main processing loop. If the 630*22dc650dSSadaf Ebrahimivalue set by <b>--match-limit</b> is reached, an error occurs. 631*22dc650dSSadaf Ebrahimi<br> 632*22dc650dSSadaf Ebrahimi<br> 633*22dc650dSSadaf EbrahimiThe <b>--heap-limit</b> option specifies, as a number of kibibytes (units of 634*22dc650dSSadaf Ebrahimi1024 bytes), the maximum amount of heap memory that may be used for matching. 635*22dc650dSSadaf Ebrahimi<br> 636*22dc650dSSadaf Ebrahimi<br> 637*22dc650dSSadaf EbrahimiThe <b>--depth-limit</b> option limits the depth of nested backtracking points, 638*22dc650dSSadaf Ebrahimiwhich indirectly limits the amount of memory that is used. The amount of memory 639*22dc650dSSadaf Ebrahimineeded for each backtracking point depends on the number of capturing 640*22dc650dSSadaf Ebrahimiparentheses in the pattern, so the amount of memory that is used before this 641*22dc650dSSadaf Ebrahimilimit acts varies from pattern to pattern. This limit is of use only if it is 642*22dc650dSSadaf Ebrahimiset smaller than <b>--match-limit</b>. 643*22dc650dSSadaf Ebrahimi<br> 644*22dc650dSSadaf Ebrahimi<br> 645*22dc650dSSadaf EbrahimiThere are no short forms for these options. The default limits can be set 646*22dc650dSSadaf Ebrahimiwhen the PCRE2 library is compiled; if they are not specified, the defaults 647*22dc650dSSadaf Ebrahimiare very large and so effectively unlimited. 648*22dc650dSSadaf Ebrahimi</P> 649*22dc650dSSadaf Ebrahimi<P> 650*22dc650dSSadaf Ebrahimi<b>--max-buffer-size</b>=<i>number</i> 651*22dc650dSSadaf EbrahimiThis limits the expansion of the processing buffer, whose initial size can be 652*22dc650dSSadaf Ebrahimiset by <b>--buffer-size</b>. The maximum buffer size is silently forced to be no 653*22dc650dSSadaf Ebrahimismaller than the starting buffer size. 654*22dc650dSSadaf Ebrahimi</P> 655*22dc650dSSadaf Ebrahimi<P> 656*22dc650dSSadaf Ebrahimi<b>-N</b> <i>newline-type</i>, <b>--newline</b>=<i>newline-type</i> 657*22dc650dSSadaf EbrahimiSix different conventions for indicating the ends of lines in scanned files are 658*22dc650dSSadaf Ebrahimisupported. For example: 659*22dc650dSSadaf Ebrahimi<pre> 660*22dc650dSSadaf Ebrahimi pcre2grep -N CRLF 'some pattern' <file> 661*22dc650dSSadaf Ebrahimi</pre> 662*22dc650dSSadaf EbrahimiThe newline type may be specified in upper, lower, or mixed case. If the 663*22dc650dSSadaf Ebrahiminewline type is NUL, lines are separated by binary zero characters. The other 664*22dc650dSSadaf Ebrahimitypes are the single-character sequences CR (carriage return) and LF 665*22dc650dSSadaf Ebrahimi(linefeed), the two-character sequence CRLF, an "anycrlf" type, which 666*22dc650dSSadaf Ebrahimirecognizes any of the preceding three types, and an "any" type, for which any 667*22dc650dSSadaf EbrahimiUnicode line ending sequence is assumed to end a line. The Unicode sequences 668*22dc650dSSadaf Ebrahimiare the three just mentioned, plus VT (vertical tab, U+000B), FF (form feed, 669*22dc650dSSadaf EbrahimiU+000C), NEL (next line, U+0085), LS (line separator, U+2028), and PS 670*22dc650dSSadaf Ebrahimi(paragraph separator, U+2029). 671*22dc650dSSadaf Ebrahimi<br> 672*22dc650dSSadaf Ebrahimi<br> 673*22dc650dSSadaf EbrahimiWhen the PCRE2 library is built, a default line-ending sequence is specified. 674*22dc650dSSadaf EbrahimiThis is normally the standard sequence for the operating system. Unless 675*22dc650dSSadaf Ebrahimiotherwise specified by this option, <b>pcre2grep</b> uses the library's default. 676*22dc650dSSadaf Ebrahimi<br> 677*22dc650dSSadaf Ebrahimi<br> 678*22dc650dSSadaf EbrahimiThis option makes it possible to use <b>pcre2grep</b> to scan files that have 679*22dc650dSSadaf Ebrahimicome from other environments without having to modify their line endings. If 680*22dc650dSSadaf Ebrahimithe data that is being scanned does not agree with the convention set by this 681*22dc650dSSadaf Ebrahimioption, <b>pcre2grep</b> may behave in strange ways. Note that this option does 682*22dc650dSSadaf Ebrahiminot apply to files specified by the <b>-f</b>, <b>--exclude-from</b>, or 683*22dc650dSSadaf Ebrahimi<b>--include-from</b> options, which are expected to use the operating system's 684*22dc650dSSadaf Ebrahimistandard newline sequence. 685*22dc650dSSadaf Ebrahimi</P> 686*22dc650dSSadaf Ebrahimi<P> 687*22dc650dSSadaf Ebrahimi<b>-n</b>, <b>--line-number</b> 688*22dc650dSSadaf EbrahimiPrecede each output line by its line number in the file, followed by a colon 689*22dc650dSSadaf Ebrahimifor matching lines or a hyphen for context lines. If the file name is also 690*22dc650dSSadaf Ebrahimibeing output, it precedes the line number. When the <b>-M</b> option causes a 691*22dc650dSSadaf Ebrahimipattern to match more than one line, only the first is preceded by its line 692*22dc650dSSadaf Ebrahiminumber. This option is forced if <b>--line-offsets</b> is used. 693*22dc650dSSadaf Ebrahimi</P> 694*22dc650dSSadaf Ebrahimi<P> 695*22dc650dSSadaf Ebrahimi<b>--no-group-separator</b> 696*22dc650dSSadaf EbrahimiDo not output a separator between groups of lines when <b>-A</b>, <b>-B</b>, or 697*22dc650dSSadaf Ebrahimi<b>-C</b> is in use. The default is to output a line containing two hyphens. See 698*22dc650dSSadaf Ebrahimialso <b>--group-separator</b>. 699*22dc650dSSadaf Ebrahimi</P> 700*22dc650dSSadaf Ebrahimi<P> 701*22dc650dSSadaf Ebrahimi<b>--no-jit</b> 702*22dc650dSSadaf EbrahimiIf the PCRE2 library is built with support for just-in-time compiling (which 703*22dc650dSSadaf Ebrahimispeeds up matching), <b>pcre2grep</b> automatically makes use of this, unless it 704*22dc650dSSadaf Ebrahimiwas explicitly disabled at build time. This option can be used to disable the 705*22dc650dSSadaf Ebrahimiuse of JIT at run time. It is provided for testing and working around problems. 706*22dc650dSSadaf EbrahimiIt should never be needed in normal use. 707*22dc650dSSadaf Ebrahimi</P> 708*22dc650dSSadaf Ebrahimi<P> 709*22dc650dSSadaf Ebrahimi<b>-O</b> <i>text</i>, <b>--output</b>=<i>text</i> 710*22dc650dSSadaf EbrahimiWhen there is a match, instead of outputting the line that matched, output just 711*22dc650dSSadaf Ebrahimithe text specified in this option, followed by an operating-system standard 712*22dc650dSSadaf Ebrahiminewline. In this mode, <b>--colour</b> has no effect, and no context is shown. 713*22dc650dSSadaf EbrahimiThat is, the <b>-A</b>, <b>-B</b>, and <b>-C</b> options are ignored. The 714*22dc650dSSadaf Ebrahimi<b>--newline</b> option has no effect on this option, which is mutually 715*22dc650dSSadaf Ebrahimiexclusive with <b>--only-matching</b>, <b>--file-offsets</b>, and 716*22dc650dSSadaf Ebrahimi<b>--line-offsets</b>. However, like <b>--only-matching</b>, if there is more 717*22dc650dSSadaf Ebrahimithan one match in a line, each of them causes a line of output. 718*22dc650dSSadaf Ebrahimi<br> 719*22dc650dSSadaf Ebrahimi<br> 720*22dc650dSSadaf EbrahimiEscape sequences starting with a dollar character may be used to insert the 721*22dc650dSSadaf Ebrahimicontents of the matched part of the line and/or captured substrings into the 722*22dc650dSSadaf Ebrahimitext. 723*22dc650dSSadaf Ebrahimi<br> 724*22dc650dSSadaf Ebrahimi<br> 725*22dc650dSSadaf Ebrahimi$<digits> or ${<digits>} is replaced by the captured substring of the given 726*22dc650dSSadaf Ebrahimidecimal number; zero substitutes the whole match. If the number is greater than 727*22dc650dSSadaf Ebrahimithe number of capturing substrings, or if the capture is unset, the replacement 728*22dc650dSSadaf Ebrahimiis empty. 729*22dc650dSSadaf Ebrahimi<br> 730*22dc650dSSadaf Ebrahimi<br> 731*22dc650dSSadaf Ebrahimi$a is replaced by bell; $b by backspace; $e by escape; $f by form feed; $n by 732*22dc650dSSadaf Ebrahiminewline; $r by carriage return; $t by tab; $v by vertical tab. 733*22dc650dSSadaf Ebrahimi<br> 734*22dc650dSSadaf Ebrahimi<br> 735*22dc650dSSadaf Ebrahimi$o<digits> or $o{<digits>} is replaced by the character whose code point is the 736*22dc650dSSadaf Ebrahimigiven octal number. In the first form, up to three octal digits are processed. 737*22dc650dSSadaf EbrahimiWhen more digits are needed in Unicode mode to specify a wide character, the 738*22dc650dSSadaf Ebrahimisecond form must be used. 739*22dc650dSSadaf Ebrahimi<br> 740*22dc650dSSadaf Ebrahimi<br> 741*22dc650dSSadaf Ebrahimi$x<digits> or $x{<digits>} is replaced by the character represented by the 742*22dc650dSSadaf Ebrahimigiven hexadecimal number. In the first form, up to two hexadecimal digits are 743*22dc650dSSadaf Ebrahimiprocessed. When more digits are needed in Unicode mode to specify a wide 744*22dc650dSSadaf Ebrahimicharacter, the second form must be used. 745*22dc650dSSadaf Ebrahimi<br> 746*22dc650dSSadaf Ebrahimi<br> 747*22dc650dSSadaf EbrahimiAny other character is substituted by itself. In particular, $$ is replaced by 748*22dc650dSSadaf Ebrahimia single dollar. 749*22dc650dSSadaf Ebrahimi</P> 750*22dc650dSSadaf Ebrahimi<P> 751*22dc650dSSadaf Ebrahimi<b>-o</b>, <b>--only-matching</b> 752*22dc650dSSadaf EbrahimiShow only the part of the line that matched a pattern instead of the whole 753*22dc650dSSadaf Ebrahimiline. In this mode, no context is shown. That is, the <b>-A</b>, <b>-B</b>, and 754*22dc650dSSadaf Ebrahimi<b>-C</b> options are ignored. If there is more than one match in a line, each 755*22dc650dSSadaf Ebrahimiof them is shown separately, on a separate line of output. If <b>-o</b> is 756*22dc650dSSadaf Ebrahimicombined with <b>-v</b> (invert the sense of the match to find non-matching 757*22dc650dSSadaf Ebrahimilines), no output is generated, but the return code is set appropriately. If 758*22dc650dSSadaf Ebrahimithe matched portion of the line is empty, nothing is output unless the file 759*22dc650dSSadaf Ebrahiminame or line number are being printed, in which case they are shown on an 760*22dc650dSSadaf Ebrahimiotherwise empty line. This option is mutually exclusive with <b>--output</b>, 761*22dc650dSSadaf Ebrahimi<b>--file-offsets</b> and <b>--line-offsets</b>. 762*22dc650dSSadaf Ebrahimi</P> 763*22dc650dSSadaf Ebrahimi<P> 764*22dc650dSSadaf Ebrahimi<b>-o</b><i>number</i>, <b>--only-matching</b>=<i>number</i> 765*22dc650dSSadaf EbrahimiShow only the part of the line that matched the capturing parentheses of the 766*22dc650dSSadaf Ebrahimigiven number. Up to 50 capturing parentheses are supported by default. This 767*22dc650dSSadaf Ebrahimilimit can be changed via the <b>--om-capture</b> option. A pattern may contain 768*22dc650dSSadaf Ebrahimiany number of capturing parentheses, but only those whose number is within the 769*22dc650dSSadaf Ebrahimilimit can be accessed by <b>-o</b>. An error occurs if the number specified by 770*22dc650dSSadaf Ebrahimi<b>-o</b> is greater than the limit. 771*22dc650dSSadaf Ebrahimi<br> 772*22dc650dSSadaf Ebrahimi<br> 773*22dc650dSSadaf Ebrahimi-o0 is the same as <b>-o</b> without a number. Because these options can be 774*22dc650dSSadaf Ebrahimigiven without an argument (see above), if an argument is present, it must be 775*22dc650dSSadaf Ebrahimigiven in the same shell item, for example, -o3 or --only-matching=2. The 776*22dc650dSSadaf Ebrahimicomments given for the non-argument case above also apply to this option. If 777*22dc650dSSadaf Ebrahimithe specified capturing parentheses do not exist in the pattern, or were not 778*22dc650dSSadaf Ebrahimiset in the match, nothing is output unless the file name or line number are 779*22dc650dSSadaf Ebrahimibeing output. 780*22dc650dSSadaf Ebrahimi<br> 781*22dc650dSSadaf Ebrahimi<br> 782*22dc650dSSadaf EbrahimiIf this option is given multiple times, multiple substrings are output for each 783*22dc650dSSadaf Ebrahimimatch, in the order the options are given, and all on one line. For example, 784*22dc650dSSadaf Ebrahimi-o3 -o1 -o3 causes the substrings matched by capturing parentheses 3 and 1 and 785*22dc650dSSadaf Ebrahimithen 3 again to be output. By default, there is no separator (but see the next 786*22dc650dSSadaf Ebrahimibut one option). 787*22dc650dSSadaf Ebrahimi</P> 788*22dc650dSSadaf Ebrahimi<P> 789*22dc650dSSadaf Ebrahimi<b>--om-capture</b>=<i>number</i> 790*22dc650dSSadaf EbrahimiSet the number of capturing parentheses that can be accessed by <b>-o</b>. The 791*22dc650dSSadaf Ebrahimidefault is 50. 792*22dc650dSSadaf Ebrahimi</P> 793*22dc650dSSadaf Ebrahimi<P> 794*22dc650dSSadaf Ebrahimi<b>--om-separator</b>=<i>text</i> 795*22dc650dSSadaf EbrahimiSpecify a separating string for multiple occurrences of <b>-o</b>. The default 796*22dc650dSSadaf Ebrahimiis an empty string. Separating strings are never coloured. 797*22dc650dSSadaf Ebrahimi</P> 798*22dc650dSSadaf Ebrahimi<P> 799*22dc650dSSadaf Ebrahimi<b>-P</b>, <b>--no-ucp</b> 800*22dc650dSSadaf EbrahimiStarting from release 10.43, when UTF/Unicode mode is specified with <b>-u</b> 801*22dc650dSSadaf Ebrahimior <b>-U</b>, the PCRE2_UCP option is used by default. This means that the 802*22dc650dSSadaf EbrahimiPOSIX classes in patterns match more than just ASCII characters. For example, 803*22dc650dSSadaf Ebrahimi[:digit:] matches any Unicode decimal digit. The <b>--no-ucp</b> option 804*22dc650dSSadaf Ebrahimisuppresses PCRE2_UCP, thus restricting the POSIX classes to ASCII characters, 805*22dc650dSSadaf Ebrahimias was the case in earlier releases. Note that there are now more fine-grained 806*22dc650dSSadaf Ebrahimioption settings within patterns that affect individual classes. For example, 807*22dc650dSSadaf Ebrahimiwhen in UCP mode, the sequence (?aP) restricts [:word:] to ASCII letters, while 808*22dc650dSSadaf Ebrahimiallowing \w to match Unicode letters and digits. 809*22dc650dSSadaf Ebrahimi</P> 810*22dc650dSSadaf Ebrahimi<P> 811*22dc650dSSadaf Ebrahimi<b>-q</b>, <b>--quiet</b> 812*22dc650dSSadaf EbrahimiWork quietly, that is, display nothing except error messages. The exit 813*22dc650dSSadaf Ebrahimistatus indicates whether or not any matches were found. 814*22dc650dSSadaf Ebrahimi</P> 815*22dc650dSSadaf Ebrahimi<P> 816*22dc650dSSadaf Ebrahimi<b>-r</b>, <b>--recursive</b> 817*22dc650dSSadaf EbrahimiIf any given path is a directory, recursively scan the files it contains, 818*22dc650dSSadaf Ebrahimitaking note of any <b>--include</b> and <b>--exclude</b> settings. By default, a 819*22dc650dSSadaf Ebrahimidirectory is read as a normal file; in some operating systems this gives an 820*22dc650dSSadaf Ebrahimiimmediate end-of-file. This option is a shorthand for setting the <b>-d</b> 821*22dc650dSSadaf Ebrahimioption to "recurse". 822*22dc650dSSadaf Ebrahimi</P> 823*22dc650dSSadaf Ebrahimi<P> 824*22dc650dSSadaf Ebrahimi<b>--recursion-limit</b>=<i>number</i> 825*22dc650dSSadaf EbrahimiThis is an obsolete synonym for <b>--depth-limit</b>. See <b>--match-limit</b> 826*22dc650dSSadaf Ebrahimiabove for details. 827*22dc650dSSadaf Ebrahimi</P> 828*22dc650dSSadaf Ebrahimi<P> 829*22dc650dSSadaf Ebrahimi<b>-s</b>, <b>--no-messages</b> 830*22dc650dSSadaf EbrahimiSuppress error messages about non-existent or unreadable files. Such files are 831*22dc650dSSadaf Ebrahimiquietly skipped. However, the return code is still 2, even if matches were 832*22dc650dSSadaf Ebrahimifound in other files. 833*22dc650dSSadaf Ebrahimi</P> 834*22dc650dSSadaf Ebrahimi<P> 835*22dc650dSSadaf Ebrahimi<b>-t</b>, <b>--total-count</b> 836*22dc650dSSadaf EbrahimiThis option is useful when scanning more than one file. If used on its own, 837*22dc650dSSadaf Ebrahimi<b>-t</b> suppresses all output except for a grand total number of matching 838*22dc650dSSadaf Ebrahimilines (or non-matching lines if <b>-v</b> is used) in all the files. If <b>-t</b> 839*22dc650dSSadaf Ebrahimiis used with <b>-c</b>, a grand total is output except when the previous output 840*22dc650dSSadaf Ebrahimiis just one line. In other words, it is not output when just one file's count 841*22dc650dSSadaf Ebrahimiis listed. If file names are being output, the grand total is preceded by 842*22dc650dSSadaf Ebrahimi"TOTAL:". Otherwise, it appears as just another number. The <b>-t</b> option is 843*22dc650dSSadaf Ebrahimiignored when used with <b>-L</b> (list files without matches), because the grand 844*22dc650dSSadaf Ebrahimitotal would always be zero. 845*22dc650dSSadaf Ebrahimi</P> 846*22dc650dSSadaf Ebrahimi<P> 847*22dc650dSSadaf Ebrahimi<b>-u</b>, <b>--utf</b> 848*22dc650dSSadaf EbrahimiOperate in UTF/Unicode mode. This option is available only if PCRE2 has been 849*22dc650dSSadaf Ebrahimicompiled with UTF-8 support. All patterns (including those for any 850*22dc650dSSadaf Ebrahimi<b>--exclude</b> and <b>--include</b> options) and all lines that are scanned 851*22dc650dSSadaf Ebrahimimust be valid strings of UTF-8 characters. If an invalid UTF-8 string is 852*22dc650dSSadaf Ebrahimiencountered, an error occurs. 853*22dc650dSSadaf Ebrahimi</P> 854*22dc650dSSadaf Ebrahimi<P> 855*22dc650dSSadaf Ebrahimi<b>-U</b>, <b>--utf-allow-invalid</b> 856*22dc650dSSadaf EbrahimiAs <b>--utf</b>, but in addition subject lines may contain invalid UTF-8 code 857*22dc650dSSadaf Ebrahimiunit sequences. These can never form part of any pattern match. Patterns 858*22dc650dSSadaf Ebrahimithemselves, however, must still be valid UTF-8 strings. This facility allows 859*22dc650dSSadaf Ebrahimivalid UTF-8 strings to be sought within arbitrary byte sequences in executable 860*22dc650dSSadaf Ebrahimior other binary files. For more details about matching in non-valid UTF-8 861*22dc650dSSadaf Ebrahimistrings, see the 862*22dc650dSSadaf Ebrahimi<a href="pcre2unicode.html"><b>pcre2unicode</b>(3)</a> 863*22dc650dSSadaf Ebrahimidocumentation. 864*22dc650dSSadaf Ebrahimi</P> 865*22dc650dSSadaf Ebrahimi<P> 866*22dc650dSSadaf Ebrahimi<b>-V</b>, <b>--version</b> 867*22dc650dSSadaf EbrahimiWrite the version numbers of <b>pcre2grep</b> and the PCRE2 library to the 868*22dc650dSSadaf Ebrahimistandard output and then exit. Anything else on the command line is 869*22dc650dSSadaf Ebrahimiignored. 870*22dc650dSSadaf Ebrahimi</P> 871*22dc650dSSadaf Ebrahimi<P> 872*22dc650dSSadaf Ebrahimi<b>-v</b>, <b>--invert-match</b> 873*22dc650dSSadaf EbrahimiInvert the sense of the match, so that lines which do <i>not</i> match any of 874*22dc650dSSadaf Ebrahimithe patterns are the ones that are found. When this option is set, options such 875*22dc650dSSadaf Ebrahimias <b>--only-matching</b> and <b>--output</b>, which specify parts of a match 876*22dc650dSSadaf Ebrahimithat are to be output, are ignored. 877*22dc650dSSadaf Ebrahimi</P> 878*22dc650dSSadaf Ebrahimi<P> 879*22dc650dSSadaf Ebrahimi<b>-w</b>, <b>--word-regex</b>, <b>--word-regexp</b> 880*22dc650dSSadaf EbrahimiForce the patterns only to match "words". That is, there must be a word 881*22dc650dSSadaf Ebrahimiboundary at the start and end of each matched string. This is equivalent to 882*22dc650dSSadaf Ebrahimihaving "\b(?:" at the start of each pattern, and ")\b" at the end. This 883*22dc650dSSadaf Ebrahimioption applies only to the patterns that are matched against the contents of 884*22dc650dSSadaf Ebrahimifiles; it does not apply to patterns specified by any of the <b>--include</b> or 885*22dc650dSSadaf Ebrahimi<b>--exclude</b> options. 886*22dc650dSSadaf Ebrahimi</P> 887*22dc650dSSadaf Ebrahimi<P> 888*22dc650dSSadaf Ebrahimi<b>-x</b>, <b>--line-regex</b>, <b>--line-regexp</b> 889*22dc650dSSadaf EbrahimiForce the patterns to start matching only at the beginnings of lines, and in 890*22dc650dSSadaf Ebrahimiaddition, require them to match entire lines. In multiline mode the match may 891*22dc650dSSadaf Ebrahimibe more than one line. This is equivalent to having "^(?:" at the start of each 892*22dc650dSSadaf Ebrahimipattern and ")$" at the end. This option applies only to the patterns that are 893*22dc650dSSadaf Ebrahimimatched against the contents of files; it does not apply to patterns specified 894*22dc650dSSadaf Ebrahimiby any of the <b>--include</b> or <b>--exclude</b> options. 895*22dc650dSSadaf Ebrahimi</P> 896*22dc650dSSadaf Ebrahimi<P> 897*22dc650dSSadaf Ebrahimi<b>-Z</b>, <b>--null</b> 898*22dc650dSSadaf EbrahimiTerminate files names in the regular output with a zero byte (the NUL 899*22dc650dSSadaf Ebrahimicharacter) instead of what would normally appear. This is useful when file 900*22dc650dSSadaf Ebrahiminames contain unusual characters such as colons, hyphens, or even newlines. The 901*22dc650dSSadaf Ebrahimioption does not apply to file names in error messages. 902*22dc650dSSadaf Ebrahimi</P> 903*22dc650dSSadaf Ebrahimi<br><a name="SEC7" href="#TOC1">ENVIRONMENT VARIABLES</a><br> 904*22dc650dSSadaf Ebrahimi<P> 905*22dc650dSSadaf EbrahimiThe environment variables <b>LC_ALL</b> and <b>LC_CTYPE</b> are examined, in that 906*22dc650dSSadaf Ebrahimiorder, for a locale. The first one that is set is used. This can be overridden 907*22dc650dSSadaf Ebrahimiby the <b>--locale</b> option. If no locale is set, the PCRE2 library's default 908*22dc650dSSadaf Ebrahimi(usually the "C" locale) is used. 909*22dc650dSSadaf Ebrahimi</P> 910*22dc650dSSadaf Ebrahimi<br><a name="SEC8" href="#TOC1">NEWLINES</a><br> 911*22dc650dSSadaf Ebrahimi<P> 912*22dc650dSSadaf EbrahimiThe <b>-N</b> (<b>--newline</b>) option allows <b>pcre2grep</b> to scan files with 913*22dc650dSSadaf Ebrahiminewline conventions that differ from the default. This option affects only the 914*22dc650dSSadaf Ebrahimiway scanned files are processed. It does not affect the interpretation of files 915*22dc650dSSadaf Ebrahimispecified by the <b>-f</b>, <b>--file-list</b>, <b>--exclude-from</b>, or 916*22dc650dSSadaf Ebrahimi<b>--include-from</b> options. 917*22dc650dSSadaf Ebrahimi</P> 918*22dc650dSSadaf Ebrahimi<P> 919*22dc650dSSadaf EbrahimiAny parts of the scanned input files that are written to the standard output 920*22dc650dSSadaf Ebrahimiare copied with whatever newline sequences they have in the input. However, if 921*22dc650dSSadaf Ebrahimithe final line of a file is output, and it does not end with a newline 922*22dc650dSSadaf Ebrahimisequence, a newline sequence is added. If the newline setting is CR, LF, CRLF 923*22dc650dSSadaf Ebrahimior NUL, that line ending is output; for the other settings (ANYCRLF or ANY) a 924*22dc650dSSadaf Ebrahimisingle NL is used. 925*22dc650dSSadaf Ebrahimi</P> 926*22dc650dSSadaf Ebrahimi<P> 927*22dc650dSSadaf EbrahimiThe newline setting does not affect the way in which <b>pcre2grep</b> writes 928*22dc650dSSadaf Ebrahiminewlines in informational messages to the standard output and error streams. 929*22dc650dSSadaf EbrahimiUnder Windows, the standard output is set to be binary, so that "\r\n" at the 930*22dc650dSSadaf Ebrahimiends of output lines that are copied from the input is not converted to 931*22dc650dSSadaf Ebrahimi"\r\r\n" by the C I/O library. This means that any messages written to the 932*22dc650dSSadaf Ebrahimistandard output must end with "\r\n". For all other operating systems, and 933*22dc650dSSadaf Ebrahimifor all messages to the standard error stream, "\n" is used. 934*22dc650dSSadaf Ebrahimi</P> 935*22dc650dSSadaf Ebrahimi<br><a name="SEC9" href="#TOC1">OPTIONS COMPATIBILITY WITH GNU GREP</a><br> 936*22dc650dSSadaf Ebrahimi<P> 937*22dc650dSSadaf EbrahimiMany of the short and long forms of <b>pcre2grep</b>'s options are the same as 938*22dc650dSSadaf Ebrahimiin the GNU <b>grep</b> program. Any long option of the form <b>--xxx-regexp</b> 939*22dc650dSSadaf Ebrahimi(GNU terminology) is also available as <b>--xxx-regex</b> (PCRE2 terminology). 940*22dc650dSSadaf EbrahimiHowever, the <b>--case-restrict</b>, <b>--depth-limit</b>, <b>-E</b>, 941*22dc650dSSadaf Ebrahimi<b>--file-list</b>, <b>--file-offsets</b>, <b>--heap-limit</b>, 942*22dc650dSSadaf Ebrahimi<b>--include-dir</b>, <b>--line-offsets</b>, <b>--locale</b>, <b>--match-limit</b>, 943*22dc650dSSadaf Ebrahimi<b>-M</b>, <b>--multiline</b>, <b>-N</b>, <b>--newline</b>, <b>--no-ucp</b>, 944*22dc650dSSadaf Ebrahimi<b>--om-separator</b>, <b>--output</b>, <b>-P</b>, <b>-u</b>, <b>--utf</b>, 945*22dc650dSSadaf Ebrahimi<b>-U</b>, and <b>--utf-allow-invalid</b> options are specific to 946*22dc650dSSadaf Ebrahimi<b>pcre2grep</b>, as is the use of the <b>--only-matching</b> option with a 947*22dc650dSSadaf Ebrahimicapturing parentheses number. 948*22dc650dSSadaf Ebrahimi</P> 949*22dc650dSSadaf Ebrahimi<P> 950*22dc650dSSadaf EbrahimiAlthough most of the common options work the same way, a few are different in 951*22dc650dSSadaf Ebrahimi<b>pcre2grep</b>. For example, the <b>--include</b> option's argument is a glob 952*22dc650dSSadaf Ebrahimifor GNU <b>grep</b>, but in <b>pcre2grep</b> it is a regular expression to which 953*22dc650dSSadaf Ebrahimithe <b>-i</b> option applies. If both the <b>-c</b> and <b>-l</b> options are 954*22dc650dSSadaf Ebrahimigiven, GNU grep lists only file names, without counts, but <b>pcre2grep</b> 955*22dc650dSSadaf Ebrahimigives the counts as well. 956*22dc650dSSadaf Ebrahimi</P> 957*22dc650dSSadaf Ebrahimi<br><a name="SEC10" href="#TOC1">OPTIONS WITH DATA</a><br> 958*22dc650dSSadaf Ebrahimi<P> 959*22dc650dSSadaf EbrahimiThere are four different ways in which an option with data can be specified. 960*22dc650dSSadaf EbrahimiIf a short form option is used, the data may follow immediately, or (with one 961*22dc650dSSadaf Ebrahimiexception) in the next command line item. For example: 962*22dc650dSSadaf Ebrahimi<pre> 963*22dc650dSSadaf Ebrahimi -f/some/file 964*22dc650dSSadaf Ebrahimi -f /some/file 965*22dc650dSSadaf Ebrahimi</pre> 966*22dc650dSSadaf EbrahimiThe exception is the <b>-o</b> option, which may appear with or without data. 967*22dc650dSSadaf EbrahimiBecause of this, if data is present, it must follow immediately in the same 968*22dc650dSSadaf Ebrahimiitem, for example -o3. 969*22dc650dSSadaf Ebrahimi</P> 970*22dc650dSSadaf Ebrahimi<P> 971*22dc650dSSadaf EbrahimiIf a long form option is used, the data may appear in the same command line 972*22dc650dSSadaf Ebrahimiitem, separated by an equals character, or (with two exceptions) it may appear 973*22dc650dSSadaf Ebrahimiin the next command line item. For example: 974*22dc650dSSadaf Ebrahimi<pre> 975*22dc650dSSadaf Ebrahimi --file=/some/file 976*22dc650dSSadaf Ebrahimi --file /some/file 977*22dc650dSSadaf Ebrahimi</pre> 978*22dc650dSSadaf EbrahimiNote, however, that if you want to supply a file name beginning with ~ as data 979*22dc650dSSadaf Ebrahimiin a shell command, and have the shell expand ~ to a home directory, you must 980*22dc650dSSadaf Ebrahimiseparate the file name from the option, because the shell does not treat ~ 981*22dc650dSSadaf Ebrahimispecially unless it is at the start of an item. 982*22dc650dSSadaf Ebrahimi</P> 983*22dc650dSSadaf Ebrahimi<P> 984*22dc650dSSadaf EbrahimiThe exceptions to the above are the <b>--colour</b> (or <b>--color</b>) and 985*22dc650dSSadaf Ebrahimi<b>--only-matching</b> options, for which the data is optional. If one of these 986*22dc650dSSadaf Ebrahimioptions does have data, it must be given in the first form, using an equals 987*22dc650dSSadaf Ebrahimicharacter. Otherwise <b>pcre2grep</b> will assume that it has no data. 988*22dc650dSSadaf Ebrahimi</P> 989*22dc650dSSadaf Ebrahimi<br><a name="SEC11" href="#TOC1">USING PCRE2'S CALLOUT FACILITY</a><br> 990*22dc650dSSadaf Ebrahimi<P> 991*22dc650dSSadaf Ebrahimi<b>pcre2grep</b> has, by default, support for calling external programs or 992*22dc650dSSadaf Ebrahimiscripts or echoing specific strings during matching by making use of PCRE2's 993*22dc650dSSadaf Ebrahimicallout facility. However, this support can be completely or partially disabled 994*22dc650dSSadaf Ebrahimiwhen <b>pcre2grep</b> is built. You can find out whether your binary has support 995*22dc650dSSadaf Ebrahimifor callouts by running it with the <b>--help</b> option. If callout support is 996*22dc650dSSadaf Ebrahimicompletely disabled, all callouts in patterns are ignored by <b>pcre2grep</b>. 997*22dc650dSSadaf EbrahimiIf the facility is partially disabled, calling external programs is not 998*22dc650dSSadaf Ebrahimisupported, and callouts that request it are ignored. 999*22dc650dSSadaf Ebrahimi</P> 1000*22dc650dSSadaf Ebrahimi<P> 1001*22dc650dSSadaf EbrahimiA callout in a PCRE2 pattern is of the form (?C<arg>) where the argument is 1002*22dc650dSSadaf Ebrahimieither a number or a quoted string (see the 1003*22dc650dSSadaf Ebrahimi<a href="pcre2callout.html"><b>pcre2callout</b></a> 1004*22dc650dSSadaf Ebrahimidocumentation for details). Numbered callouts are ignored by <b>pcre2grep</b>; 1005*22dc650dSSadaf Ebrahimionly callouts with string arguments are useful. 1006*22dc650dSSadaf Ebrahimi</P> 1007*22dc650dSSadaf Ebrahimi<br><b> 1008*22dc650dSSadaf EbrahimiEchoing a specific string 1009*22dc650dSSadaf Ebrahimi</b><br> 1010*22dc650dSSadaf Ebrahimi<P> 1011*22dc650dSSadaf EbrahimiStarting the callout string with a pipe character invokes an echoing facility 1012*22dc650dSSadaf Ebrahimithat avoids calling an external program or script. This facility is always 1013*22dc650dSSadaf Ebrahimiavailable, provided that callouts were not completely disabled when 1014*22dc650dSSadaf Ebrahimi<b>pcre2grep</b> was built. The rest of the callout string is processed as a 1015*22dc650dSSadaf Ebrahimizero-terminated string, which means it should not contain any internal binary 1016*22dc650dSSadaf Ebrahimizeros. It is written to the output, having first been passed through the same 1017*22dc650dSSadaf Ebrahimiescape processing as text from the <b>--output</b> (<b>-O</b>) option (see 1018*22dc650dSSadaf Ebrahimiabove). However, $0 cannot be used to insert a matched substring because the 1019*22dc650dSSadaf Ebrahimimatch is still in progress. Instead, the single character '0' is inserted. Any 1020*22dc650dSSadaf Ebrahimisyntax errors in the string (for example, a dollar not followed by another 1021*22dc650dSSadaf Ebrahimicharacter) causes the callout to be ignored. No terminator is added to the 1022*22dc650dSSadaf Ebrahimioutput string, so if you want a newline, you must include it explicitly using 1023*22dc650dSSadaf Ebrahimithe escape $n. For example: 1024*22dc650dSSadaf Ebrahimi<pre> 1025*22dc650dSSadaf Ebrahimi pcre2grep '(.)(..(.))(?C"|[$1] [$2] [$3]$n")' <some file> 1026*22dc650dSSadaf Ebrahimi</pre> 1027*22dc650dSSadaf EbrahimiMatching continues normally after the string is output. If you want to see only 1028*22dc650dSSadaf Ebrahimithe callout output but not any output from an actual match, you should end the 1029*22dc650dSSadaf Ebrahimipattern with (*FAIL). 1030*22dc650dSSadaf Ebrahimi</P> 1031*22dc650dSSadaf Ebrahimi<br><b> 1032*22dc650dSSadaf EbrahimiCalling external programs or scripts 1033*22dc650dSSadaf Ebrahimi</b><br> 1034*22dc650dSSadaf Ebrahimi<P> 1035*22dc650dSSadaf EbrahimiThis facility can be independently disabled when <b>pcre2grep</b> is built. It 1036*22dc650dSSadaf Ebrahimiis supported for Windows, where a call to <b>_spawnvp()</b> is used, for VMS, 1037*22dc650dSSadaf Ebrahimiwhere <b>lib$spawn()</b> is used, and for any Unix-like environment where 1038*22dc650dSSadaf Ebrahimi<b>fork()</b> and <b>execv()</b> are available. 1039*22dc650dSSadaf Ebrahimi</P> 1040*22dc650dSSadaf Ebrahimi<P> 1041*22dc650dSSadaf EbrahimiIf the callout string does not start with a pipe (vertical bar) character, it 1042*22dc650dSSadaf Ebrahimiis parsed into a list of substrings separated by pipe characters. The first 1043*22dc650dSSadaf Ebrahimisubstring must be an executable name, with the following substrings specifying 1044*22dc650dSSadaf Ebrahimiarguments: 1045*22dc650dSSadaf Ebrahimi<pre> 1046*22dc650dSSadaf Ebrahimi executable_name|arg1|arg2|... 1047*22dc650dSSadaf Ebrahimi</pre> 1048*22dc650dSSadaf EbrahimiAny substring (including the executable name) may contain escape sequences 1049*22dc650dSSadaf Ebrahimistarted by a dollar character. These are the same as for the <b>--output</b> 1050*22dc650dSSadaf Ebrahimi(<b>-O</b>) option documented above, except that $0 cannot insert the matched 1051*22dc650dSSadaf Ebrahimistring because the match is still in progress. Instead, the character '0' 1052*22dc650dSSadaf Ebrahimiis inserted. If you need a literal dollar or pipe character in any 1053*22dc650dSSadaf Ebrahimisubstring, use $$ or $| respectively. Here is an example: 1054*22dc650dSSadaf Ebrahimi<pre> 1055*22dc650dSSadaf Ebrahimi echo -e "abcde\n12345" | pcre2grep \ 1056*22dc650dSSadaf Ebrahimi '(?x)(.)(..(.)) 1057*22dc650dSSadaf Ebrahimi (?C"/bin/echo|Arg1: [$1] [$2] [$3]|Arg2: $|${1}$| ($4)")()' - 1058*22dc650dSSadaf Ebrahimi 1059*22dc650dSSadaf Ebrahimi Output: 1060*22dc650dSSadaf Ebrahimi 1061*22dc650dSSadaf Ebrahimi Arg1: [a] [bcd] [d] Arg2: |a| () 1062*22dc650dSSadaf Ebrahimi abcde 1063*22dc650dSSadaf Ebrahimi Arg1: [1] [234] [4] Arg2: |1| () 1064*22dc650dSSadaf Ebrahimi 12345 1065*22dc650dSSadaf Ebrahimi</pre> 1066*22dc650dSSadaf EbrahimiThe parameters for the system call that is used to run the program or script 1067*22dc650dSSadaf Ebrahimiare zero-terminated strings. This means that binary zero characters in the 1068*22dc650dSSadaf Ebrahimicallout argument will cause premature termination of their substrings, and 1069*22dc650dSSadaf Ebrahimitherefore should not be present. Any syntax errors in the string (for example, 1070*22dc650dSSadaf Ebrahimia dollar not followed by another character) causes the callout to be ignored. 1071*22dc650dSSadaf EbrahimiIf running the program fails for any reason (including the non-existence of the 1072*22dc650dSSadaf Ebrahimiexecutable), a local matching failure occurs and the matcher backtracks in the 1073*22dc650dSSadaf Ebrahiminormal way. 1074*22dc650dSSadaf Ebrahimi</P> 1075*22dc650dSSadaf Ebrahimi<br><a name="SEC12" href="#TOC1">MATCHING ERRORS</a><br> 1076*22dc650dSSadaf Ebrahimi<P> 1077*22dc650dSSadaf EbrahimiIt is possible to supply a regular expression that takes a very long time to 1078*22dc650dSSadaf Ebrahimifail to match certain lines. Such patterns normally involve nested indefinite 1079*22dc650dSSadaf Ebrahimirepeats, for example: (a+)*\d when matched against a line of a's with no final 1080*22dc650dSSadaf Ebrahimidigit. The PCRE2 matching function has a resource limit that causes it to abort 1081*22dc650dSSadaf Ebrahimiin these circumstances. If this happens, <b>pcre2grep</b> outputs an error 1082*22dc650dSSadaf Ebrahimimessage and the line that caused the problem to the standard error stream. If 1083*22dc650dSSadaf Ebrahimithere are more than 20 such errors, <b>pcre2grep</b> gives up. 1084*22dc650dSSadaf Ebrahimi</P> 1085*22dc650dSSadaf Ebrahimi<P> 1086*22dc650dSSadaf EbrahimiThe <b>--match-limit</b> option of <b>pcre2grep</b> can be used to set the 1087*22dc650dSSadaf Ebrahimioverall resource limit. There are also other limits that affect the amount of 1088*22dc650dSSadaf Ebrahimimemory used during matching; see the discussion of <b>--heap-limit</b> and 1089*22dc650dSSadaf Ebrahimi<b>--depth-limit</b> above. 1090*22dc650dSSadaf Ebrahimi</P> 1091*22dc650dSSadaf Ebrahimi<br><a name="SEC13" href="#TOC1">DIAGNOSTICS</a><br> 1092*22dc650dSSadaf Ebrahimi<P> 1093*22dc650dSSadaf EbrahimiExit status is 0 if any matches were found, 1 if no matches were found, and 2 1094*22dc650dSSadaf Ebrahimifor syntax errors, overlong lines, non-existent or inaccessible files (even if 1095*22dc650dSSadaf Ebrahimimatches were found in other files) or too many matching errors. Using the 1096*22dc650dSSadaf Ebrahimi<b>-s</b> option to suppress error messages about inaccessible files does not 1097*22dc650dSSadaf Ebrahimiaffect the return code. 1098*22dc650dSSadaf Ebrahimi</P> 1099*22dc650dSSadaf Ebrahimi<P> 1100*22dc650dSSadaf EbrahimiWhen run under VMS, the return code is placed in the symbol PCRE2GREP_RC 1101*22dc650dSSadaf Ebrahimibecause VMS does not distinguish between exit(0) and exit(1). 1102*22dc650dSSadaf Ebrahimi</P> 1103*22dc650dSSadaf Ebrahimi<br><a name="SEC14" href="#TOC1">SEE ALSO</a><br> 1104*22dc650dSSadaf Ebrahimi<P> 1105*22dc650dSSadaf Ebrahimi<b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3), 1106*22dc650dSSadaf Ebrahimi<b>pcre2unicode</b>(3). 1107*22dc650dSSadaf Ebrahimi</P> 1108*22dc650dSSadaf Ebrahimi<br><a name="SEC15" href="#TOC1">AUTHOR</a><br> 1109*22dc650dSSadaf Ebrahimi<P> 1110*22dc650dSSadaf EbrahimiPhilip Hazel 1111*22dc650dSSadaf Ebrahimi<br> 1112*22dc650dSSadaf EbrahimiRetired from University Computing Service 1113*22dc650dSSadaf Ebrahimi<br> 1114*22dc650dSSadaf EbrahimiCambridge, England. 1115*22dc650dSSadaf Ebrahimi<br> 1116*22dc650dSSadaf Ebrahimi</P> 1117*22dc650dSSadaf Ebrahimi<br><a name="SEC16" href="#TOC1">REVISION</a><br> 1118*22dc650dSSadaf Ebrahimi<P> 1119*22dc650dSSadaf EbrahimiLast updated: 22 December 2023 1120*22dc650dSSadaf Ebrahimi<br> 1121*22dc650dSSadaf EbrahimiCopyright © 1997-2023 University of Cambridge. 1122*22dc650dSSadaf Ebrahimi<br> 1123*22dc650dSSadaf Ebrahimi<p> 1124*22dc650dSSadaf EbrahimiReturn to the <a href="index.html">PCRE2 index page</a>. 1125*22dc650dSSadaf Ebrahimi</p> 1126