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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

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

webmaster@exim.org
ViewVC Help
Powered by ViewVC 1.1.12