143 lines
5.3 KiB
Groff
143 lines
5.3 KiB
Groff
.TH PCREPRECOMPILE 3
|
|
.SH NAME
|
|
PCRE - Perl-compatible regular expressions
|
|
.SH "SAVING AND RE-USING PRECOMPILED PCRE PATTERNS"
|
|
.rs
|
|
.sp
|
|
If you are running an application that uses a large number of regular
|
|
expression patterns, it may be useful to store them in a precompiled form
|
|
instead of having to compile them every time the application is run.
|
|
If you are not using any private character tables (see the
|
|
.\" HREF
|
|
\fBpcre_maketables()\fP
|
|
.\"
|
|
documentation), this is relatively straightforward. If you are using private
|
|
tables, it is a little bit more complicated.
|
|
.P
|
|
If you save compiled patterns to a file, you can copy them to a different host
|
|
and run them there. This works even if the new host has the opposite endianness
|
|
to the one on which the patterns were compiled. There may be a small
|
|
performance penalty, but it should be insignificant. However, compiling regular
|
|
expressions with one version of PCRE for use with a different version is not
|
|
guaranteed to work and may cause crashes.
|
|
.
|
|
.
|
|
.SH "SAVING A COMPILED PATTERN"
|
|
.rs
|
|
.sh
|
|
The value returned by \fBpcre_compile()\fP points to a single block of memory
|
|
that holds the compiled pattern and associated data. You can find the length of
|
|
this block in bytes by calling \fBpcre_fullinfo()\fP with an argument of
|
|
PCRE_INFO_SIZE. You can then save the data in any appropriate manner. Here is
|
|
sample code that compiles a pattern and writes it to a file. It assumes that
|
|
the variable \fIfd\fP refers to a file that is open for output:
|
|
.sp
|
|
int erroroffset, rc, size;
|
|
char *error;
|
|
pcre *re;
|
|
.sp
|
|
re = pcre_compile("my pattern", 0, &error, &erroroffset, NULL);
|
|
if (re == NULL) { ... handle errors ... }
|
|
rc = pcre_fullinfo(re, NULL, PCRE_INFO_SIZE, &size);
|
|
if (rc < 0) { ... handle errors ... }
|
|
rc = fwrite(re, 1, size, fd);
|
|
if (rc != size) { ... handle errors ... }
|
|
.sp
|
|
In this example, the bytes that comprise the compiled pattern are copied
|
|
exactly. Note that this is binary data that may contain any of the 256 possible
|
|
byte values. On systems that make a distinction between binary and non-binary
|
|
data, be sure that the file is opened for binary output.
|
|
.P
|
|
If you want to write more than one pattern to a file, you will have to devise a
|
|
way of separating them. For binary data, preceding each pattern with its length
|
|
is probably the most straightforward approach. Another possibility is to write
|
|
out the data in hexadecimal instead of binary, one pattern to a line.
|
|
.P
|
|
Saving compiled patterns in a file is only one possible way of storing them for
|
|
later use. They could equally well be saved in a database, or in the memory of
|
|
some daemon process that passes them via sockets to the processes that want
|
|
them.
|
|
.P
|
|
If the pattern has been studied, it is also possible to save the study data in
|
|
a similar way to the compiled pattern itself. When studying generates
|
|
additional information, \fBpcre_study()\fP returns a pointer to a
|
|
\fBpcre_extra\fP data block. Its format is defined in the
|
|
.\" HTML <a href="pcreapi.html#extradata">
|
|
.\" </a>
|
|
section on matching a pattern
|
|
.\"
|
|
in the
|
|
.\" HREF
|
|
\fBpcreapi\fP
|
|
.\"
|
|
documentation. The \fIstudy_data\fP field points to the binary study data, and
|
|
this is what you must save (not the \fBpcre_extra\fP block itself). The length
|
|
of the study data can be obtained by calling \fBpcre_fullinfo()\fP with an
|
|
argument of PCRE_INFO_STUDYSIZE. Remember to check that \fBpcre_study()\fP did
|
|
return a non-NULL value before trying to save the study data.
|
|
.
|
|
.
|
|
.SH "RE-USING A PRECOMPILED PATTERN"
|
|
.rs
|
|
.sp
|
|
Re-using a precompiled pattern is straightforward. Having reloaded it into main
|
|
memory, you pass its pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in
|
|
the usual way. This should work even on another host, and even if that host has
|
|
the opposite endianness to the one where the pattern was compiled.
|
|
.P
|
|
However, if you passed a pointer to custom character tables when the pattern
|
|
was compiled (the \fItableptr\fP argument of \fBpcre_compile()\fP), you must
|
|
now pass a similar pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP,
|
|
because the value saved with the compiled pattern will obviously be nonsense. A
|
|
field in a \fBpcre_extra()\fP block is used to pass this data, as described in
|
|
the
|
|
.\" HTML <a href="pcreapi.html#extradata">
|
|
.\" </a>
|
|
section on matching a pattern
|
|
.\"
|
|
in the
|
|
.\" HREF
|
|
\fBpcreapi\fP
|
|
.\"
|
|
documentation.
|
|
.P
|
|
If you did not provide custom character tables when the pattern was compiled,
|
|
the pointer in the compiled pattern is NULL, which causes \fBpcre_exec()\fP to
|
|
use PCRE's internal tables. Thus, you do not need to take any special action at
|
|
run time in this case.
|
|
.P
|
|
If you saved study data with the compiled pattern, you need to create your own
|
|
\fBpcre_extra\fP data block and set the \fIstudy_data\fP field to point to the
|
|
reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the
|
|
\fIflags\fP field to indicate that study data is present. Then pass the
|
|
\fBpcre_extra\fP block to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in the
|
|
usual way.
|
|
.
|
|
.
|
|
.SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES"
|
|
.rs
|
|
.sp
|
|
In general, it is safest to recompile all saved patterns when you update to a
|
|
new PCRE release, though not all updates actually require this. Recompiling is
|
|
definitely needed for release 7.2.
|
|
.
|
|
.
|
|
.
|
|
.SH AUTHOR
|
|
.rs
|
|
.sp
|
|
.nf
|
|
Philip Hazel
|
|
University Computing Service
|
|
Cambridge CB2 3QH, England.
|
|
.fi
|
|
.
|
|
.
|
|
.SH REVISION
|
|
.rs
|
|
.sp
|
|
.nf
|
|
Last updated: 13 June 2007
|
|
Copyright (c) 1997-2007 University of Cambridge.
|
|
.fi
|