diff options
Diffstat (limited to 'srclib/pcre/doc/pcreprecompile.3')
| -rw-r--r-- | srclib/pcre/doc/pcreprecompile.3 | 125 |
1 files changed, 0 insertions, 125 deletions
diff --git a/srclib/pcre/doc/pcreprecompile.3 b/srclib/pcre/doc/pcreprecompile.3 deleted file mode 100644 index f08939bae0..0000000000 --- a/srclib/pcre/doc/pcreprecompile.3 +++ /dev/null @@ -1,125 +0,0 @@ -.TH PCRE 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. -. -. -.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 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, 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 in the usual way. -. -. -.SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES" -.rs -.sp -The layout of the control block that is at the start of the data that makes up -a compiled pattern was changed for release 5.0. If you have any saved patterns -that were compiled with previous releases (not a facility that was previously -advertised), you will have to recompile them for release 5.0. However, from now -on, it should be possible to make changes in a compabible manner. -.P -.in 0 -Last updated: 10 September 2004 -.br -Copyright (c) 1997-2004 University of Cambridge. |