/[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 - (show annotations)
Sat Feb 24 21:40:45 2007 UTC (8 years, 5 months ago) by nigel
File MIME type: text/html
File size: 9874 byte(s)
Error occurred while calculating annotation data.
Load pcre-6.0 into code/trunk.
1 <html>
2 <head>
3 <title>pcregrep specification</title>
4 </head>
5 <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB">
6 <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 <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 <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 </ul>
24 <br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
25 <P>
26 <b>pcregrep [options] [long options] [pattern] [file1 file2 ...]</b>
27 </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 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 </P>
54 <P>
55 Patterns are limited to 8K or BUFSIZ characters, whichever is the greater.
56 BUFSIZ is defined in <b>&#60;stdio.h&#62;</b>.
57 </P>
58 <br><a name="SEC3" href="#TOC1">OPTIONS</a><br>
59 <P>
60 <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 </P>
64 <P>
65 <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 <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 <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 <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 <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 <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 <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 <b>-n</b>
159 Precede each line by its line number in the file.
160 </P>
161 <P>
162 <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 <b>-r</b>
168 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 <b>-r</b> a directory is scanned as a normal file.
171 </P>
172 <P>
173 <b>-s</b>
174 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 </P>
178 <P>
179 <b>-u</b>
180 Operate in UTF-8 mode. This option is available only if PCRE has been compiled
181 with UTF-8 support. Both the pattern and each subject line must be valid
182 strings of UTF-8 characters.
183 </P>
184 <P>
185 <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 <b>-v</b>
191 Invert the sense of the match, so that lines which do <i>not</i> match the
192 pattern are the ones that are found.
193 </P>
194 <P>
195 <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 <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 -A --after-context
212 -B --before-context
213 -C --context
214 -c --count
215 --exclude (no short form)
216 -f --file
217 -h --no-filename
218 --help (no short form)
219 -i --ignore-case
220 --include (no short form)
221 -L --files-without-match
222 -l --files-with-matches
223 --label (no short form)
224 -n --line-number
225 -r --recursive
226 -q --quiet
227 -s --no-messages
228 -u --utf-8
229 -V --version
230 -v --invert-match
231 -x --line-regex
232 -x --line-regexp
233 </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 </pre>
244 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 </P>
253 <br><a name="SEC6" href="#TOC1">DIAGNOSTICS</a><br>
254 <P>
255 Exit status is 0 if any matches were found, 1 if no matches were found, and 2
256 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 </P>
260 <br><a name="SEC7" href="#TOC1">AUTHOR</a><br>
261 <P>
262 Philip Hazel
263 <br>
264 University Computing Service
265 <br>
266 Cambridge CB2 3QG, England.
267 </P>
268 <P>
269 Last updated: 16 May 2005
270 <br>
271 Copyright &copy; 1997-2005 University of Cambridge.
272 <p>
273 Return to the <a href="index.html">PCRE index page</a>.
274 </p>

  ViewVC Help
Powered by ViewVC 1.1.5