Annotation of embedaddon/pcre/doc/pcregrep.txt, revision 1.1
1.1 ! misho 1: PCREGREP(1) PCREGREP(1)
! 2:
! 3:
! 4: NAME
! 5: pcregrep - a grep with Perl-compatible regular expressions.
! 6:
! 7:
! 8: SYNOPSIS
! 9: pcregrep [options] [long options] [pattern] [path1 path2 ...]
! 10:
! 11:
! 12: DESCRIPTION
! 13:
! 14: pcregrep searches files for character patterns, in the same way as
! 15: other grep commands do, but it uses the PCRE regular expression library
! 16: to support patterns that are compatible with the regular expressions of
! 17: Perl 5. See pcrepattern(3) for a full description of syntax and seman-
! 18: tics of the regular expressions that PCRE supports.
! 19:
! 20: Patterns, whether supplied on the command line or in a separate file,
! 21: are given without delimiters. For example:
! 22:
! 23: pcregrep Thursday /etc/motd
! 24:
! 25: If you attempt to use delimiters (for example, by surrounding a pattern
! 26: with slashes, as is common in Perl scripts), they are interpreted as
! 27: part of the pattern. Quotes can of course be used to delimit patterns
! 28: on the command line because they are interpreted by the shell, and
! 29: indeed they are required if a pattern contains white space or shell
! 30: metacharacters.
! 31:
! 32: The first argument that follows any option settings is treated as the
! 33: single pattern to be matched when neither -e nor -f is present. Con-
! 34: versely, when one or both of these options are used to specify pat-
! 35: terns, all arguments are treated as path names. At least one of -e, -f,
! 36: or an argument pattern must be provided.
! 37:
! 38: If no files are specified, pcregrep reads the standard input. The stan-
! 39: dard input can also be referenced by a name consisting of a single
! 40: hyphen. For example:
! 41:
! 42: pcregrep some-pattern /file1 - /file3
! 43:
! 44: By default, each line that matches a pattern is copied to the standard
! 45: output, and if there is more than one file, the file name is output at
! 46: the start of each line, followed by a colon. However, there are options
! 47: that can change how pcregrep behaves. In particular, the -M option
! 48: makes it possible to search for patterns that span line boundaries.
! 49: What defines a line boundary is controlled by the -N (--newline)
! 50: option.
! 51:
! 52: The amount of memory used for buffering files that are being scanned is
! 53: controlled by a parameter that can be set by the --buffer-size option.
! 54: The default value for this parameter is specified when pcregrep is
! 55: built, with the default default being 20K. A block of memory three
! 56: times this size is used (to allow for buffering "before" and "after"
! 57: lines). An error occurs if a line overflows the buffer.
! 58:
! 59: Patterns are limited to 8K or BUFSIZ bytes, whichever is the greater.
! 60: BUFSIZ is defined in <stdio.h>. When there is more than one pattern
! 61: (specified by the use of -e and/or -f), each pattern is applied to each
! 62: line in the order in which they are defined, except that all the -e
! 63: patterns are tried before the -f patterns.
! 64:
! 65: By default, as soon as one pattern matches (or fails to match when -v
! 66: is used), no further patterns are considered. However, if --colour (or
! 67: --color) is used to colour the matching substrings, or if --only-match-
! 68: ing, --file-offsets, or --line-offsets is used to output only the part
! 69: of the line that matched (either shown literally, or as an offset),
! 70: scanning resumes immediately following the match, so that further
! 71: matches on the same line can be found. If there are multiple patterns,
! 72: they are all tried on the remainder of the line, but patterns that fol-
! 73: low the one that matched are not tried on the earlier part of the line.
! 74:
! 75: This is the same behaviour as GNU grep, but it does mean that the order
! 76: in which multiple patterns are specified can affect the output when one
! 77: of the above options is used.
! 78:
! 79: Patterns that can match an empty string are accepted, but empty string
! 80: matches are never recognized. An example is the pattern
! 81: "(super)?(man)?", in which all components are optional. This pattern
! 82: finds all occurrences of both "super" and "man"; the output differs
! 83: from matching with "super|man" when only the matching substrings are
! 84: being shown.
! 85:
! 86: If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses
! 87: the value to set a locale when calling the PCRE library. The --locale
! 88: option can be used to override this.
! 89:
! 90:
! 91: SUPPORT FOR COMPRESSED FILES
! 92:
! 93: It is possible to compile pcregrep so that it uses libz or libbz2 to
! 94: read files whose names end in .gz or .bz2, respectively. You can find
! 95: out whether your binary has support for one or both of these file types
! 96: by running it with the --help option. If the appropriate support is not
! 97: present, files are treated as plain text. The standard input is always
! 98: so treated.
! 99:
! 100:
! 101: OPTIONS
! 102:
! 103: The order in which some of the options appear can affect the output.
! 104: For example, both the -h and -l options affect the printing of file
! 105: names. Whichever comes later in the command line will be the one that
! 106: takes effect. Numerical values for options may be followed by K or M,
! 107: to signify multiplication by 1024 or 1024*1024 respectively.
! 108:
! 109: -- This terminates the list of options. It is useful if the next
! 110: item on the command line starts with a hyphen but is not an
! 111: option. This allows for the processing of patterns and file-
! 112: names that start with hyphens.
! 113:
! 114: -A number, --after-context=number
! 115: Output number lines of context after each matching line. If
! 116: filenames and/or line numbers are being output, a hyphen sep-
! 117: arator is used instead of a colon for the context lines. A
! 118: line containing "--" is output between each group of lines,
! 119: unless they are in fact contiguous in the input file. The
! 120: value of number is expected to be relatively small. However,
! 121: pcregrep guarantees to have up to 8K of following text avail-
! 122: able for context output.
! 123:
! 124: -B number, --before-context=number
! 125: Output number lines of context before each matching line. If
! 126: filenames and/or line numbers are being output, a hyphen sep-
! 127: arator is used instead of a colon for the context lines. A
! 128: line containing "--" is output between each group of lines,
! 129: unless they are in fact contiguous in the input file. The
! 130: value of number is expected to be relatively small. However,
! 131: pcregrep guarantees to have up to 8K of preceding text avail-
! 132: able for context output.
! 133:
! 134: --buffer-size=number
! 135: Set the parameter that controls how much memory is used for
! 136: buffering files that are being scanned.
! 137:
! 138: -C number, --context=number
! 139: Output number lines of context both before and after each
! 140: matching line. This is equivalent to setting both -A and -B
! 141: to the same value.
! 142:
! 143: -c, --count
! 144: Do not output individual lines from the files that are being
! 145: scanned; instead output the number of lines that would other-
! 146: wise have been shown. If no lines are selected, the number
! 147: zero is output. If several files are are being scanned, a
! 148: count is output for each of them. However, if the --files-
! 149: with-matches option is also used, only those files whose
! 150: counts are greater than zero are listed. When -c is used, the
! 151: -A, -B, and -C options are ignored.
! 152:
! 153: --colour, --color
! 154: If this option is given without any data, it is equivalent to
! 155: "--colour=auto". If data is required, it must be given in
! 156: the same shell item, separated by an equals sign.
! 157:
! 158: --colour=value, --color=value
! 159: This option specifies under what circumstances the parts of a
! 160: line that matched a pattern should be coloured in the output.
! 161: By default, the output is not coloured. The value (which is
! 162: optional, see above) may be "never", "always", or "auto". In
! 163: the latter case, colouring happens only if the standard out-
! 164: put is connected to a terminal. More resources are used when
! 165: colouring is enabled, because pcregrep has to search for all
! 166: possible matches in a line, not just one, in order to colour
! 167: them all.
! 168:
! 169: The colour that is used can be specified by setting the envi-
! 170: ronment variable PCREGREP_COLOUR or PCREGREP_COLOR. The value
! 171: of this variable should be a string of two numbers, separated
! 172: by a semicolon. They are copied directly into the control
! 173: string for setting colour on a terminal, so it is your
! 174: responsibility to ensure that they make sense. If neither of
! 175: the environment variables is set, the default is "1;31",
! 176: which gives red.
! 177:
! 178: -D action, --devices=action
! 179: If an input path is not a regular file or a directory,
! 180: "action" specifies how it is to be processed. Valid values
! 181: are "read" (the default) or "skip" (silently skip the path).
! 182:
! 183: -d action, --directories=action
! 184: If an input path is a directory, "action" specifies how it is
! 185: to be processed. Valid values are "read" (the default),
! 186: "recurse" (equivalent to the -r option), or "skip" (silently
! 187: skip the path). In the default case, directories are read as
! 188: if they were ordinary files. In some operating systems the
! 189: effect of reading a directory like this is an immediate end-
! 190: of-file.
! 191:
! 192: -e pattern, --regex=pattern, --regexp=pattern
! 193: Specify a pattern to be matched. This option can be used mul-
! 194: tiple times in order to specify several patterns. It can also
! 195: be used as a way of specifying a single pattern that starts
! 196: with a hyphen. When -e is used, no argument pattern is taken
! 197: from the command line; all arguments are treated as file
! 198: names. There is an overall maximum of 100 patterns. They are
! 199: applied to each line in the order in which they are defined
! 200: until one matches (or fails to match if -v is used). If -f is
! 201: used with -e, the command line patterns are matched first,
! 202: followed by the patterns from the file, independent of the
! 203: order in which these options are specified. Note that multi-
! 204: ple use of -e is not the same as a single pattern with alter-
! 205: natives. For example, X|Y finds the first character in a line
! 206: that is X or Y, whereas if the two patterns are given sepa-
! 207: rately, pcregrep finds X if it is present, even if it follows
! 208: Y in the line. It finds Y only if there is no X in the line.
! 209: This really matters only if you are using -o to show the
! 210: part(s) of the line that matched.
! 211:
! 212: --exclude=pattern
! 213: When pcregrep is searching the files in a directory as a con-
! 214: sequence of the -r (recursive search) option, any regular
! 215: files whose names match the pattern are excluded. Subdirecto-
! 216: ries are not excluded by this option; they are searched
! 217: recursively, subject to the --exclude-dir and --include_dir
! 218: options. The pattern is a PCRE regular expression, and is
! 219: matched against the final component of the file name (not the
! 220: entire path). If a file name matches both --include and
! 221: --exclude, it is excluded. There is no short form for this
! 222: option.
! 223:
! 224: --exclude-dir=pattern
! 225: When pcregrep is searching the contents of a directory as a
! 226: consequence of the -r (recursive search) option, any subdi-
! 227: rectories whose names match the pattern are excluded. (Note
! 228: that the --exclude option does not affect subdirectories.)
! 229: The pattern is a PCRE regular expression, and is matched
! 230: against the final component of the name (not the entire
! 231: path). If a subdirectory name matches both --include-dir and
! 232: --exclude-dir, it is excluded. There is no short form for
! 233: this option.
! 234:
! 235: -F, --fixed-strings
! 236: Interpret each pattern as a list of fixed strings, separated
! 237: by newlines, instead of as a regular expression. The -w
! 238: (match as a word) and -x (match whole line) options can be
! 239: used with -F. They apply to each of the fixed strings. A line
! 240: is selected if any of the fixed strings are found in it (sub-
! 241: ject to -w or -x, if present).
! 242:
! 243: -f filename, --file=filename
! 244: Read a number of patterns from the file, one per line, and
! 245: match them against each line of input. A data line is output
! 246: if any of the patterns match it. The filename can be given as
! 247: "-" to refer to the standard input. When -f is used, patterns
! 248: specified on the command line using -e may also be present;
! 249: they are tested before the file's patterns. However, no other
! 250: pattern is taken from the command line; all arguments are
! 251: treated as file names. There is an overall maximum of 100
! 252: patterns. Trailing white space is removed from each line, and
! 253: blank lines are ignored. An empty file contains no patterns
! 254: and therefore matches nothing. See also the comments about
! 255: multiple patterns versus a single pattern with alternatives
! 256: in the description of -e above.
! 257:
! 258: --file-offsets
! 259: Instead of showing lines or parts of lines that match, show
! 260: each match as an offset from the start of the file and a
! 261: length, separated by a comma. In this mode, no context is
! 262: shown. That is, the -A, -B, and -C options are ignored. If
! 263: there is more than one match in a line, each of them is shown
! 264: separately. This option is mutually exclusive with --line-
! 265: offsets and --only-matching.
! 266:
! 267: -H, --with-filename
! 268: Force the inclusion of the filename at the start of output
! 269: lines when searching a single file. By default, the filename
! 270: is not shown in this case. For matching lines, the filename
! 271: is followed by a colon; for context lines, a hyphen separator
! 272: is used. If a line number is also being output, it follows
! 273: the file name.
! 274:
! 275: -h, --no-filename
! 276: Suppress the output filenames when searching multiple files.
! 277: By default, filenames are shown when multiple files are
! 278: searched. For matching lines, the filename is followed by a
! 279: colon; for context lines, a hyphen separator is used. If a
! 280: line number is also being output, it follows the file name.
! 281:
! 282: --help Output a help message, giving brief details of the command
! 283: options and file type support, and then exit.
! 284:
! 285: -i, --ignore-case
! 286: Ignore upper/lower case distinctions during comparisons.
! 287:
! 288: --include=pattern
! 289: When pcregrep is searching the files in a directory as a con-
! 290: sequence of the -r (recursive search) option, only those reg-
! 291: ular files whose names match the pattern are included. Subdi-
! 292: rectories are always included and searched recursively, sub-
! 293: ject to the --include-dir and --exclude-dir options. The pat-
! 294: tern is a PCRE regular expression, and is matched against the
! 295: final component of the file name (not the entire path). If a
! 296: file name matches both --include and --exclude, it is
! 297: excluded. There is no short form for this option.
! 298:
! 299: --include-dir=pattern
! 300: When pcregrep is searching the contents of a directory as a
! 301: consequence of the -r (recursive search) option, only those
! 302: subdirectories whose names match the pattern are included.
! 303: (Note that the --include option does not affect subdirecto-
! 304: ries.) The pattern is a PCRE regular expression, and is
! 305: matched against the final component of the name (not the
! 306: entire path). If a subdirectory name matches both --include-
! 307: dir and --exclude-dir, it is excluded. There is no short form
! 308: for this option.
! 309:
! 310: -L, --files-without-match
! 311: Instead of outputting lines from the files, just output the
! 312: names of the files that do not contain any lines that would
! 313: have been output. Each file name is output once, on a sepa-
! 314: rate line.
! 315:
! 316: -l, --files-with-matches
! 317: Instead of outputting lines from the files, just output the
! 318: names of the files containing lines that would have been out-
! 319: put. Each file name is output once, on a separate line.
! 320: Searching normally stops as soon as a matching line is found
! 321: in a file. However, if the -c (count) option is also used,
! 322: matching continues in order to obtain the correct count, and
! 323: those files that have at least one match are listed along
! 324: with their counts. Using this option with -c is a way of sup-
! 325: pressing the listing of files with no matches.
! 326:
! 327: --label=name
! 328: This option supplies a name to be used for the standard input
! 329: when file names are being output. If not supplied, "(standard
! 330: input)" is used. There is no short form for this option.
! 331:
! 332: --line-buffered
! 333: When this option is given, input is read and processed line
! 334: by line, and the output is flushed after each write. By
! 335: default, input is read in large chunks, unless pcregrep can
! 336: determine that it is reading from a terminal (which is cur-
! 337: rently possible only in Unix environments). Output to termi-
! 338: nal is normally automatically flushed by the operating sys-
! 339: tem. This option can be useful when the input or output is
! 340: attached to a pipe and you do not want pcregrep to buffer up
! 341: large amounts of data. However, its use will affect perfor-
! 342: mance, and the -M (multiline) option ceases to work.
! 343:
! 344: --line-offsets
! 345: Instead of showing lines or parts of lines that match, show
! 346: each match as a line number, the offset from the start of the
! 347: line, and a length. The line number is terminated by a colon
! 348: (as usual; see the -n option), and the offset and length are
! 349: separated by a comma. In this mode, no context is shown.
! 350: That is, the -A, -B, and -C options are ignored. If there is
! 351: more than one match in a line, each of them is shown sepa-
! 352: rately. This option is mutually exclusive with --file-offsets
! 353: and --only-matching.
! 354:
! 355: --locale=locale-name
! 356: This option specifies a locale to be used for pattern match-
! 357: ing. It overrides the value in the LC_ALL or LC_CTYPE envi-
! 358: ronment variables. If no locale is specified, the PCRE
! 359: library's default (usually the "C" locale) is used. There is
! 360: no short form for this option.
! 361:
! 362: --match-limit=number
! 363: Processing some regular expression patterns can require a
! 364: very large amount of memory, leading in some cases to a pro-
! 365: gram crash if not enough is available. Other patterns may
! 366: take a very long time to search for all possible matching
! 367: strings. The pcre_exec() function that is called by pcregrep
! 368: to do the matching has two parameters that can limit the
! 369: resources that it uses.
! 370:
! 371: The --match-limit option provides a means of limiting
! 372: resource usage when processing patterns that are not going to
! 373: match, but which have a very large number of possibilities in
! 374: their search trees. The classic example is a pattern that
! 375: uses nested unlimited repeats. Internally, PCRE uses a func-
! 376: tion called match() which it calls repeatedly (sometimes
! 377: recursively). The limit set by --match-limit is imposed on
! 378: the number of times this function is called during a match,
! 379: which has the effect of limiting the amount of backtracking
! 380: that can take place.
! 381:
! 382: The --recursion-limit option is similar to --match-limit, but
! 383: instead of limiting the total number of times that match() is
! 384: called, it limits the depth of recursive calls, which in turn
! 385: limits the amount of memory that can be used. The recursion
! 386: depth is a smaller number than the total number of calls,
! 387: because not all calls to match() are recursive. This limit is
! 388: of use only if it is set smaller than --match-limit.
! 389:
! 390: There are no short forms for these options. The default set-
! 391: tings are specified when the PCRE library is compiled, with
! 392: the default default being 10 million.
! 393:
! 394: -M, --multiline
! 395: Allow patterns to match more than one line. When this option
! 396: is given, patterns may usefully contain literal newline char-
! 397: acters and internal occurrences of ^ and $ characters. The
! 398: output for a successful match may consist of more than one
! 399: line, the last of which is the one in which the match ended.
! 400: If the matched string ends with a newline sequence the output
! 401: ends at the end of that line.
! 402:
! 403: When this option is set, the PCRE library is called in "mul-
! 404: tiline" mode. There is a limit to the number of lines that
! 405: can be matched, imposed by the way that pcregrep buffers the
! 406: input file as it scans it. However, pcregrep ensures that at
! 407: least 8K characters or the rest of the document (whichever is
! 408: the shorter) are available for forward matching, and simi-
! 409: larly the previous 8K characters (or all the previous charac-
! 410: ters, if fewer than 8K) are guaranteed to be available for
! 411: lookbehind assertions. This option does not work when input
! 412: is read line by line (see --line-buffered.)
! 413:
! 414: -N newline-type, --newline=newline-type
! 415: The PCRE library supports five different conventions for
! 416: indicating the ends of lines. They are the single-character
! 417: sequences CR (carriage return) and LF (linefeed), the two-
! 418: character sequence CRLF, an "anycrlf" convention, which rec-
! 419: ognizes any of the preceding three types, and an "any" con-
! 420: vention, in which any Unicode line ending sequence is assumed
! 421: to end a line. The Unicode sequences are the three just men-
! 422: tioned, plus VT (vertical tab, U+000B), FF (form feed,
! 423: U+000C), NEL (next line, U+0085), LS (line separator,
! 424: U+2028), and PS (paragraph separator, U+2029).
! 425:
! 426: When the PCRE library is built, a default line-ending
! 427: sequence is specified. This is normally the standard
! 428: sequence for the operating system. Unless otherwise specified
! 429: by this option, pcregrep uses the library's default. The
! 430: possible values for this option are CR, LF, CRLF, ANYCRLF, or
! 431: ANY. This makes it possible to use pcregrep on files that
! 432: have come from other environments without having to modify
! 433: their line endings. If the data that is being scanned does
! 434: not agree with the convention set by this option, pcregrep
! 435: may behave in strange ways.
! 436:
! 437: -n, --line-number
! 438: Precede each output line by its line number in the file, fol-
! 439: lowed by a colon for matching lines or a hyphen for context
! 440: lines. If the filename is also being output, it precedes the
! 441: line number. This option is forced if --line-offsets is used.
! 442:
! 443: --no-jit If the PCRE library is built with support for just-in-time
! 444: compiling (which speeds up matching), pcregrep automatically
! 445: makes use of this, unless it was explicitly disabled at build
! 446: time. This option can be used to disable the use of JIT at
! 447: run time. It is provided for testing and working round prob-
! 448: lems. It should never be needed in normal use.
! 449:
! 450: -o, --only-matching
! 451: Show only the part of the line that matched a pattern instead
! 452: of the whole line. In this mode, no context is shown. That
! 453: is, the -A, -B, and -C options are ignored. If there is more
! 454: than one match in a line, each of them is shown separately.
! 455: If -o is combined with -v (invert the sense of the match to
! 456: find non-matching lines), no output is generated, but the
! 457: return code is set appropriately. If the matched portion of
! 458: the line is empty, nothing is output unless the file name or
! 459: line number are being printed, in which case they are shown
! 460: on an otherwise empty line. This option is mutually exclusive
! 461: with --file-offsets and --line-offsets.
! 462:
! 463: -onumber, --only-matching=number
! 464: Show only the part of the line that matched the capturing
! 465: parentheses of the given number. Up to 32 capturing parenthe-
! 466: ses are supported. Because these options can be given without
! 467: an argument (see above), if an argument is present, it must
! 468: be given in the same shell item, for example, -o3 or --only-
! 469: matching=2. The comments given for the non-argument case
! 470: above also apply to this case. If the specified capturing
! 471: parentheses do not exist in the pattern, or were not set in
! 472: the match, nothing is output unless the file name or line
! 473: number are being printed.
! 474:
! 475: -q, --quiet
! 476: Work quietly, that is, display nothing except error messages.
! 477: The exit status indicates whether or not any matches were
! 478: found.
! 479:
! 480: -r, --recursive
! 481: If any given path is a directory, recursively scan the files
! 482: it contains, taking note of any --include and --exclude set-
! 483: tings. By default, a directory is read as a normal file; in
! 484: some operating systems this gives an immediate end-of-file.
! 485: This option is a shorthand for setting the -d option to
! 486: "recurse".
! 487:
! 488: --recursion-limit=number
! 489: See --match-limit above.
! 490:
! 491: -s, --no-messages
! 492: Suppress error messages about non-existent or unreadable
! 493: files. Such files are quietly skipped. However, the return
! 494: code is still 2, even if matches were found in other files.
! 495:
! 496: -u, --utf-8
! 497: Operate in UTF-8 mode. This option is available only if PCRE
! 498: has been compiled with UTF-8 support. Both patterns and sub-
! 499: ject lines must be valid strings of UTF-8 characters.
! 500:
! 501: -V, --version
! 502: Write the version numbers of pcregrep and the PCRE library
! 503: that is being used to the standard error stream.
! 504:
! 505: -v, --invert-match
! 506: Invert the sense of the match, so that lines which do not
! 507: match any of the patterns are the ones that are found.
! 508:
! 509: -w, --word-regex, --word-regexp
! 510: Force the patterns to match only whole words. This is equiva-
! 511: lent to having \b at the start and end of the pattern.
! 512:
! 513: -x, --line-regex, --line-regexp
! 514: Force the patterns to be anchored (each must start matching
! 515: at the beginning of a line) and in addition, require them to
! 516: match entire lines. This is equivalent to having ^ and $
! 517: characters at the start and end of each alternative branch in
! 518: every pattern.
! 519:
! 520:
! 521: ENVIRONMENT VARIABLES
! 522:
! 523: The environment variables LC_ALL and LC_CTYPE are examined, in that
! 524: order, for a locale. The first one that is set is used. This can be
! 525: overridden by the --locale option. If no locale is set, the PCRE
! 526: library's default (usually the "C" locale) is used.
! 527:
! 528:
! 529: NEWLINES
! 530:
! 531: The -N (--newline) option allows pcregrep to scan files with different
! 532: newline conventions from the default. However, the setting of this
! 533: option does not affect the way in which pcregrep writes information to
! 534: the standard error and output streams. It uses the string "\n" in C
! 535: printf() calls to indicate newlines, relying on the C I/O library to
! 536: convert this to an appropriate sequence if the output is sent to a
! 537: file.
! 538:
! 539:
! 540: OPTIONS COMPATIBILITY
! 541:
! 542: Many of the short and long forms of pcregrep's options are the same as
! 543: in the GNU grep program (version 2.5.4). Any long option of the form
! 544: --xxx-regexp (GNU terminology) is also available as --xxx-regex (PCRE
! 545: terminology). However, the --file-offsets, --include-dir, --line-off-
! 546: sets, --locale, --match-limit, -M, --multiline, -N, --newline, --recur-
! 547: sion-limit, -u, and --utf-8 options are specific to pcregrep, as is the
! 548: use of the --only-matching option with a capturing parentheses number.
! 549:
! 550: Although most of the common options work the same way, a few are dif-
! 551: ferent in pcregrep. For example, the --include option's argument is a
! 552: glob for GNU grep, but a regular expression for pcregrep. If both the
! 553: -c and -l options are given, GNU grep lists only file names, without
! 554: counts, but pcregrep gives the counts.
! 555:
! 556:
! 557: OPTIONS WITH DATA
! 558:
! 559: There are four different ways in which an option with data can be spec-
! 560: ified. If a short form option is used, the data may follow immedi-
! 561: ately, or (with one exception) in the next command line item. For exam-
! 562: ple:
! 563:
! 564: -f/some/file
! 565: -f /some/file
! 566:
! 567: The exception is the -o option, which may appear with or without data.
! 568: Because of this, if data is present, it must follow immediately in the
! 569: same item, for example -o3.
! 570:
! 571: If a long form option is used, the data may appear in the same command
! 572: line item, separated by an equals character, or (with two exceptions)
! 573: it may appear in the next command line item. For example:
! 574:
! 575: --file=/some/file
! 576: --file /some/file
! 577:
! 578: Note, however, that if you want to supply a file name beginning with ~
! 579: as data in a shell command, and have the shell expand ~ to a home
! 580: directory, you must separate the file name from the option, because the
! 581: shell does not treat ~ specially unless it is at the start of an item.
! 582:
! 583: The exceptions to the above are the --colour (or --color) and --only-
! 584: matching options, for which the data is optional. If one of these
! 585: options does have data, it must be given in the first form, using an
! 586: equals character. Otherwise pcregrep will assume that it has no data.
! 587:
! 588:
! 589: MATCHING ERRORS
! 590:
! 591: It is possible to supply a regular expression that takes a very long
! 592: time to fail to match certain lines. Such patterns normally involve
! 593: nested indefinite repeats, for example: (a+)*\d when matched against a
! 594: line of a's with no final digit. The PCRE matching function has a
! 595: resource limit that causes it to abort in these circumstances. If this
! 596: happens, pcregrep outputs an error message and the line that caused the
! 597: problem to the standard error stream. If there are more than 20 such
! 598: errors, pcregrep gives up.
! 599:
! 600: The --match-limit option of pcregrep can be used to set the overall
! 601: resource limit; there is a second option called --recursion-limit that
! 602: sets a limit on the amount of memory (usually stack) that is used (see
! 603: the discussion of these options above).
! 604:
! 605:
! 606: DIAGNOSTICS
! 607:
! 608: Exit status is 0 if any matches were found, 1 if no matches were found,
! 609: and 2 for syntax errors, overlong lines, non-existent or inaccessible
! 610: files (even if matches were found in other files) or too many matching
! 611: errors. Using the -s option to suppress error messages about inaccessi-
! 612: ble files does not affect the return code.
! 613:
! 614:
! 615: SEE ALSO
! 616:
! 617: pcrepattern(3), pcretest(1).
! 618:
! 619:
! 620: AUTHOR
! 621:
! 622: Philip Hazel
! 623: University Computing Service
! 624: Cambridge CB2 3QH, England.
! 625:
! 626:
! 627: REVISION
! 628:
! 629: Last updated: 06 September 2011
! 630: Copyright (c) 1997-2011 University of Cambridge.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcregrep.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc