Allow to bind to multiple separate addresses.
[privoxy.git] / doc / pcrs.3
1 .\" Copyright (c) 2001-2003 Andreas S. Oesterhelt <oes@oesterhelt.org>
2 .\"
3 .\" This is free documentation; you can redistribute it and/or
4 .\" modify it under the terms of the GNU General Public License as
5 .\" published by the Free Software Foundation; either version 2 of
6 .\" the License, or (at your option) any later version.
7 .\"
8 .\" The GNU General Public License's references to "object code"
9 .\" and "executables" are to be interpreted as the output of any
10 .\" document formatting or typesetting system, including
11 .\" intermediate and printed output.
12 .\"
13 .\" This manual is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 .\" GNU General Public License for more details.
17 .\"
18 .\" You should have received a copy of the GNU General Public
19 .\" License along with this manual; if not, write to the Free
20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
21 .\" MA 02111, USA.
22 .\"
23 .TH PCRS 3 "2 December 2003" "pcrs-0.0.3"
24 .SH NAME
25 pcrs - Perl-compatible regular substitution.
26 .SH SYNOPSIS
27 .br
28 .B "#include <pcrs.h>"
29 .PP
30 .br
31 .BI "pcrs_job *pcrs_compile(const char *" pattern "," 
32 .ti +5n
33 .BI "const char *" substitute ", const char *" options ,
34 .ti +5n
35 .BI "int *" errptr );
36 .PP
37 .br
38 .BI "pcrs_job *pcrs_compile_command(const char *" command ,
39 .ti +5n
40 .BI "int *" errptr );
41 .PP
42 .br
43 .BI "int pcrs_execute(pcrs_job *" job ", char *" subject ,
44 .ti +5n
45 .BI "int " subject_length ", char **" result ,
46 .ti +5n
47 .BI "int *" result_length );
48 .PP
49 .br
50 .BI "int pcrs_execute_list (pcrs_job *" joblist ", char *" subject ,
51 .ti +5n
52 .BI "int " subject_length ", char **" result ,
53 .ti +5n
54 .BI "int *" result_length );
55 .PP
56 .br
57 .BI "pcrs_job *pcrs_free_job(pcrs_job *" job );
58 .PP
59 .br
60 .BI "void pcrs_free_joblist(pcrs_job *" joblist );
61 .PP
62 .br
63 .BI "char *pcrs_strerror(int " err );
64 .PP
65 .br
66
67 .SH DESCRIPTION
68
69 The
70 .SM PCRS
71 library is a supplement to the 
72 .SB PCRE(3)
73 library that implements
74 .RB "regular expression based substitution, like provided by " Perl(1) "'s 's'"
75 operator. It uses the same syntax and semantics as Perl 5, with just a few
76 differences (see below).
77
78 In a first step, the information on a substitution, i.e. the pattern, the
79 substitute and the options are compiled from Perl syntax to an internal form
80 .RB "called " pcrs_job " by using either the " pcrs_compile() " or " 
81 .BR pcrs_compile_command() " functions."
82
83 Once the job is compiled, it can be used on subjects, which are arbitrary 
84 memory areas containing string or binary data, by calling
85 .BR pcrs_execute() ". Jobs can be chained to joblists and whole"
86 .RB "joblists can be applied to a subject using " pcrs_execute_list() .
87
88 There are also convenience functions for freeing the jobs and for errno-to-string
89 .RB "conversion, namely " pcrs_free_job() ", " pcrs_free_joblist() " and "
90 .BR pcrs_strerror() .
91
92 .SH COMPILING JOBS
93
94 .RB "The function " pcrs_compile() " is called to compile a " pcrs_job
95 .RI "from a " pattern ", " substitute " and " options " string."
96 .RB "The resulting " "pcrs_job" " structure is dynamically allocated and it"
97 .RB "is the caller's responsibility to call " "pcrs_free_job()" "  when it's no longer needed."
98
99 .BR "pcrs_compile_command()" " is a convenience wrapper function that parses a Perl"
100 .IR "command" " of the form"
101 .BI "s/" "pattern" "/" "substitute" "/[" "options" "]"
102 .RB "into its components and then calls " "pcrs_compile()" ". As in Perl, you"
103 .RB "are not bound to the '" "/" "' character: Whatever"
104 .RB "follows the '" "s" "' will be used as the delimiter. Patterns or substitutes"
105 that contain the delimiter need to quote it:
106 \fBs/th\\/is/th\\/at/\fR
107 .RB "will replace " "th/is" " by " "th/at" " and can be written more simply as" 
108 .BR "s|th/is|th/at|" "."
109
110 .IR "pattern" ", " "substitute" ", " "options" " and " "command" " must be"
111 .RI "zero-terminated C strings. " "substitute" " and " "options" " may be"
112 .BR "NULL" ", in which case they are treated like the empty string."
113
114 .SS "Return value and diagnostics"
115 On success, both functions return a pointer to the compiled job.
116 .RB "On failure, " "NULL"
117 .RI "is returned. In that case, the pcrs error code is written to *" "err" "."
118
119 .SS Patterns
120 .RI "For the syntax of the " "pattern" ", see the "
121 .BR "PCRE(3)" " manual page."
122
123 .SS Substitutes
124 .RI "The " "substitute" " uses"
125 .RB "Perl syntax as documented in the " "perlre(1)" " manual page, with"
126 some exceptions: 
127
128 Most notably and evidently, since
129 .SM PCRS
130 is not Perl, variable interpolation or Perl command substitution won't work.
131 Special variables that do get interpolated, are:
132 .TP
133 .B "$1, $2, ..., $n"
134 Like in Perl, these variables refer to what the nth capturing subpattern
135 in the pattern matched.
136 .TP
137 .B "$& and $0"
138 .RB "refer to the whole match. Note that " "$0" " is deprecated in recent"
139 Perl versions and now refers to the program name.
140 .TP
141 .B "$+"
142 refers to what the last capturing subpattern matched.
143 .TP
144 .BR "$` and $'" " (backtick and tick)"
145 .RI "refer to the areas of the " "subject" " before and after the match, respectively."
146 .RB "Note that, like in Perl, the " "unmodified" " subject is used, even"
147 if a global substitution previously matched.
148
149 .PP
150 Perl4-style references to subpattern matches of the form 
151 \fB\\1, \\2, ...\fR
152 .RB "which only exist in Perl5 for backwards compatibility, are " "not" 
153 supported.
154
155 Also, since the substitute is a double-quoted string in Perl, you
156 might expect all Perl syntax for special characters to apply. In fact,
157 only the following are supported:
158
159 .TP
160 \fB\\n\fR
161 newline (0x0a)
162 .TP
163 \fB\\r\fR
164 carriage return (0x0d)
165 .TP
166 \fB\\t\fR
167 horizontal tab (0x09)
168 .TP
169 \fB\\f\fR
170 form feed (0x0c)
171 .TP
172 \fB\\b\fR
173 backspace (0x08)
174 .TP
175 \fB\\a\fR
176 alarm, bell (0x07)
177 .TP
178 \fB\\e\fR
179 escape (0x1b)
180 .TP
181 \fB\\0\fR
182 binary zero (0x00)
183
184 .SS "Options"
185 .RB "The options " "gmisx" " are supported. " "e" " is not, since it would"
186 .RB "require a Perl interpreter and neither is " o ", because the pattern
187 is explicitly compiled, anyway. Additionally,
188 .SM PCRS
189 .RB "honors the options " "U" " and " "T" "."
190 Where
191 .SM PCRE
192 .RB "options are mentioned below, refer to " PCRE(3) " for the subtle differences"
193 to Perl behaviour.
194
195 .TP
196 .B g
197 .RB "Replace " all " instances of"
198 .IR pattern " in " subject ,
199 not just the first one.
200
201 .TP
202 .B i
203 .RI "Match the " pattern " without respect to case. This translates to"
204 .SM PCRE_CASELESS.
205
206 .TP
207 .B m
208 .RI "Treat the " subject " as consisting of multiple lines, i.e."
209 .RB ' ^ "' matches immediately after, and '" $ "' immediately before each newline."
210 Translates to
211 .SM PCRE_MULTILINE.
212
213 .TP
214 .B s
215 .RI "Treat the " subject " as consisting of one single line, i.e."
216 .RB "let the scope of the '" . "' metacharacter include newlines."
217 Translates to
218 .SM PCRE_DOTALL.
219
220 .TP
221 .B x
222 .RI "Allow extended regular expression syntax in the " pattern ","
223 .RB "enabling whitespace and comments in complex patterns."
224 Translates to
225 .SM PCRE_EXTENDED.
226
227 .TP
228 .B U
229 .RB "Switch the default behaviour of the '" * "' and '" + "' quantifiers"
230 .RB "to ungreedy. Note that appending a '" ? "' switches back to greedy(!)."
231 .RB "The explicit in-pattern switches " (?U) " and " (?-U) " remain unaffected."
232 Translates to
233 .SM PCRE_UNGREEDY.
234
235 .TP
236 .B T
237 .RI "Consider the " substitute " trivial, i.e. do not interpret any references"
238 or special character escape sequences in the substitute. Handy for large
239 user-supplied substitutes, which would otherwise have to be examined and properly
240 quoted.
241
242 .PP
243 Unsupported options are silently ignored.
244
245 .SH EXECUTING JOBS
246
247 .RI "Calling " pcrs_execute() " produces a modified copy of the " subject ", in which"
248 .RB "the first (or all, if the '" g "' option was given when compiling the job)"
249 .RI "occurance(s) of the job's " pattern " in the " subject " is replaced by the job's"
250 .IR substitute .
251
252 .RI "The first " subject_length " bytes following " subject " are processed, so"
253 .RI  "a " subject_length " that exceeds the actual " subject " is dangerous."
254 .RI "Note that for zero-terminated C strings, you should set " subject_length " to"
255 .BI strlen( subject ) \fR,
256 so that the dollar metacharacter matches at the end of the string, not after
257 the string-terminating null byte. For convenience, an extra null byte is
258 appended to the result so it can again be used as a string.
259
260 .RI "The " subject " itself is left untouched, and the " *result " is dynamically"
261 .RB "allocated, so it is the caller's responsibility to " free() " it when it's"
262 no longer needed.
263
264 .RI "The result's length (excluding the extra null byte) is written to " *result_length "."
265
266 .RB "If the job matched, the " PCRS_SUCCESS " flag in"
267 .IB job ->flags
268 is set.
269
270
271 .SS String subjects
272 If your 
273
274 .SS Return value and diagnostics
275
276 .RB "On success, " pcrs_execute() " returns the number of substitutions that"
277 were made, which is limited to 0 or 1 for non-global searches.
278 .RI "On failure, a negative error code is returned and " result " is set"
279 .RB "to " NULL .
280
281 .SH FREEING JOBS
282 .RB "It is not sufficient to call " free() " on a " pcrs_job ", because it "
283 contains pointers to other dynamically allocated structures.
284 .RB "Use " pcrs_free_job() " instead. It is safe to pass " NULL " pointers "
285 .RB "(or pointers to invalid " pcrs_job "s that contain " NULL " pointers"
286 .RB "to dependant structures) to " pcrs_free_job() "."
287
288 .SS Return value
289 .RB "The value of the job's " next " pointer."
290
291
292 .SH CHAINING JOBS
293
294 .SM PCRS
295 .RB "supports to some extent the chaining of multiple " pcrs_job " structures by"
296 .RB "means of their " next " member."
297
298 Chaining the jobs is up to you, but once you have built a linked list of jobs,
299 .RI "you can execute a whole " joblist " on a given subject by"
300 .RB "a single call to " pcrs_execute_list() ", which will sequentially traverse"
301 .RB "the linked list until it reaches a " NULL " pointer, and call " pcrs_execute() 
302 .RI "for each job it encounters, feeding the " result  " and " result_length " of each"
303 .RI "call into the next as the " subject " and " subject_length ". As in the single"
304 .RI "job case, the original " subject " remains untouched, but all interim " result "s"
305 .RB "are of course " free() "d. The return value is the accumulated number of matches"
306 .RI "for all jobs in the " joblist "."
307 .RI "Note that while this is handy, it reduces the diagnostic value of " err ", since "
308 you won't know which job failed.
309
310 .RI "In analogy, you can free all jobs in a given " joblist " by calling"
311 .BR pcrs_free_joblist() .
312
313 .SH QUOTING
314 The quote character is (surprise!) '\fB\\\fR'. It quotes the delimiter in a
315 .IR command ", the"
316 .RB ' $ "' in  a"
317 .IR substitute ", and, of course, itself. Note that the"
318 .RB ' $ "' doesn't need to be quoted if it isn't followed by " [0-9+'`&] "."
319
320 .RI "For quoting in the " pattern ", please refer to"
321 .BR PCRE(3) .
322
323 .SH DIAGNOSTICS
324
325 .RB "When " compiling " a job either via the " pcrs_compile() " or " pcrs_compile_command()
326 .RB "functions, you know that something went wrong when you are returned a " NULL " pointer."
327 .RI "In that case, or in the event of non-fatal warnings, the integer pointed to by " err
328 contains a nonzero error code, which is either a passed-through
329 .SM PCRE
330 error code or one generated by
331 .SM PCRS.
332 Under normal circumstances, it can take the following values:
333 .TP
334 .B PCRE_ERROR_NOMEMORY
335 While compiling the pattern,
336 .SM PCRE
337 ran out of memory.
338 .TP  
339 .B  PCRS_ERR_NOMEM
340 While compiling the job,
341 .SM PCRS
342 ran out of memory.
343 .TP  
344 .B  PCRS_ERR_CMDSYNTAX
345 .BR pcrs_compile_command() " didn't find four tokens while parsing the"
346 .IR command .
347 .TP  
348 .B  PCRS_ERR_STUDY
349 A
350 .SM PCRE
351 .RB "error occured while studying the compiled pattern. Since " pcre_study()
352 only provides textual diagnostic information, the details are lost.
353 .TP  
354 .B  PCRS_WARN_BADREF
355 .RI "The " substitute " contains a reference to a capturing subpattern that"
356 .RI "has a higher index than the number of capturing subpatterns in the " pattern
357 or that exceeds the current hard limit of 33 (See LIMITATIONS below). As in Perl,
358 this is non-fatal and results in substitutions with the empty string.
359
360 .PP
361 .RB "When " executing " jobs via " pcrs_execute() " or " pcrs_execute_list() ","
362 .RI "a negative return code indicates an error. In that case, *" result
363 .RB "is " NULL ". Possible error codes are:"
364 .TP
365 .B PCRE_ERROR_NOMEMORY
366 While matching the pattern,
367 .SM PCRE
368 ran out of memory. This can only happen if there are more than 33 backrefrences
369 .RI "in the " pattern "(!)"
370 .BR and " memory is too tight to extend storage for more."
371 .TP  
372 .B  PCRS_ERR_NOMEM
373 While executing the job,
374 .SM PCRS
375 ran out of memory.
376 .TP  
377 .B  PCRS_ERR_BADJOB
378 .RB "The " pcrs_job "*  passed to " pcrs_execute " was NULL, or the"
379 .RB "job is bogus (it contains " NULL " pointers to the compiled
380 pattern, extra, or substitute).
381
382 .PP
383 If you see any other
384 .SM PCRE
385 error code passed through, you've either messed with the compiled job
386 or found a bug in
387 .SM PCRS.
388 Please send me an email.
389
390 .RB "Ah, and don't look for " PCRE_ERROR_NOMATCH ", since this"
391 is not an error in the context of
392 .SM PCRS.
393 .RI "Should there be no match, an exact copy of the " subject " is"
394 .RI "found at *" result " and the return code is 0 (matches)."
395
396 All error codes can be translated into human readable text by means
397 .RB "of the " pcrs_strerror() " function."
398
399
400 .SH EXAMPLE
401 A trivial command-line test program for
402 .SM PCRS
403 might look like:
404
405 .nf
406 #include <pcrs.h>
407 #include <stdio.h>
408
409 int main(int Argc, char **Argv)
410 {
411    pcrs_job *job;
412    char *result;
413    size_t newsize;
414    int err;
415
416    if (Argc != 3)
417    {
418       fprintf(stderr, "Usage: %s s/pattern/substitute/[options]  subject\\n", Argv[0]);
419       return 1;
420    }
421
422    if (NULL == (job = pcrs_compile_command(Argv[1], &err)))
423    {
424       fprintf(stderr, "%s: compile error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);
425    }
426
427    if (0 > (err = pcrs_execute(job, Argv[2], strlen(Argv[2]), &result, &newsize)))
428    {
429       fprintf(stderr, "%s: exec error:  %s (%d).\\n", Argv[0], pcrs_strerror(err), err);
430    }
431    else
432    {
433       printf("Result: *%s*\\n", result);
434       free(result);
435    }
436
437    pcrs_free_job(job);
438    return(err < 0);
439
440 }
441
442 .fi
443
444
445 .SH LIMITATIONS
446 The number of matches that a global job can have is only limited by the
447 available memory. An initial storage for 40 matches is reserved, which
448 is dynamically resized by the factor 1.6 whenever it is exhausted.
449
450 The number of capturing subpatterns is currently limited to 33, which
451 is a Bad Thing[tm]. It should be dynamically expanded until it reaches the
452 .SM PCRE
453 limit of 99.
454 .br
455 This limitation is particularly embarassing since
456 .SM PCRE
457 3.5 has raised the capturing subpattern limit to 65K.
458
459 All of the above values can be adjusted in the "Capacity" section
460 .RB "of " pcrs.h "."
461
462 The Perl-style escape sequences for special characters \\\fInnn\fR,
463 \\x\fInn\fR, and \\c\fIX\fR are currently unsupported.
464
465 .SH BUGS
466 This library has only been tested in the context of one application
467 and should be considered high risk.
468
469 .SH HISTORY
470 .SM PCRS
471 was originally written for the Privoxy project
472 (http://www.privoxy.org/).
473
474 .SH SEE ALSO
475 .B PCRE(3), perl(1), perlre(1)
476
477 .SH AUTHOR
478
479 .SM PCRS
480 is Copyright 2000 - 2003 by Andreas Oesterhelt <andreas@oesterhelt.org> and is
481 licensed under the terms of the GNU Lesser General Public License (LGPL),
482 version 2.1, which should be included in this distribution, with the exception
483 that the permission to replace that license with the GNU General Public
484 License (GPL) given in section 3 is restricted to version 2 of the GPL.
485
486 If it is missing from this distribution, the LGPL can be obtained from
487 http://www.gnu.org/licenses/lgpl.html or by mail: Write to the Free Software
488 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.