/[pcre]/code/trunk/doc/pcregrep.txt
ViewVC logotype

Diff of /code/trunk/doc/pcregrep.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 63 by nigel, Sat Feb 24 21:40:03 2007 UTC revision 77 by nigel, Sat Feb 24 21:40:45 2007 UTC
# Line 1  Line 1 
1  NAME  PCREGREP(1)                                                        PCREGREP(1)
2       pcregrep - a grep with Perl-compatible regular expressions.  
3    
4    
5    NAME
6           pcregrep - a grep with Perl-compatible regular expressions.
7    
8  SYNOPSIS  SYNOPSIS
9       pcregrep [-Vcfhilnrsuvx] [long options] [pattern] [file1         pcregrep [options] [long options] [pattern] [file1 file2 ...]
10    
11    
12  DESCRIPTION  DESCRIPTION
13    
14       pcregrep searches files for character patterns, in the  same         pcregrep  searches  files  for  character  patterns, in the same way as
15       way  as other grep commands do, but it uses the PCRE regular         other grep commands do, but it uses the PCRE regular expression library
16       expression library to support patterns that  are  compatible         to support patterns that are compatible with the regular expressions of
17       with  the regular expressions of Perl 5. See pcrepattern for         Perl 5. See pcrepattern for a full description of syntax and  semantics
18       a full description of syntax and semantics  of  the  regular         of the regular expressions that PCRE supports.
19       expressions that PCRE supports.  
20           A pattern must be specified on the command line unless the -f option is
21       A pattern must be specified on the command line  unless  the         used (see below).
22       -f option is used (see below).  
23           If no files are specified, pcregrep reads the standard input. The stan-
24       If no files  are  specified,  pcregrep  reads  the  standard         dard  input  can  also  be  referenced by a name consisting of a single
25       input.  By  default,  each  line that matches the pattern is         hyphen.  For example:
26       copied to the standard output, and if there is more than one  
27       file,  the  file name is printed before each line of output.           pcregrep some-pattern /file1 - /file3
28       However, there are options  that  can  change  how  pcregrep  
29       behaves.         By default, each line that matches the pattern is copied to  the  stan-
30           dard  output,  and  if  there  is  more than one file, the file name is
31       Lines are limited to BUFSIZ characters. BUFSIZ is defined in         printed before each line of output. However, there are options that can
32       <stdio.h>.  The newline character is removed from the end of         change how pcregrep behaves. In particular, the -M option makes it pos-
33       each line before it is matched against the pattern.         sible to search for patterns that span line boundaries.
34    
35           Patterns are limited to 8K  or  BUFSIZ  characters,  whichever  is  the
36  OPTIONS         greater.  BUFSIZ is defined in <stdio.h>.
37    
38    
39       -V        Write the version number of the PCRE library being  OPTIONS
                used to the standard error stream.  
40    
41       -c        Do not print individual lines; instead just  print         --        This  terminate the list of options. It is useful if the next
42                 a  count  of the number of lines that would other-                   item on the command line starts with a hyphen, but is not  an
43                 wise have  been  printed.  If  several  files  are                   option.
44                 given, a count is printed for each of them.  
45           -A number Print  number  lines  of context after each matching line. If
46       -ffilename                   file names and/or line numbers are being  printed,  a  hyphen
47                 Read a number of patterns from the file,  one  per                   separator is used instead of a colon for the context lines. A
48                 line,  and  match all of them against each line of                   line containing "--" is printed between each group of  lines,
49                 input. A line is output if  any  of  the  patterns                   unless  they  are  in  fact contiguous in the input file. The
50                 match  it.   When  -f is used, no pattern is taken                   value of number is expected to be relatively small.  However,
51                 from the command line; all arguments  are  treated                   pcregrep guarantees to have up to 8K of following text avail-
52                 as file names. There is a maximum of 100 patterns.                   able for context printing.
53                 Trailing white space is removed, and  blank  lines  
54                 are  ignored.  An  empty file contains no patterns         -B number Print number lines of context before each matching  line.  If
55                 and therefore matches nothing.                   file  names  and/or  line numbers are being printed, a hyphen
56                     separator is used instead of a colon for the context lines. A
57       -h        Suppress printing of filenames when searching mul-                   line  containing "--" is printed between each group of lines,
58                 tiple files.                   unless they are in fact contiguous in  the  input  file.  The
59                     value  of number is expected to be relatively small. However,
60       -i        Ignore upper/lower case distinctions  during  com-                   pcregrep guarantees to have up to 8K of preceding text avail-
61                 parisons.                   able for context printing.
62    
63       -l        Instead of printing lines  from  the  files,  just         -C number Print  number  lines  of  context  both before and after each
64                 print the names of the files containing lines that                   matching line.  This is equivalent to setting both -A and  -B
65                 would have been printed. Each file name is printed                   to the same value.
66                 once, on a separate line.  
67           -c        Do  not print individual lines; instead just print a count of
68       -n        Precede each line by its line number in the file.                   the number of lines that would otherwise have  been  printed.
69                     If  several  files  are given, a count is printed for each of
70       -r        If any file is a directory, recursively  scan  the                   them.
71                 files  it  contains.  Without  -r  a  directory is  
72                 scanned as a normal file.         --exclude=pattern
73                     When pcregrep is searching the files in a directory as a con-
74       -s        Work silently, that  is,  display  nothing  except                   sequence of the -r (recursive search) option, any files whose
75                 error messages.  The exit status indicates whether                   names match the pattern are excluded. The pattern is  a  PCRE
76                 any matches were found.                   regular expression. If a file name matches both --include and
77                     --exclude, it is excluded. There is no short  form  for  this
78       -u        Operate in UTF-8 mode. This  option  is  available                   option.
79                 only if PCRE has been compiled with UTF-8 support.  
80                 Both the pattern and each subject line are assumed         -ffilename
81                 to be valid strings of UTF-8 characters.                   Read  a  number  of patterns from the file, one per line, and
82                     match all of them against each line of input. A line is  out-
83       -v        Invert the sense of the match, so that lines which                   put  if  any  of  the patterns match it.  When -f is used, no
84                 do not match the pattern are now the ones that are                   pattern is taken from the command  line;  all  arguments  are
85                 found.                   treated  as  file  names. There is a maximum of 100 patterns.
86                     Trailing white space is removed, and blank lines are ignored.
87       -x        Force the pattern to be anchored  (it  must  start                   An  empty  file  contains  no  patterns and therefore matches
88                 matching  at  the  beginning  of  the line) and in                   nothing.
89                 addition, require it to  match  the  entire  line.  
90                 This is equivalent to having ^ and $ characters at         -h        Suppress printing of filenames when searching multiple files.
91                 the start and end of each  alternative  branch  in  
92                 the regular expression.         -i        Ignore upper/lower case distinctions during comparisons.
93    
94           --include=pattern
95                     When pcregrep is searching the files in a directory as a con-
96                     sequence of the -r  (recursive  search)  option,  only  files
97                     whose  names match the pattern are included. The pattern is a
98                     PCRE  regular  expression.  If  a  file  name  matches   both
99                     --include  and  --exclude,  it is excluded. There is no short
100                     form for this option.
101    
102           -L        Instead of printing lines from  the  files,  just  print  the
103                     names  of  the files that do not contain any lines that would
104                     have been printed. Each file name is printed once, on a sepa-
105                     rate line.
106    
107           -l        Instead  of  printing  lines  from  the files, just print the
108                     names of the files containing  lines  that  would  have  been
109                     printed.  Each file name is printed once, on a separate line.
110    
111           --label=name
112                     This option supplies a name to be used for the standard input
113                     when  file  names are being printed. If not supplied, "(stan-
114                     dard input)" is used. There is no short form for this option.
115    
116           -M        Allow  patterns to match more than one line. When this option
117                     is given, patterns may usefully contain literal newline char-
118                     acters  and  internal  occurrences of ^ and $ characters. The
119                     output for any one match may consist of more than  one  line.
120                     When  this option is set, the PCRE library is called in "mul-
121                     tiline" mode.  There is a limit to the number of  lines  that
122                     can  be matched, imposed by the way that pcregrep buffers the
123                     input file as it scans it. However, pcregrep ensures that  at
124                     least 8K characters or the rest of the document (whichever is
125                     the shorter) are available for forward  matching,  and  simi-
126                     larly the previous 8K characters (or all the previous charac-
127                     ters, if fewer than 8K) are guaranteed to  be  available  for
128                     lookbehind assertions.
129    
130           -n        Precede each line by its line number in the file.
131    
132           -q        Work quietly, that is, display nothing except error messages.
133                     The exit status indicates whether or  not  any  matches  were
134                     found.
135    
136           -r        If  any given path is a directory, recursively scan the files
137                     it contains, taking note of any --include and --exclude  set-
138                     tings. Without -r a directory is scanned as a normal file.
139    
140           -s        Suppress  error  messages  about  non-existent  or unreadable
141                     files. Such files are quietly skipped.  However,  the  return
142                     code is still 2, even if matches were found in other files.
143    
144           -u        Operate  in UTF-8 mode. This option is available only if PCRE
145                     has been compiled with UTF-8 support. Both  the  pattern  and
146                     each  subject line must be valid strings of UTF-8 characters.
147    
148           -V        Write the version numbers of pcregrep and  the  PCRE  library
149                     that is being used to the standard error stream.
150    
151           -v        Invert  the  sense  of  the match, so that lines which do not
152                     match the pattern are the ones that are found.
153    
154           -w        Force the pattern to match only whole words. This is  equiva-
155                     lent to having \b at the start and end of the pattern.
156    
157           -x        Force  the  pattern to be anchored (it must start matching at
158                     the beginning of the line) and in  addition,  require  it  to
159                     match  the  entire line. This is equivalent to having ^ and $
160                     characters at the start and end of each alternative branch in
161                     the regular expression.
162    
163    
164  LONG OPTIONS  LONG OPTIONS
165    
166       Long forms of all the options are available, as in GNU grep.         Long  forms  of all the options are available, as in GNU grep. They are
167       They are shown in the following table:         shown in the following table:
168    
169         -c   --count           -A   --after-context
170         -h   --no-filename           -B   --before-context
171         -i   --ignore-case           -C   --context
172         -l   --files-with-matches           -c   --count
173         -n   --line-number                --exclude (no short form)
174         -r   --recursive           -f   --file
175         -s   --no-messages           -h   --no-filename
176         -u   --utf-8                --help (no short form)
177         -V   --version           -i   --ignore-case
178         -v   --invert-match                --include (no short form)
179         -x   --line-regex           -L   --files-without-match
180         -x   --line-regexp           -l   --files-with-matches
181                  --label (no short form)
182             -n   --line-number
183             -r   --recursive
184             -q   --quiet
185             -s   --no-messages
186             -u   --utf-8
187             -V   --version
188             -v   --invert-match
189             -x   --line-regex
190             -x   --line-regexp
191    
192    
193    OPTIONS WITH DATA
194    
195           There are four different ways in which an option with data can be spec-
196           ified.   If  a  short  form option is used, the data may follow immedi-
197           ately, or in the next command line item. For example:
198    
199             -f/some/file
200             -f /some/file
201    
202           If a long form option is used, the data may appear in the same  command
203           line  item,  separated  by an = character, or it may appear in the next
204           command line item. For example:
205    
206       In addition, --file=filename is  equivalent  to  -ffilename,           --file=/some/file
207       and --help shows the list of options and then exits.           --file /some/file
208    
209    
210  DIAGNOSTICS  DIAGNOSTICS
211    
212       Exit status is 0 if any matches were found, 1 if no  matches         Exit status is 0 if any matches were found, 1 if no matches were found,
213       were  found,  and  2  for syntax errors or inacessible files         and  2 for syntax errors and non-existent or inacessible files (even if
214       (even if matches were found).         matches were found in other files). Using the  -s  option  to  suppress
215           error messages about inaccessble files does not affect the return code.
216    
217    
218  AUTHOR  AUTHOR
219    
220       Philip Hazel <ph10@cam.ac.uk>         Philip Hazel
221       University Computing Service         University Computing Service
222       Cambridge CB2 3QG, England.         Cambridge CB2 3QG, England.
223    
224  Last updated: 03 February 2003  Last updated: 16 May 2005
225  Copyright (c) 1997-2003 University of Cambridge.  Copyright (c) 1997-2005 University of Cambridge.

Legend:
Removed from v.63  
changed lines
  Added in v.77

  ViewVC Help
Powered by ViewVC 1.1.5