Return to pcreprecompile.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc

Annotation of embedaddon/pcre/doc/pcreprecompile.3, revision 1.1.1.1

1.1       misho       1: .TH PCREPRECOMPILE 3
                      2: .SH NAME
                      3: PCRE - Perl-compatible regular expressions
                      4: .SH "SAVING AND RE-USING PRECOMPILED PCRE PATTERNS"
                      5: .rs
                      6: .sp
                      7: If you are running an application that uses a large number of regular
                      8: expression patterns, it may be useful to store them in a precompiled form
                      9: instead of having to compile them every time the application is run.
                     10: If you are not using any private character tables (see the
                     11: .\" HREF
                     12: \fBpcre_maketables()\fP
                     13: .\"
                     14: documentation), this is relatively straightforward. If you are using private
                     15: tables, it is a little bit more complicated. However, if you are using the
                     16: just-in-time optimization feature of \fBpcre_study()\fP, it is not possible to
                     17: save and reload the JIT data.
                     18: .P
                     19: If you save compiled patterns to a file, you can copy them to a different host
                     20: and run them there. This works even if the new host has the opposite endianness
                     21: to the one on which the patterns were compiled. There may be a small
                     22: performance penalty, but it should be insignificant. However, compiling regular
                     23: expressions with one version of PCRE for use with a different version is not
                     24: guaranteed to work and may cause crashes, and saving and restoring a compiled
                     25: pattern loses any JIT optimization data.
                     26: .
                     27: .
                     28: .SH "SAVING A COMPILED PATTERN"
                     29: .rs
                     30: .sp
                     31: The value returned by \fBpcre_compile()\fP points to a single block of memory
                     32: that holds the compiled pattern and associated data. You can find the length of
                     33: this block in bytes by calling \fBpcre_fullinfo()\fP with an argument of
                     34: PCRE_INFO_SIZE. You can then save the data in any appropriate manner. Here is
                     35: sample code that compiles a pattern and writes it to a file. It assumes that
                     36: the variable \fIfd\fP refers to a file that is open for output:
                     37: .sp
                     38:   int erroroffset, rc, size;
                     39:   char *error;
                     40:   pcre *re;
                     41: .sp
                     42:   re = pcre_compile("my pattern", 0, &error, &erroroffset, NULL);
                     43:   if (re == NULL) { ... handle errors ... }
                     44:   rc = pcre_fullinfo(re, NULL, PCRE_INFO_SIZE, &size);
                     45:   if (rc < 0) { ... handle errors ... }
                     46:   rc = fwrite(re, 1, size, fd);
                     47:   if (rc != size) { ... handle errors ... }
                     48: .sp
                     49: In this example, the bytes that comprise the compiled pattern are copied
                     50: exactly. Note that this is binary data that may contain any of the 256 possible
                     51: byte values. On systems that make a distinction between binary and non-binary
                     52: data, be sure that the file is opened for binary output.
                     53: .P
                     54: If you want to write more than one pattern to a file, you will have to devise a
                     55: way of separating them. For binary data, preceding each pattern with its length
                     56: is probably the most straightforward approach. Another possibility is to write
                     57: out the data in hexadecimal instead of binary, one pattern to a line.
                     58: .P
                     59: Saving compiled patterns in a file is only one possible way of storing them for
                     60: later use. They could equally well be saved in a database, or in the memory of
                     61: some daemon process that passes them via sockets to the processes that want
                     62: them.
                     63: .P
                     64: If the pattern has been studied, it is also possible to save the normal study
                     65: data in a similar way to the compiled pattern itself. However, if the
                     66: PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is created cannot
                     67: be saved because it is too dependent on the current environment. When studying
                     68: generates additional information, \fBpcre_study()\fP returns a pointer to a
                     69: \fBpcre_extra\fP data block. Its format is defined in the
                     70: .\" HTML <a href="pcreapi.html#extradata">
                     71: .\" </a>
                     72: section on matching a pattern
                     73: .\"
                     74: in the
                     75: .\" HREF
                     76: \fBpcreapi\fP
                     77: .\"
                     78: documentation. The \fIstudy_data\fP field points to the binary study data, and
                     79: this is what you must save (not the \fBpcre_extra\fP block itself). The length
                     80: of the study data can be obtained by calling \fBpcre_fullinfo()\fP with an
                     81: argument of PCRE_INFO_STUDYSIZE. Remember to check that \fBpcre_study()\fP did
                     82: return a non-NULL value before trying to save the study data.
                     83: .
                     84: .
                     85: .SH "RE-USING A PRECOMPILED PATTERN"
                     86: .rs
                     87: .sp
                     88: Re-using a precompiled pattern is straightforward. Having reloaded it into main
                     89: memory, you pass its pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in
                     90: the usual way. This should work even on another host, and even if that host has
                     91: the opposite endianness to the one where the pattern was compiled.
                     92: .P
                     93: However, if you passed a pointer to custom character tables when the pattern
                     94: was compiled (the \fItableptr\fP argument of \fBpcre_compile()\fP), you must
                     95: now pass a similar pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP,
                     96: because the value saved with the compiled pattern will obviously be nonsense. A
                     97: field in a \fBpcre_extra()\fP block is used to pass this data, as described in
                     98: the
                     99: .\" HTML <a href="pcreapi.html#extradata">
                    100: .\" </a>
                    101: section on matching a pattern
                    102: .\"
                    103: in the
                    104: .\" HREF
                    105: \fBpcreapi\fP
                    106: .\"
                    107: documentation.
                    108: .P
                    109: If you did not provide custom character tables when the pattern was compiled,
                    110: the pointer in the compiled pattern is NULL, which causes \fBpcre_exec()\fP to
                    111: use PCRE's internal tables. Thus, you do not need to take any special action at
                    112: run time in this case.
                    113: .P
                    114: If you saved study data with the compiled pattern, you need to create your own
                    115: \fBpcre_extra\fP data block and set the \fIstudy_data\fP field to point to the
                    116: reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the
                    117: \fIflags\fP field to indicate that study data is present. Then pass the
                    118: \fBpcre_extra\fP block to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in the
                    119: usual way. If the pattern was studied for just-in-time optimization, that data
                    120: cannot be saved, and so is lost by a save/restore cycle.
                    121: .
                    122: .
                    123: .SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES"
                    124: .rs
                    125: .sp
                    126: In general, it is safest to recompile all saved patterns when you update to a
                    127: new PCRE release, though not all updates actually require this.
                    128: .
                    129: .
                    130: .
                    131: .SH AUTHOR
                    132: .rs
                    133: .sp
                    134: .nf
                    135: Philip Hazel
                    136: University Computing Service
                    137: Cambridge CB2 3QH, England.
                    138: .fi
                    139: .
                    140: .
                    141: .SH REVISION
                    142: .rs
                    143: .sp
                    144: .nf
                    145: Last updated: 26 August 2011
                    146: Copyright (c) 1997-2011 University of Cambridge.
                    147: .fi