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.4

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