6 |
pcregrep - a grep with Perl-compatible regular expressions. |
pcregrep - a grep with Perl-compatible regular expressions. |
7 |
|
|
8 |
SYNOPSIS |
SYNOPSIS |
9 |
pcregrep [-Vcfhilnrsuvx] [long options] [pattern] [file1 file2 ...] |
pcregrep [options] [long options] [pattern] [file1 file2 ...] |
10 |
|
|
11 |
|
|
12 |
DESCRIPTION |
DESCRIPTION |
20 |
A pattern must be specified on the command line unless the -f option is |
A pattern must be specified on the command line unless the -f option is |
21 |
used (see below). |
used (see below). |
22 |
|
|
23 |
If no files are specified, pcregrep reads the standard input. By |
If no files are specified, pcregrep reads the standard input. The stan- |
24 |
default, each line that matches the pattern is copied to the standard |
dard input can also be referenced by a name consisting of a single |
25 |
output, and if there is more than one file, the file name is printed |
hyphen. For example: |
26 |
before each line of output. However, there are options that can change |
|
27 |
how pcregrep behaves. |
pcregrep some-pattern /file1 - /file3 |
28 |
|
|
29 |
Lines are limited to BUFSIZ characters. BUFSIZ is defined in <stdio.h>. |
By default, each line that matches the pattern is copied to the stan- |
30 |
The newline character is removed from the end of each line before it is |
dard output, and if there is more than one file, the file name is |
31 |
matched against the pattern. |
printed before each line of output. However, there are options that can |
32 |
|
change how pcregrep behaves. In particular, the -M option makes it pos- |
33 |
|
sible to search for patterns that span line boundaries. |
34 |
|
|
35 |
|
Patterns are limited to 8K or BUFSIZ characters, whichever is the |
36 |
|
greater. BUFSIZ is defined in <stdio.h>. |
37 |
|
|
|
OPTIONS |
|
38 |
|
|
39 |
|
OPTIONS |
40 |
|
|
41 |
-V Write the version number of the PCRE library being used to |
-- This terminate the list of options. It is useful if the next |
42 |
the standard error stream. |
item on the command line starts with a hyphen, but is not an |
43 |
|
option. |
44 |
|
|
45 |
|
-A number Print number lines of context after each matching line. If |
46 |
|
file names and/or line numbers are being printed, a hyphen |
47 |
|
separator is used instead of a colon for the context lines. A |
48 |
|
line containing "--" is printed between each group of lines, |
49 |
|
unless they are in fact contiguous in the input file. The |
50 |
|
value of number is expected to be relatively small. However, |
51 |
|
pcregrep guarantees to have up to 8K of following text avail- |
52 |
|
able for context printing. |
53 |
|
|
54 |
|
-B number Print number lines of context before each matching line. If |
55 |
|
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 |
|
line containing "--" is printed between each group of lines, |
58 |
|
unless they are in fact contiguous in the input file. The |
59 |
|
value of number is expected to be relatively small. However, |
60 |
|
pcregrep guarantees to have up to 8K of preceding text avail- |
61 |
|
able for context printing. |
62 |
|
|
63 |
|
-C number Print number lines of context both before and after each |
64 |
|
matching line. This is equivalent to setting both -A and -B |
65 |
|
to the same value. |
66 |
|
|
67 |
-c Do not print individual lines; instead just print a count of |
-c Do not print individual lines; instead just print a count of |
68 |
the number of lines that would otherwise have been printed. |
the number of lines that would otherwise have been printed. |
69 |
If several files are given, a count is printed for each of |
If several files are given, a count is printed for each of |
70 |
them. |
them. |
71 |
|
|
72 |
|
--exclude=pattern |
73 |
|
When pcregrep is searching the files in a directory as a con- |
74 |
|
sequence of the -r (recursive search) option, any files whose |
75 |
|
names match the pattern are excluded. The pattern is a PCRE |
76 |
|
regular expression. If a file name matches both --include and |
77 |
|
--exclude, it is excluded. There is no short form for this |
78 |
|
option. |
79 |
|
|
80 |
-ffilename |
-ffilename |
81 |
Read a number of patterns from the file, one per line, and |
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- |
match all of them against each line of input. A line is out- |
83 |
put if any of the patterns match it. When -f is used, no |
put if any of the patterns match it. When -f is used, no |
84 |
pattern is taken from the command line; all arguments are |
pattern is taken from the command line; all arguments are |
85 |
treated as file names. There is a maximum of 100 patterns. |
treated as file names. There is a maximum of 100 patterns. |
86 |
Trailing white space is removed, and blank lines are ignored. |
Trailing white space is removed, and blank lines are ignored. |
87 |
An empty file contains no patterns and therefore matches |
An empty file contains no patterns and therefore matches |
88 |
nothing. |
nothing. |
89 |
|
|
90 |
-h Suppress printing of filenames when searching multiple files. |
-h Suppress printing of filenames when searching multiple files. |
91 |
|
|
92 |
-i Ignore upper/lower case distinctions during comparisons. |
-i Ignore upper/lower case distinctions during comparisons. |
93 |
|
|
94 |
-l Instead of printing lines from the files, just print the |
--include=pattern |
95 |
names of the files containing lines that would have been |
When pcregrep is searching the files in a directory as a con- |
96 |
printed. Each file name is printed once, on a separate line. |
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. |
-n Precede each line by its line number in the file. |
131 |
|
|
132 |
-r If any file is a directory, recursively scan the files it |
-q Work quietly, that is, display nothing except error messages. |
133 |
contains. Without -r a directory is scanned as a normal file. |
The exit status indicates whether or not any matches were |
|
|
|
|
-s Work silently, that is, display nothing except error mes- |
|
|
sages. The exit status indicates whether any matches were |
|
134 |
found. |
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 |
-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 |
has been compiled with UTF-8 support. Both the pattern and |
146 |
each subject line must be valid strings of UTF-8 characters. |
each subject line must be valid strings of UTF-8 characters. |
147 |
|
|
148 |
-v Invert the sense of the match, so that lines which do not |
-V Write the version numbers of pcregrep and the PCRE library |
149 |
match the pattern are now the ones that are found. |
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 |
-x Force the pattern to be anchored (it must start matching at |
158 |
the beginning of the line) and in addition, require it to |
the beginning of the line) and in addition, require it to |
166 |
Long forms of all the options are available, as in GNU grep. They are |
Long forms of all the options are available, as in GNU grep. They are |
167 |
shown in the following table: |
shown in the following table: |
168 |
|
|
169 |
|
-A --after-context |
170 |
|
-B --before-context |
171 |
|
-C --context |
172 |
-c --count |
-c --count |
173 |
|
--exclude (no short form) |
174 |
|
-f --file |
175 |
-h --no-filename |
-h --no-filename |
176 |
|
--help (no short form) |
177 |
-i --ignore-case |
-i --ignore-case |
178 |
|
--include (no short form) |
179 |
|
-L --files-without-match |
180 |
-l --files-with-matches |
-l --files-with-matches |
181 |
|
--label (no short form) |
182 |
-n --line-number |
-n --line-number |
183 |
-r --recursive |
-r --recursive |
184 |
|
-q --quiet |
185 |
-s --no-messages |
-s --no-messages |
186 |
-u --utf-8 |
-u --utf-8 |
187 |
-V --version |
-V --version |
189 |
-x --line-regex |
-x --line-regex |
190 |
-x --line-regexp |
-x --line-regexp |
191 |
|
|
192 |
In addition, --file=filename is equivalent to -ffilename, and --help |
|
193 |
shows the list of options and then exits. |
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 |
|
--file=/some/file |
207 |
|
--file /some/file |
208 |
|
|
209 |
|
|
210 |
DIAGNOSTICS |
DIAGNOSTICS |
211 |
|
|
212 |
Exit status is 0 if any matches were found, 1 if no matches were found, |
Exit status is 0 if any matches were found, 1 if no matches were found, |
213 |
and 2 for syntax errors or inacessible files (even if matches were |
and 2 for syntax errors and non-existent or inacessible files (even if |
214 |
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: 09 September 2004 |
Last updated: 16 May 2005 |
225 |
Copyright (c) 1997-2004 University of Cambridge. |
Copyright (c) 1997-2005 University of Cambridge. |