diff -r 000000000000 -r 7f656887cf89 libraries/spcre/libpcre/pcre/doc/pcregrep.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/libraries/spcre/libpcre/pcre/doc/pcregrep.txt Wed Jun 23 15:52:26 2010 +0100 @@ -0,0 +1,498 @@ +PCREGREP(1) PCREGREP(1) + + +NAME + pcregrep - a grep with Perl-compatible regular expressions. + + +SYNOPSIS + pcregrep [options] [long options] [pattern] [path1 path2 ...] + + +DESCRIPTION + + pcregrep searches files for character patterns, in the same way as + other grep commands do, but it uses the PCRE regular expression library + to support patterns that are compatible with the regular expressions of + Perl 5. See pcrepattern(3) for a full description of syntax and seman- + tics of the regular expressions that PCRE supports. + + Patterns, whether supplied on the command line or in a separate file, + are given without delimiters. For example: + + pcregrep Thursday /etc/motd + + If you attempt to use delimiters (for example, by surrounding a pattern + with slashes, as is common in Perl scripts), they are interpreted as + part of the pattern. Quotes can of course be used to delimit patterns + on the command line because they are interpreted by the shell, and + indeed they are required if a pattern contains white space or shell + metacharacters. + + The first argument that follows any option settings is treated as the + single pattern to be matched when neither -e nor -f is present. Con- + versely, when one or both of these options are used to specify pat- + terns, all arguments are treated as path names. At least one of -e, -f, + or an argument pattern must be provided. + + If no files are specified, pcregrep reads the standard input. The stan- + dard input can also be referenced by a name consisting of a single + hyphen. For example: + + pcregrep some-pattern /file1 - /file3 + + By default, each line that matches a pattern is copied to the standard + output, and if there is more than one file, the file name is output at + the start of each line, followed by a colon. However, there are options + that can change how pcregrep behaves. In particular, the -M option + makes it possible to search for patterns that span line boundaries. + What defines a line boundary is controlled by the -N (--newline) + option. + + Patterns are limited to 8K or BUFSIZ characters, whichever is the + greater. BUFSIZ is defined in . When there is more than one + pattern (specified by the use of -e and/or -f), each pattern is applied + to each line in the order in which they are defined, except that all + the -e patterns are tried before the -f patterns. As soon as one pat- + tern matches (or fails to match when -v is used), no further patterns + are considered. + + When --only-matching, --file-offsets, or --line-offsets is used, the + output is the part of the line that matched (either shown literally, or + as an offset). In this case, scanning resumes immediately following the + match, so that further matches on the same line can be found. If there + are multiple patterns, they are all tried on the remainder of the line. + However, patterns that follow the one that matched are not tried on the + earlier part of the line. + + If the LC_ALL or LC_CTYPE environment variable is set, pcregrep uses + the value to set a locale when calling the PCRE library. The --locale + option can be used to override this. + + +SUPPORT FOR COMPRESSED FILES + + It is possible to compile pcregrep so that it uses libz or libbz2 to + read files whose names end in .gz or .bz2, respectively. You can find + out whether your binary has support for one or both of these file types + by running it with the --help option. If the appropriate support is not + present, files are treated as plain text. The standard input is always + so treated. + + +OPTIONS + + -- This terminate the list of options. It is useful if the next + item on the command line starts with a hyphen but is not an + option. This allows for the processing of patterns and file- + names that start with hyphens. + + -A number, --after-context=number + Output number lines of context after each matching line. If + filenames and/or line numbers are being output, a hyphen sep- + arator is used instead of a colon for the context lines. A + line containing "--" is output between each group of lines, + unless they are in fact contiguous in the input file. The + value of number is expected to be relatively small. However, + pcregrep guarantees to have up to 8K of following text avail- + able for context output. + + -B number, --before-context=number + Output number lines of context before each matching line. If + filenames and/or line numbers are being output, a hyphen sep- + arator is used instead of a colon for the context lines. A + line containing "--" is output between each group of lines, + unless they are in fact contiguous in the input file. The + value of number is expected to be relatively small. However, + pcregrep guarantees to have up to 8K of preceding text avail- + able for context output. + + -C number, --context=number + Output number lines of context both before and after each + matching line. This is equivalent to setting both -A and -B + to the same value. + + -c, --count + Do not output individual lines; instead just output a count + of the number of lines that would otherwise have been output. + If several files are given, a count is output for each of + them. In this mode, the -A, -B, and -C options are ignored. + + --colour, --color + If this option is given without any data, it is equivalent to + "--colour=auto". If data is required, it must be given in + the same shell item, separated by an equals sign. + + --colour=value, --color=value + This option specifies under what circumstances the part of a + line that matched a pattern should be coloured in the output. + The value may be "never" (the default), "always", or "auto". + In the latter case, colouring happens only if the standard + output is connected to a terminal. The colour can be speci- + fied by setting the environment variable PCREGREP_COLOUR or + PCREGREP_COLOR. The value of this variable should be a string + of two numbers, separated by a semicolon. They are copied + directly into the control string for setting colour on a ter- + minal, so it is your responsibility to ensure that they make + sense. If neither of the environment variables is set, the + default is "1;31", which gives red. + + -D action, --devices=action + If an input path is not a regular file or a directory, + "action" specifies how it is to be processed. Valid values + are "read" (the default) or "skip" (silently skip the path). + + -d action, --directories=action + If an input path is a directory, "action" specifies how it is + to be processed. Valid values are "read" (the default), + "recurse" (equivalent to the -r option), or "skip" (silently + skip the path). In the default case, directories are read as + if they were ordinary files. In some operating systems the + effect of reading a directory like this is an immediate end- + of-file. + + -e pattern, --regex=pattern, --regexp=pattern + Specify a pattern to be matched. This option can be used mul- + tiple times in order to specify several patterns. It can also + be used as a way of specifying a single pattern that starts + with a hyphen. When -e is used, no argument pattern is taken + from the command line; all arguments are treated as file + names. There is an overall maximum of 100 patterns. They are + applied to each line in the order in which they are defined + until one matches (or fails to match if -v is used). If -f is + used with -e, the command line patterns are matched first, + followed by the patterns from the file, independent of the + order in which these options are specified. Note that multi- + ple use of -e is not the same as a single pattern with alter- + natives. For example, X|Y finds the first character in a line + that is X or Y, whereas if the two patterns are given sepa- + rately, pcregrep finds X if it is present, even if it follows + Y in the line. It finds Y only if there is no X in the line. + This really matters only if you are using -o to show the + part(s) of the line that matched. + + --exclude=pattern + When pcregrep is searching the files in a directory as a con- + sequence of the -r (recursive search) option, any regular + files whose names match the pattern are excluded. Subdirecto- + ries are not excluded by this option; they are searched + recursively, subject to the --exclude_dir and --include_dir + options. The pattern is a PCRE regular expression, and is + matched against the final component of the file name (not the + entire path). If a file name matches both --include and + --exclude, it is excluded. There is no short form for this + option. + + --exclude_dir=pattern + When pcregrep is searching the contents of a directory as a + consequence of the -r (recursive search) option, any subdi- + rectories whose names match the pattern are excluded. (Note + that the --exclude option does not affect subdirectories.) + The pattern is a PCRE regular expression, and is matched + against the final component of the name (not the entire + path). If a subdirectory name matches both --include_dir and + --exclude_dir, it is excluded. There is no short form for + this option. + + -F, --fixed-strings + Interpret each pattern as a list of fixed strings, separated + by newlines, instead of as a regular expression. The -w + (match as a word) and -x (match whole line) options can be + used with -F. They apply to each of the fixed strings. A line + is selected if any of the fixed strings are found in it (sub- + ject to -w or -x, if present). + + -f filename, --file=filename + Read a number of patterns from the file, one per line, and + match them against each line of input. A data line is output + if any of the patterns match it. The filename can be given as + "-" to refer to the standard input. When -f is used, patterns + specified on the command line using -e may also be present; + they are tested before the file's patterns. However, no other + pattern is taken from the command line; all arguments are + treated as file names. There is an overall maximum of 100 + patterns. Trailing white space is removed from each line, and + blank lines are ignored. An empty file contains no patterns + and therefore matches nothing. See also the comments about + multiple patterns versus a single pattern with alternatives + in the description of -e above. + + --file-offsets + Instead of showing lines or parts of lines that match, show + each match as an offset from the start of the file and a + length, separated by a comma. In this mode, no context is + shown. That is, the -A, -B, and -C options are ignored. If + there is more than one match in a line, each of them is shown + separately. This option is mutually exclusive with --line- + offsets and --only-matching. + + -H, --with-filename + Force the inclusion of the filename at the start of output + lines when searching a single file. By default, the filename + is not shown in this case. For matching lines, the filename + is followed by a colon and a space; for context lines, a + hyphen separator is used. If a line number is also being out- + put, it follows the file name without a space. + + -h, --no-filename + Suppress the output filenames when searching multiple files. + By default, filenames are shown when multiple files are + searched. For matching lines, the filename is followed by a + colon and a space; for context lines, a hyphen separator is + used. If a line number is also being output, it follows the + file name without a space. + + --help Output a help message, giving brief details of the command + options and file type support, and then exit. + + -i, --ignore-case + Ignore upper/lower case distinctions during comparisons. + + --include=pattern + When pcregrep is searching the files in a directory as a con- + sequence of the -r (recursive search) option, only those reg- + ular files whose names match the pattern are included. Subdi- + rectories are always included and searched recursively, sub- + ject to the --include_dir and --exclude_dir options. The pat- + tern is a PCRE regular expression, and is matched against the + final component of the file name (not the entire path). If a + file name matches both --include and --exclude, it is + excluded. There is no short form for this option. + + --include_dir=pattern + When pcregrep is searching the contents of a directory as a + consequence of the -r (recursive search) option, only those + subdirectories whose names match the pattern are included. + (Note that the --include option does not affect subdirecto- + ries.) The pattern is a PCRE regular expression, and is + matched against the final component of the name (not the + entire path). If a subdirectory name matches both + --include_dir and --exclude_dir, it is excluded. There is no + short form for this option. + + -L, --files-without-match + Instead of outputting lines from the files, just output the + names of the files that do not contain any lines that would + have been output. Each file name is output once, on a sepa- + rate line. + + -l, --files-with-matches + Instead of outputting lines from the files, just output the + names of the files containing lines that would have been out- + put. Each file name is output once, on a separate line. + Searching stops as soon as a matching line is found in a + file. + + --label=name + This option supplies a name to be used for the standard input + when file names are being output. If not supplied, "(standard + input)" is used. There is no short form for this option. + + --line-offsets + Instead of showing lines or parts of lines that match, show + each match as a line number, the offset from the start of the + line, and a length. The line number is terminated by a colon + (as usual; see the -n option), and the offset and length are + separated by a comma. In this mode, no context is shown. + That is, the -A, -B, and -C options are ignored. If there is + more than one match in a line, each of them is shown sepa- + rately. This option is mutually exclusive with --file-offsets + and --only-matching. + + --locale=locale-name + This option specifies a locale to be used for pattern match- + ing. It overrides the value in the LC_ALL or LC_CTYPE envi- + ronment variables. If no locale is specified, the PCRE + library's default (usually the "C" locale) is used. There is + no short form for this option. + + -M, --multiline + Allow patterns to match more than one line. When this option + is given, patterns may usefully contain literal newline char- + acters and internal occurrences of ^ and $ characters. The + output for any one match may consist of more than one line. + When this option is set, the PCRE library is called in "mul- + tiline" mode. There is a limit to the number of lines that + can be matched, imposed by the way that pcregrep buffers the + input file as it scans it. However, pcregrep ensures that at + least 8K characters or the rest of the document (whichever is + the shorter) are available for forward matching, and simi- + larly the previous 8K characters (or all the previous charac- + ters, if fewer than 8K) are guaranteed to be available for + lookbehind assertions. + + -N newline-type, --newline=newline-type + The PCRE library supports five different conventions for + indicating the ends of lines. They are the single-character + sequences CR (carriage return) and LF (linefeed), the two- + character sequence CRLF, an "anycrlf" convention, which rec- + ognizes any of the preceding three types, and an "any" con- + vention, in which any Unicode line ending sequence is assumed + to end a line. The Unicode sequences are the three just men- + tioned, plus VT (vertical tab, U+000B), FF (formfeed, + U+000C), NEL (next line, U+0085), LS (line separator, + U+2028), and PS (paragraph separator, U+2029). + + When the PCRE library is built, a default line-ending + sequence is specified. This is normally the standard + sequence for the operating system. Unless otherwise specified + by this option, pcregrep uses the library's default. The + possible values for this option are CR, LF, CRLF, ANYCRLF, or + ANY. This makes it possible to use pcregrep on files that + have come from other environments without having to modify + their line endings. If the data that is being scanned does + not agree with the convention set by this option, pcregrep + may behave in strange ways. + + -n, --line-number + Precede each output line by its line number in the file, fol- + lowed by a colon and a space for matching lines or a hyphen + and a space for context lines. If the filename is also being + output, it precedes the line number. This option is forced if + --line-offsets is used. + + -o, --only-matching + Show only the part of the line that matched a pattern. In + this mode, no context is shown. That is, the -A, -B, and -C + options are ignored. If there is more than one match in a + line, each of them is shown separately. If -o is combined + with -v (invert the sense of the match to find non-matching + lines), no output is generated, but the return code is set + appropriately. This option is mutually exclusive with --file- + offsets and --line-offsets. + + -q, --quiet + Work quietly, that is, display nothing except error messages. + The exit status indicates whether or not any matches were + found. + + -r, --recursive + If any given path is a directory, recursively scan the files + it contains, taking note of any --include and --exclude set- + tings. By default, a directory is read as a normal file; in + some operating systems this gives an immediate end-of-file. + This option is a shorthand for setting the -d option to + "recurse". + + -s, --no-messages + Suppress error messages about non-existent or unreadable + files. Such files are quietly skipped. However, the return + code is still 2, even if matches were found in other files. + + -u, --utf-8 + Operate in UTF-8 mode. This option is available only if PCRE + has been compiled with UTF-8 support. Both patterns and sub- + ject lines must be valid strings of UTF-8 characters. + + -V, --version + Write the version numbers of pcregrep and the PCRE library + that is being used to the standard error stream. + + -v, --invert-match + Invert the sense of the match, so that lines which do not + match any of the patterns are the ones that are found. + + -w, --word-regex, --word-regexp + Force the patterns to match only whole words. This is equiva- + lent to having \b at the start and end of the pattern. + + -x, --line-regex, --line-regexp + Force the patterns to be anchored (each must start matching + at the beginning of a line) and in addition, require them to + match entire lines. This is equivalent to having ^ and $ + characters at the start and end of each alternative branch in + every pattern. + + +ENVIRONMENT VARIABLES + + The environment variables LC_ALL and LC_CTYPE are examined, in that + order, for a locale. The first one that is set is used. This can be + overridden by the --locale option. If no locale is set, the PCRE + library's default (usually the "C" locale) is used. + + +NEWLINES + + The -N (--newline) option allows pcregrep to scan files with different + newline conventions from the default. However, the setting of this + option does not affect the way in which pcregrep writes information to + the standard error and output streams. It uses the string "\n" in C + printf() calls to indicate newlines, relying on the C I/O library to + convert this to an appropriate sequence if the output is sent to a + file. + + +OPTIONS COMPATIBILITY + + The majority of short and long forms of pcregrep's options are the same + as in the GNU grep program. Any long option of the form --xxx-regexp + (GNU terminology) is also available as --xxx-regex (PCRE terminology). + However, the --locale, -M, --multiline, -u, and --utf-8 options are + specific to pcregrep. + + +OPTIONS WITH DATA + + There are four different ways in which an option with data can be spec- + ified. If a short form option is used, the data may follow immedi- + ately, or in the next command line item. For example: + + -f/some/file + -f /some/file + + If a long form option is used, the data may appear in the same command + line item, separated by an equals character, or (with one exception) it + may appear in the next command line item. For example: + + --file=/some/file + --file /some/file + + Note, however, that if you want to supply a file name beginning with ~ + as data in a shell command, and have the shell expand ~ to a home + directory, you must separate the file name from the option, because the + shell does not treat ~ specially unless it is at the start of an item. + + The exception to the above is the --colour (or --color) option, for + which the data is optional. If this option does have data, it must be + given in the first form, using an equals character. Otherwise it will + be assumed that it has no data. + + +MATCHING ERRORS + + It is possible to supply a regular expression that takes a very long + time to fail to match certain lines. Such patterns normally involve + nested indefinite repeats, for example: (a+)*\d when matched against a + line of a's with no final digit. The PCRE matching function has a + resource limit that causes it to abort in these circumstances. If this + happens, pcregrep outputs an error message and the line that caused the + problem to the standard error stream. If there are more than 20 such + errors, pcregrep gives up. + + +DIAGNOSTICS + + Exit status is 0 if any matches were found, 1 if no matches were found, + and 2 for syntax errors and non-existent or inacessible files (even if + matches were found in other files) or too many matching errors. Using + the -s option to suppress error messages about inaccessble files does + not affect the return code. + + +SEE ALSO + + pcrepattern(3), pcretest(1). + + +AUTHOR + + Philip Hazel + University Computing Service + Cambridge CB2 3QH, England. + + +REVISION + + Last updated: 08 March 2008 + Copyright (c) 1997-2008 University of Cambridge.