esruby 0.0.0

data/resources/mruby/build/mrbgems/mruby-regexp-pcre/pcre/doc/pcregrep.txt

@@ -0,0 +1,740 @@
+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 quotes 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.
+
+       The amount of memory used for buffering files that are being scanned is
+       controlled by a parameter that can be set by the --buffer-size  option.
+       The  default  value  for  this  parameter is specified when pcregrep is
+       built, with the default default being 20K.  A  block  of  memory  three
+       times  this  size  is used (to allow for buffering "before" and "after"
+       lines). An error occurs if a line overflows the buffer.
+
+       Patterns can be no longer than 8K or BUFSIZ  bytes,  whichever  is  the
+       greater.   BUFSIZ  is defined in <stdio.h>. 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.
+
+       By default, as soon as one pattern matches a line, no further  patterns
+       are considered. However, if --colour (or --color) is used to colour the
+       matching substrings, or if --only-matching, --file-offsets, or  --line-
+       offsets  is  used  to  output  only  the  part of the line that matched
+       (either shown literally, or as an offset), scanning resumes immediately
+       following  the  match,  so that further matches on the same line can be
+       found. If there are multiple  patterns,  they  are  all  tried  on  the
+       remainder  of  the  line, but patterns that follow the one that matched
+       are not tried on the earlier part of the line.
+
+       This behaviour means that the order  in  which  multiple  patterns  are
+       specified  can affect the output when one of the above options is used.
+       This is no longer the same behaviour as GNU grep, which now manages  to
+       display  earlier  matches  for  later  patterns (as long as there is no
+       overlap).
+
+       Patterns that can match an empty string are accepted, but empty  string
+       matches   are   never   recognized.   An   example   is   the   pattern
+       "(super)?(man)?", in which all components are  optional.  This  pattern
+       finds  all  occurrences  of  both "super" and "man"; the output differs
+       from matching with "super|man" when only the  matching  substrings  are
+       being shown.
+
+       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.
+
+
+BINARY FILES
+
+       By default, a file that contains a binary zero byte  within  the  first
+       1024  bytes is identified as a binary file, and is processed specially.
+       (GNU grep also  identifies  binary  files  in  this  manner.)  See  the
+       --binary-files  option for a means of changing the way binary files are
+       handled.
+
+
+OPTIONS
+
+       The order in which some of the options appear can  affect  the  output.
+       For  example,  both  the  -h and -l options affect the printing of file
+       names. Whichever comes later in the command line will be the  one  that
+       takes  effect.  Similarly,  except  where  noted below, if an option is
+       given twice, the later setting is used. Numerical  values  for  options
+       may  be  followed  by  K  or  M,  to  signify multiplication by 1024 or
+       1024*1024 respectively.
+
+       --        This terminates the list of options. It is useful if the next
+                 item  on  the command line starts with a hyphen but is not an
+                 option. This allows for the processing of patterns and  file-
+                 names that start with hyphens.
+
+       -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.
+
+       -a, --text
+                 Treat binary files as text. This is equivalent  to  --binary-
+                 files=text.
+
+       -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.
+
+       --binary-files=word
+                 Specify how binary files are to be processed. If the word  is
+                 "binary"  (the  default),  pattern  matching  is performed on
+                 binary files, but the only  output  is  "Binary  file  <name>
+                 matches"  when a match succeeds. If the word is "text", which
+                 is equivalent to the -a or --text option,  binary  files  are
+                 processed  in  the  same way as any other file. In this case,
+                 when a match succeeds, the  output  may  be  binary  garbage,
+                 which  can  have  nasty effects if sent to a terminal. If the
+                 word is  "without-match",  which  is  equivalent  to  the  -I
+                 option,  binary  files  are  not  processed  at all; they are
+                 assumed not to be of interest.
+
+       --buffer-size=number
+                 Set the parameter that controls how much memory is  used  for
+                 buffering files that are being scanned.
+
+       -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 from the files that are being
+                 scanned; instead output the number of lines that would other-
+                 wise  have  been  shown. If no lines are selected, the number
+                 zero is output. If several files are  are  being  scanned,  a
+                 count  is  output  for each of them. However, if the --files-
+                 with-matches option is also  used,  only  those  files  whose
+                 counts are greater than zero are listed. When -c is used, 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 parts of a
+                 line that matched a pattern should be coloured in the output.
+                 By default, the output is not coloured. The value  (which  is
+                 optional,  see above) may be "never", "always", or "auto". In
+                 the latter case, colouring happens only if the standard  out-
+                 put  is connected to a terminal. More resources are used when
+                 colouring is enabled, because pcregrep has to search for  all
+                 possible  matches in a line, not just one, in order to colour
+                 them all.
+
+                 The colour that is used can be specified by setting the envi-
+                 ronment 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  terminal,  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  in
+                 non-Windows  environments,  for compatibility with GNU grep),
+                 "recurse" (equivalent to the -r option), or "skip"  (silently
+                 skip  the  path, the default in Windows environments). In the
+                 "read" case, directories are read as if  they  were  ordinary
+                 files.  In  some  operating  systems  the effect of reading a
+                 directory like this is an immediate end-of-file; in others it
+                 may provoke an error.
+
+       -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 no limit to the number of patterns. They  are
+                 applied  to  each line in the order in which they are defined
+                 until one matches.
+
+                 If -f is used with -e, the command line patterns are  matched
+                 first, followed by the patterns from the file(s), independent
+                 of the order in which these options are specified. Note  that
+                 multiple  use  of -e is not the same as a single pattern with
+                 alternatives. For example, X|Y finds the first character in a
+                 line  that  is  X or Y, whereas if the two patterns are given
+                 separately, with X first, 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 matters only if you are  using  -o  or
+                 --colo(u)r to show the part(s) of the line that matched.
+
+       --exclude=pattern
+                 Files (but not directories) whose names match the pattern are
+                 skipped without being processed. This applies to  all  files,
+                 whether  listed  on  the  command line, obtained from --file-
+                 list, or by scanning a directory. The pattern is a PCRE regu-
+                 lar expression, and is matched against the final component of
+                 the file name, not the  entire  path.  The  -F,  -w,  and  -x
+                 options do not apply to this pattern. The option may be given
+                 any number of times in order to specify multiple patterns. If
+                 a  file  name matches both an --include and an --exclude pat-
+                 tern, it is excluded. There is no short form for this option.
+
+       --exclude-from=filename
+                 Treat each non-empty line of the file  as  the  data  for  an
+                 --exclude option. What constitutes a newline when reading the
+                 file is the operating system's default. The --newline  option
+                 has  no  effect on this option. This option may be given more
+                 than once in order to specify a number of files to read.
+
+       --exclude-dir=pattern
+                 Directories whose names match the pattern are skipped without
+                 being  processed,  whatever  the  setting  of the --recursive
+                 option. This applies to all directories,  whether  listed  on
+                 the command line, obtained from --file-list, or by scanning a
+                 parent directory. The pattern is a PCRE  regular  expression,
+                 and  is  matched against the final component of the directory
+                 name, not the entire path. The -F, -w, and -x options do  not
+                 apply  to this pattern. The option may be given any number of
+                 times in order to specify more than one pattern. If a  direc-
+                 tory  matches  both  --include-dir  and  --exclude-dir, it is
+                 excluded. There is no short form for this option.
+
+       -F, --fixed-strings
+                 Interpret each data-matching  pattern  as  a  list  of  fixed
+                 strings,  separated  by  newlines,  instead  of  as a regular
+                 expression. What constitutes a newline for  this  purpose  is
+                 controlled  by the --newline option. 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 (subject to -w or -x, if
+                 present).  This  option applies only to the patterns that are
+                 matched against the contents of files; it does not  apply  to
+                 patterns  specified  by  any  of  the  --include or --exclude
+                 options.
+
+       -f filename, --file=filename
+                 Read patterns from the file, one per  line,  and  match  them
+                 against  each  line of input. What constitutes a newline when
+                 reading the file  is  the  operating  system's  default.  The
+                 --newline option has no effect on this option. Trailing white
+                 space is removed from each line, and blank lines are ignored.
+                 An  empty  file  contains  no  patterns and therefore matches
+                 nothing. See also the comments about multiple patterns versus
+                 a  single  pattern with alternatives in the description of -e
+                 above.
+
+                 If this option is given more than  once,  all  the  specified
+                 files  are read. A data line is output if any of the patterns
+                 match it. A 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 the
+                 names of paths to be searched.
+
+       --file-list=filename
+                 Read  a  list  of  files  and/or  directories  that are to be
+                 scanned from the given file, one  per  line.  Trailing  white
+                 space is removed from each line, and blank lines are ignored.
+                 These paths are processed before any that are listed  on  the
+                 command  line.  The  filename can be given as "-" to refer to
+                 the standard input.  If --file and --file-list are both spec-
+                 ified  as  "-",  patterns are read first. This is useful only
+                 when the standard input is a  terminal,  from  which  further
+                 lines  (the  list  of files) can be read after an end-of-file
+                 indication. If this option is given more than once,  all  the
+                 specified files are read.
+
+       --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; for context lines, a hyphen separator
+                 is  used.  If  a line number is also being output, it follows
+                 the file name.
+
+       -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;  for  context lines, a hyphen separator is used.  If a
+                 line number is also being output, it follows the file name.
+
+       --help    Output a help message, giving brief details  of  the  command
+                 options  and  file type support, and then exit. Anything else
+                 on the command line is ignored.
+
+       -I        Treat binary files as never matching. This is  equivalent  to
+                 --binary-files=without-match.
+
+       -i, --ignore-case
+                 Ignore upper/lower case distinctions during comparisons.
+
+       --include=pattern
+                 If  any --include patterns are specified, the only files that
+                 are processed are those that match one of the  patterns  (and
+                 do  not  match  an  --exclude  pattern). This option does not
+                 affect directories, but it  applies  to  all  files,  whether
+                 listed  on the command line, obtained from --file-list, or by
+                 scanning a directory. The pattern is a PCRE  regular  expres-
+                 sion,  and is matched against the final component of the file
+                 name, not the entire path. The -F, -w, and -x options do  not
+                 apply  to this pattern. The option may be given any number of
+                 times. If a file  name  matches  both  an  --include  and  an
+                 --exclude  pattern,  it  is excluded.  There is no short form
+                 for this option.
+
+       --include-from=filename
+                 Treat each non-empty line of the file  as  the  data  for  an
+                 --include option. What constitutes a newline for this purpose
+                 is the operating system's default. The --newline  option  has
+                 no effect on this option. This option may be given any number
+                 of times; all the files are read.
+
+       --include-dir=pattern
+                 If any --include-dir patterns are specified, the only  direc-
+                 tories  that  are  processed  are those that match one of the
+                 patterns (and do not match an  --exclude-dir  pattern).  This
+                 applies  to  all  directories,  whether listed on the command
+                 line, obtained from --file-list,  or  by  scanning  a  parent
+                 directory.  The  pattern is a PCRE regular expression, and is
+                 matched against the final component of  the  directory  name,
+                 not  the entire path. The -F, -w, and -x options do not apply
+                 to this pattern. The option may be given any number of times.
+                 If  a directory 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 normally stops as soon as a matching line is  found
+                 in  a  file.  However, if the -c (count) option is also used,
+                 matching continues in order to obtain the correct count,  and
+                 those  files  that  have  at least one match are listed along
+                 with their counts. Using this option with -c is a way of sup-
+                 pressing the listing of files with no matches.
+
+       --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-buffered
+                 When  this  option is given, input is read and processed line
+                 by line, and the output  is  flushed  after  each  write.  By
+                 default,  input  is read in large chunks, unless pcregrep can
+                 determine that it is reading from a terminal (which  is  cur-
+                 rently  possible  only  in Unix-like environments). Output to
+                 terminal is normally automatically flushed by  the  operating
+                 system. This option can be useful when the input or output is
+                 attached to a pipe and you do not want pcregrep to buffer  up
+                 large  amounts  of data. However, its use will affect perfor-
+                 mance, and the -M (multiline) option ceases to work.
+
+       --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.
+
+       --match-limit=number
+                 Processing some regular expression  patterns  can  require  a
+                 very  large amount of memory, leading in some cases to a pro-
+                 gram crash if not enough is available.   Other  patterns  may
+                 take  a  very  long  time to search for all possible matching
+                 strings. The pcre_exec() function that is called by  pcregrep
+                 to  do  the  matching  has  two parameters that can limit the
+                 resources that it uses.
+
+                 The  --match-limit  option  provides  a  means  of   limiting
+                 resource usage when processing patterns that are not going to
+                 match, but which have a very large number of possibilities in
+                 their  search  trees.  The  classic example is a pattern that
+                 uses nested unlimited repeats. Internally, PCRE uses a  func-
+                 tion  called  match()  which  it  calls repeatedly (sometimes
+                 recursively). The limit set by --match-limit  is  imposed  on
+                 the  number  of times this function is called during a match,
+                 which has the effect of limiting the amount  of  backtracking
+                 that can take place.
+
+                 The --recursion-limit option is similar to --match-limit, but
+                 instead of limiting the total number of times that match() is
+                 called, it limits the depth of recursive calls, which in turn
+                 limits the amount of memory that can be used.  The  recursion
+                 depth  is  a  smaller  number than the total number of calls,
+                 because not all calls to match() are recursive. This limit is
+                 of use only if it is set smaller than --match-limit.
+
+                 There  are no short forms for these options. The default set-
+                 tings are specified when the PCRE library is  compiled,  with
+                 the default default being 10 million.
+
+       -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 a successful match may consist of  more  than  one
+                 line,  the last of which is the one in which the match ended.
+                 If the matched string ends with a newline sequence the output
+                 ends at the end of that 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.  This option does not work when input
+                 is read line by line (see --line-buffered.)
+
+       -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  (form feed,
+                 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  to  scan  files
+                 that have come from other environments without having to mod-
+                 ify their line endings. If the data  that  is  being  scanned
+                 does  not agree with the convention set by this option, pcre-
+                 grep may behave in strange ways. Note that this  option  does
+                 not  apply  to  files specified by the -f, --exclude-from, or
+                 --include-from options, which are expected to use the operat-
+                 ing system's standard newline sequence.
+
+       -n, --line-number
+                 Precede each output line by its line number in the file, fol-
+                 lowed by a colon for matching lines or a hyphen  for  context
+                 lines.  If the filename is also being output, it precedes the
+                 line number. This option is forced if --line-offsets is used.
+
+       --no-jit  If the PCRE library is built with  support  for  just-in-time
+                 compiling  (which speeds up matching), pcregrep automatically
+                 makes use of this, unless it was explicitly disabled at build
+                 time.  This  option  can be used to disable the use of JIT at
+                 run time. It is provided for testing and working round  prob-
+                 lems.  It should never be needed in normal use.
+
+       -o, --only-matching
+                 Show only the part of the line that matched a pattern instead
+                 of the whole line. In this mode, no context  is  shown.  That
+                 is,  the -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. If the matched portion of
+                 the line is empty, nothing is output unless the file name  or
+                 line  number  are being printed, in which case they are shown
+                 on an otherwise empty line. This option is mutually exclusive
+                 with --file-offsets and --line-offsets.
+
+       -onumber, --only-matching=number
+                 Show  only  the  part  of the line that matched the capturing
+                 parentheses of the given number. Up to 32 capturing parenthe-
+                 ses are supported, and -o0 is equivalent to -o without a num-
+                 ber. Because these options can be given without  an  argument
+                 (see  above),  if an argument is present, it must be given in
+                 the same shell item, for example, -o3  or  --only-matching=2.
+                 The comments given for the non-argument case above also apply
+                 to this case. If the specified capturing parentheses  do  not
+                 exist  in  the pattern, or were not set in the match, nothing
+                 is output unless the file  name  or  line  number  are  being
+                 printed.
+
+                 If  this  option is given multiple times, multiple substrings
+                 are output, in the order the options are given. For  example,
+                 -o3 -o1 -o3 causes the substrings matched by capturing paren-
+                 theses 3 and 1 and then 3 again to  be  output.  By  default,
+                 there is no separator (but see the next option).
+
+       --om-separator=text
+                 Specify  a  separating string for multiple occurrences of -o.
+                 The default is an empty string. Separating strings are  never
+                 coloured.
+
+       -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".
+
+       --recursion-limit=number
+                 See --match-limit above.
+
+       -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. All patterns (including
+                 those for any --exclude and --include options) and  all  sub-
+                 ject  lines  that  are scanned must be valid strings of UTF-8
+                 characters.
+
+       -V, --version
+                 Write the version numbers of pcregrep and the PCRE library to
+                 the  standard output and then exit. Anything else on the com-
+                 mand line is ignored.
+
+       -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.  This
+                 option  applies only to the patterns that are matched against
+                 the contents of files; it does not apply to  patterns  speci-
+                 fied by any of the --include or --exclude options.
+
+       -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. This option applies only to the patterns that
+                 are matched against the contents of files; it does not  apply
+                 to  patterns  specified  by any of the --include or --exclude
+                 options.
+
+
+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. Any parts of the input files that
+       are  written  to the standard output are copied identically, with what-
+       ever newline sequences they have in the input. However, the setting  of
+       this  option  does  not affect the interpretation of files specified by
+       the -f, --exclude-from, or --include-from options, which are assumed to
+       use  the  operating  system's  standard  newline  sequence, nor does it
+       affect the way in which pcregrep writes informational messages  to  the
+       standard error and output streams. For these it uses the string "\n" to
+       indicate newlines, relying on the C I/O library to convert this  to  an
+       appropriate sequence.
+
+
+OPTIONS COMPATIBILITY
+
+       Many  of the 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). How-
+       ever, the --file-list, --file-offsets,  --include-dir,  --line-offsets,
+       --locale,  --match-limit,  -M, --multiline, -N, --newline, --om-separa-
+       tor, --recursion-limit, -u, and --utf-8 options are specific  to  pcre-
+       grep,  as  is  the  use  of the --only-matching option with a capturing
+       parentheses number.
+
+       Although most of the common options work the same way, a few  are  dif-
+       ferent  in  pcregrep. For example, the --include option's argument is a
+       glob for GNU grep, but a regular expression for pcregrep. If  both  the
+       -c  and  -l  options are given, GNU grep lists only file names, without
+       counts, but pcregrep gives the counts.
+
+
+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 (with one exception) in the next command line item. For exam-
+       ple:
+
+         -f/some/file
+         -f /some/file
+
+       The  exception is the -o option, which may appear with or without data.
+       Because of this, if data is present, it must follow immediately in  the
+       same item, for example -o3.
+
+       If  a long form option is used, the data may appear in the same command
+       line item, separated by an equals character, or (with  two  exceptions)
+       it may appear in the next command line item. For example:
+
+         --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 exceptions to the above are the --colour (or --color)  and  --only-
+       matching  options,  for  which  the  data  is optional. If one of these
+       options does have data, it must be given in the first  form,  using  an
+       equals character. Otherwise pcregrep will assume 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.
+
+       The --match-limit option of pcregrep can be used  to  set  the  overall
+       resource  limit; there is a second option called --recursion-limit that
+       sets a limit on the amount of memory (usually stack) that is used  (see
+       the discussion of these options above).
+
+
+DIAGNOSTICS
+
+       Exit status is 0 if any matches were found, 1 if no matches were found,
+       and 2 for syntax errors, overlong lines, non-existent  or  inaccessible
+       files  (even if matches were found in other files) or too many matching
+       errors. Using the -s option to suppress error messages about inaccessi-
+       ble files does not affect the return code.
+
+
+SEE ALSO
+
+       pcrepattern(3), pcresyntax(3), pcretest(1).
+
+
+AUTHOR
+
+       Philip Hazel
+       University Computing Service
+       Cambridge CB2 3QH, England.
+
+
+REVISION
+
+       Last updated: 13 September 2012
+       Copyright (c) 1997-2012 University of Cambridge.