PCREGREP(1)                                                        PCREGREP(1)


NAME
       pcregrep - a grep with Perl-compatible regular expressions.


SYNOPSIS
       pcregrep [options] [long options] [pattern] [file1 file2 ...]


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 for a full description of syntax and  semantics
       of the regular expressions that PCRE supports.

       A pattern must be specified on the command line unless the -f option is
       used (see below).

       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 the pattern is copied to  the  stan-
       dard  output,  and  if  there  is  more than one file, the file name is
       printed before each line of output. However, there are options that can
       change how pcregrep behaves. In particular, the -M option makes it pos-
       sible to search for patterns that span line boundaries.

       Patterns are limited to 8K  or  BUFSIZ  characters,  whichever  is  the
       greater.  BUFSIZ is defined in <stdio.h>.


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.

       -A number Print  number  lines  of context after each matching line. If
                 file names and/or line numbers are being  printed,  a  hyphen
                 separator is used instead of a colon for the context lines. A
                 line containing "--" is printed 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 printing.

       -B number Print number lines of context before each matching  line.  If
                 file  names  and/or  line numbers are being printed, a hyphen
                 separator is used instead of a colon for the context lines. A
                 line  containing "--" is printed 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 printing.

       -C number Print  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        Do  not print individual lines; instead just print a count of
                 the number of lines that would otherwise have  been  printed.
                 If  several  files  are given, a count is printed for each of
                 them.

       --exclude=pattern
                 When pcregrep is searching the files in a directory as a con-
                 sequence of the -r (recursive search) option, any files whose
                 names match the pattern are excluded. The pattern is  a  PCRE
                 regular expression. If a file name matches both --include and
                 --exclude, it is excluded. There is no short  form  for  this
                 option.

       -ffilename
                 Read  a  number  of patterns from the file, one per line, and
                 match all of them against each line of input. A line is  out-
                 put  if  any  of  the patterns match it.  When -f is used, no
                 pattern is taken from the command  line;  all  arguments  are
                 treated  as  file  names. There is a maximum of 100 patterns.
                 Trailing white space is removed, and blank lines are ignored.
                 An  empty  file  contains  no  patterns and therefore matches
                 nothing.

       -h        Suppress printing of filenames when searching multiple files.

       -i        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  files
                 whose  names match the pattern are included. The pattern is a
                 PCRE  regular  expression.  If  a  file  name  matches   both
                 --include  and  --exclude,  it is excluded. There is no short
                 form for this option.

       -L        Instead of printing lines from  the  files,  just  print  the
                 names  of  the files that do not contain any lines that would
                 have been printed. Each file name is printed once, on a sepa-
                 rate line.

       -l        Instead  of  printing  lines  from  the files, just print the
                 names of the files containing  lines  that  would  have  been
                 printed.  Each file name is printed once, on a separate line.

       --label=name
                 This option supplies a name to be used for the standard input
                 when  file  names are being printed. If not supplied, "(stan-
                 dard input)" is used. There is no short form for this option.

       -M        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        Precede each line by its line number in the file.

       -q        Work quietly, that is, display nothing except error messages.
                 The exit status indicates whether or  not  any  matches  were
                 found.

       -r        If  any given path is a directory, recursively scan the files
                 it contains, taking note of any --include and --exclude  set-
                 tings. Without -r a directory is scanned as a normal file.

       -s        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        Operate  in UTF-8 mode. This option is available only if PCRE
                 has been compiled with UTF-8 support. Both  the  pattern  and
                 each  subject line must be valid strings of UTF-8 characters.

       -V        Write the version numbers of pcregrep and  the  PCRE  library
                 that is being used to the standard error stream.

       -v        Invert  the  sense  of  the match, so that lines which do not
                 match the pattern are the ones that are found.

       -w        Force the pattern to match only whole words. This is  equiva-
                 lent to having \b at the start and end of the pattern.

       -x        Force  the  pattern to be anchored (it must start matching at
                 the beginning of the line) and in  addition,  require  it  to
                 match  the  entire line. This is equivalent to having ^ and $
                 characters at the start and end of each alternative branch in
                 the regular expression.


LONG OPTIONS

       Long  forms  of all the options are available, as in GNU grep. They are
       shown in the following table:

         -A   --after-context
         -B   --before-context
         -C   --context
         -c   --count
              --exclude (no short form)
         -f   --file
         -h   --no-filename
              --help (no short form)
         -i   --ignore-case
              --include (no short form)
         -L   --files-without-match
         -l   --files-with-matches
              --label (no short form)
         -n   --line-number
         -r   --recursive
         -q   --quiet
         -s   --no-messages
         -u   --utf-8
         -V   --version
         -v   --invert-match
         -x   --line-regex
         -x   --line-regexp


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 = character, or it may appear in the next
       command line item. For example:

         --file=/some/file
         --file /some/file


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). Using the  -s  option  to  suppress
       error messages about inaccessble files does not affect the return code.


AUTHOR

       Philip Hazel
       University Computing Service
       Cambridge CB2 3QG, England.

Last updated: 16 May 2005
Copyright (c) 1997-2005 University of Cambridge.
