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

Contents of /code/trunk/doc/html/pcregrep.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 77 - (hide annotations) (download) (as text)
Sat Feb 24 21:40:45 2007 UTC (7 years, 8 months ago) by nigel
File MIME type: text/html
File size: 9874 byte(s)
Load pcre-6.0 into code/trunk.

1 nigel 63 <html>
2     <head>
3     <title>pcregrep specification</title>
4     </head>
5     <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6 nigel 75 <h1>pcregrep man page</h1>
7     <p>
8     Return to the <a href="index.html">PCRE index page</a>.
9     </p>
10     <p>
11     This page is part of the PCRE HTML documentation. It was generated automatically
12     from the original man page. If there is any nonsense in it, please consult the
13     man page, in case the conversion went wrong.
14     <br>
15 nigel 63 <ul>
16     <li><a name="TOC1" href="#SEC1">SYNOPSIS</a>
17     <li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
18     <li><a name="TOC3" href="#SEC3">OPTIONS</a>
19     <li><a name="TOC4" href="#SEC4">LONG OPTIONS</a>
20 nigel 77 <li><a name="TOC5" href="#SEC5">OPTIONS WITH DATA</a>
21     <li><a name="TOC6" href="#SEC6">DIAGNOSTICS</a>
22     <li><a name="TOC7" href="#SEC7">AUTHOR</a>
23 nigel 63 </ul>
24     <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
25     <P>
26 nigel 77 <b>pcregrep [options] [long options] [pattern] [file1 file2 ...]</b>
27 nigel 63 </P>
28     <br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br>
29     <P>
30     <b>pcregrep</b> searches files for character patterns, in the same way as other
31     grep commands do, but it uses the PCRE regular expression library to support
32     patterns that are compatible with the regular expressions of Perl 5. See
33     <a href="pcrepattern.html"><b>pcrepattern</b></a>
34     for a full description of syntax and semantics of the regular expressions that
35     PCRE supports.
36     </P>
37     <P>
38     A pattern must be specified on the command line unless the <b>-f</b> option is
39     used (see below).
40     </P>
41     <P>
42 nigel 77 If no files are specified, <b>pcregrep</b> reads the standard input. The
43     standard input can also be referenced by a name consisting of a single hyphen.
44     For example:
45     <pre>
46     pcregrep some-pattern /file1 - /file3
47     </pre>
48     By default, each line that matches the pattern is copied to the standard
49     output, and if there is more than one file, the file name is printed before
50     each line of output. However, there are options that can change how
51     <b>pcregrep</b> behaves. In particular, the <b>-M</b> option makes it possible to
52     search for patterns that span line boundaries.
53 nigel 63 </P>
54     <P>
55 nigel 77 Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.
56     BUFSIZ is defined in <b>&#60;stdio.h&#62;</b>.
57 nigel 63 </P>
58     <br><a name="SEC3" href="#TOC1">OPTIONS</a><br>
59     <P>
60 nigel 77 <b>--</b>
61     This terminate the list of options. It is useful if the next item on the
62     command line starts with a hyphen, but is not an option.
63 nigel 63 </P>
64     <P>
65 nigel 77 <b>-A</b> <i>number</i>
66     Print <i>number</i> lines of context after each matching line. If file names
67     and/or line numbers are being printed, a hyphen separator is used instead of a
68     colon for the context lines. A line containing "--" is printed between each
69     group of lines, unless they are in fact contiguous in the input file. The value
70     of <i>number</i> is expected to be relatively small. However, <b>pcregrep</b>
71     guarantees to have up to 8K of following text available for context printing.
72     </P>
73     <P>
74     <b>-B</b> <i>number</i>
75     Print <i>number</i> lines of context before each matching line. If file names
76     and/or line numbers are being printed, a hyphen separator is used instead of a
77     colon for the context lines. A line containing "--" is printed between each
78     group of lines, unless they are in fact contiguous in the input file. The value
79     of <i>number</i> is expected to be relatively small. However, <b>pcregrep</b>
80     guarantees to have up to 8K of preceding text available for context printing.
81     </P>
82     <P>
83     <b>-C</b> <i>number</i>
84     Print <i>number</i> lines of context both before and after each matching line.
85     This is equivalent to setting both <b>-A</b> and <b>-B</b> to the same value.
86     </P>
87     <P>
88 nigel 63 <b>-c</b>
89     Do not print individual lines; instead just print a count of the number of
90     lines that would otherwise have been printed. If several files are given, a
91     count is printed for each of them.
92     </P>
93     <P>
94 nigel 77 <b>--exclude</b>=<i>pattern</i>
95     When <b>pcregrep</b> is searching the files in a directory as a consequence of
96     the <b>-r</b> (recursive search) option, any files whose names match the pattern
97     are excluded. The pattern is a PCRE regular expression. If a file name matches
98     both <b>--include</b> and <b>--exclude</b>, it is excluded. There is no short
99     form for this option.
100     </P>
101     <P>
102 nigel 63 <b>-f</b><i>filename</i>
103     Read a number of patterns from the file, one per line, and match all of them
104     against each line of input. A line is output if any of the patterns match it.
105     When <b>-f</b> is used, no pattern is taken from the command line; all arguments
106     are treated as file names. There is a maximum of 100 patterns. Trailing white
107     space is removed, and blank lines are ignored. An empty file contains no
108     patterns and therefore matches nothing.
109     </P>
110     <P>
111     <b>-h</b>
112     Suppress printing of filenames when searching multiple files.
113     </P>
114     <P>
115     <b>-i</b>
116     Ignore upper/lower case distinctions during comparisons.
117     </P>
118     <P>
119 nigel 77 <b>--include</b>=<i>pattern</i>
120     When <b>pcregrep</b> is searching the files in a directory as a consequence of
121     the <b>-r</b> (recursive search) option, only files whose names match the
122     pattern are included. The pattern is a PCRE regular expression. If a file name
123     matches both <b>--include</b> and <b>--exclude</b>, it is excluded. There is no
124     short form for this option.
125     </P>
126     <P>
127     <b>-L</b>
128     Instead of printing lines from the files, just print the names of the files
129     that do not contain any lines that would have been printed. Each file name is
130     printed once, on a separate line.
131     </P>
132     <P>
133 nigel 63 <b>-l</b>
134     Instead of printing lines from the files, just print the names of the files
135     containing lines that would have been printed. Each file name is printed
136     once, on a separate line.
137     </P>
138     <P>
139 nigel 77 <b>--label</b>=<i>name</i>
140     This option supplies a name to be used for the standard input when file names
141     are being printed. If not supplied, "(standard input)" is used. There is no
142     short form for this option.
143     </P>
144     <P>
145     <b>-M</b>
146     Allow patterns to match more than one line. When this option is given, patterns
147     may usefully contain literal newline characters and internal occurrences of ^
148     and $ characters. The output for any one match may consist of more than one
149     line. When this option is set, the PCRE library is called in "multiline" mode.
150     There is a limit to the number of lines that can be matched, imposed by the way
151     that <b>pcregrep</b> buffers the input file as it scans it. However,
152     <b>pcregrep</b> ensures that at least 8K characters or the rest of the document
153     (whichever is the shorter) are available for forward matching, and similarly
154     the previous 8K characters (or all the previous characters, if fewer than 8K)
155     are guaranteed to be available for lookbehind assertions.
156     </P>
157     <P>
158 nigel 63 <b>-n</b>
159     Precede each line by its line number in the file.
160     </P>
161     <P>
162 nigel 77 <b>-q</b>
163     Work quietly, that is, display nothing except error messages.
164     The exit status indicates whether or not any matches were found.
165     </P>
166     <P>
167 nigel 63 <b>-r</b>
168 nigel 77 If any given path is a directory, recursively scan the files it contains,
169     taking note of any <b>--include</b> and <b>--exclude</b> settings. Without
170 nigel 63 <b>-r</b> a directory is scanned as a normal file.
171     </P>
172     <P>
173     <b>-s</b>
174 nigel 77 Suppress error messages about non-existent or unreadable files. Such files are
175     quietly skipped. However, the return code is still 2, even if matches were
176     found in other files.
177 nigel 63 </P>
178     <P>
179     <b>-u</b>
180     Operate in UTF-8 mode. This option is available only if PCRE has been compiled
181 nigel 75 with UTF-8 support. Both the pattern and each subject line must be valid
182     strings of UTF-8 characters.
183 nigel 63 </P>
184     <P>
185 nigel 77 <b>-V</b>
186     Write the version numbers of <b>pcregrep</b> and the PCRE library that is being
187     used to the standard error stream.
188     </P>
189     <P>
190 nigel 63 <b>-v</b>
191     Invert the sense of the match, so that lines which do <i>not</i> match the
192 nigel 77 pattern are the ones that are found.
193 nigel 63 </P>
194     <P>
195 nigel 77 <b>-w</b>
196     Force the pattern to match only whole words. This is equivalent to having \b
197     at the start and end of the pattern.
198     </P>
199     <P>
200 nigel 63 <b>-x</b>
201     Force the pattern to be anchored (it must start matching at the beginning of
202     the line) and in addition, require it to match the entire line. This is
203     equivalent to having ^ and $ characters at the start and end of each
204     alternative branch in the regular expression.
205     </P>
206     <br><a name="SEC4" href="#TOC1">LONG OPTIONS</a><br>
207     <P>
208     Long forms of all the options are available, as in GNU grep. They are shown in
209     the following table:
210     <pre>
211 nigel 77 -A --after-context
212     -B --before-context
213     -C --context
214 nigel 63 -c --count
215 nigel 77 --exclude (no short form)
216     -f --file
217 nigel 63 -h --no-filename
218 nigel 77 --help (no short form)
219 nigel 63 -i --ignore-case
220 nigel 77 --include (no short form)
221     -L --files-without-match
222 nigel 63 -l --files-with-matches
223 nigel 77 --label (no short form)
224 nigel 63 -n --line-number
225     -r --recursive
226 nigel 77 -q --quiet
227 nigel 63 -s --no-messages
228     -u --utf-8
229     -V --version
230     -v --invert-match
231     -x --line-regex
232     -x --line-regexp
233 nigel 77 </PRE>
234     </P>
235     <br><a name="SEC5" href="#TOC1">OPTIONS WITH DATA</a><br>
236     <P>
237     There are four different ways in which an option with data can be specified.
238     If a short form option is used, the data may follow immediately, or in the next
239     command line item. For example:
240     <pre>
241     -f/some/file
242     -f /some/file
243 nigel 75 </pre>
244 nigel 77 If a long form option is used, the data may appear in the same command line
245     item, separated by an = character, or it may appear in the next command line
246     item. For example:
247     <pre>
248     --file=/some/file
249     --file /some/file
250    
251     </PRE>
252 nigel 63 </P>
253 nigel 77 <br><a name="SEC6" href="#TOC1">DIAGNOSTICS</a><br>
254 nigel 63 <P>
255     Exit status is 0 if any matches were found, 1 if no matches were found, and 2
256 nigel 77 for syntax errors and non-existent or inacessible files (even if matches were
257     found in other files). Using the <b>-s</b> option to suppress error messages
258     about inaccessble files does not affect the return code.
259 nigel 63 </P>
260 nigel 77 <br><a name="SEC7" href="#TOC1">AUTHOR</a><br>
261 nigel 63 <P>
262 nigel 77 Philip Hazel
263 nigel 63 <br>
264     University Computing Service
265     <br>
266     Cambridge CB2 3QG, England.
267     </P>
268     <P>
269 nigel 77 Last updated: 16 May 2005
270 nigel 63 <br>
271 nigel 77 Copyright &copy; 1997-2005 University of Cambridge.
272 nigel 75 <p>
273     Return to the <a href="index.html">PCRE index page</a>.
274     </p>

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12