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, and saving and restoring a compiled -pattern loses any JIT optimization data. +and run them there. If the two hosts have different endianness (byte order), +you should run the pcre[16|32]_pattern_to_host_byte_order() function on the +new host before trying to match the pattern. The matching functions return +PCRE_ERROR_BADENDIANNESS if they detect a pattern with the wrong endianness.
++Compiling regular expressions with one version of PCRE for use with a different +version is not guaranteed to work and may cause crashes, and saving and +restoring a compiled pattern loses any JIT optimization data. +
-The value returned by pcre_compile() 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 pcre_fullinfo() 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 fd refers to a file that is open for output: +The value returned by pcre[16|32]_compile() 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 pcre[16|32]_fullinfo() with an +argument of PCRE_INFO_SIZE. You can then save the data in any appropriate +manner. Here is sample code for the 8-bit library that compiles a pattern and +writes it to a file. It assumes that the variable fd refers to a file +that is open for output:
int erroroffset, rc, size; char *error; @@ -83,50 +87,56 @@ If the pattern has been studied, it is also possible t data in a similar way to the compiled pattern itself. However, if the PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is created cannot be saved because it is too dependent on the current environment. When studying -generates additional information, pcre_study() returns a pointer to a -pcre_extra data block. Its format is defined in the +generates additional information, pcre[16|32]_study() returns a pointer to a +pcre[16|32]_extra data block. Its format is defined in the section on matching a pattern in the pcreapi documentation. The study_data field points to the binary study data, and -this is what you must save (not the pcre_extra block itself). The length -of the study data can be obtained by calling pcre_fullinfo() with an -argument of PCRE_INFO_STUDYSIZE. Remember to check that pcre_study() did -return a non-NULL value before trying to save the study data. +this is what you must save (not the pcre[16|32]_extra block itself). The +length of the study data can be obtained by calling pcre[16|32]_fullinfo() +with an argument of PCRE_INFO_STUDYSIZE. Remember to check that +pcre[16|32]_study() did return a non-NULL value before trying to save the +study data.
RE-USING A PRECOMPILED PATTERN
Re-using a precompiled pattern is straightforward. Having reloaded it into main -memory, you pass its pointer to pcre_exec() or pcre_dfa_exec() 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. +memory, called pcre[16|32]_pattern_to_host_byte_order() if necessary, you +pass its pointer to pcre[16|32]_exec() or pcre[16|32]_dfa_exec() in +the usual way.
However, if you passed a pointer to custom character tables when the pattern -was compiled (the tableptr argument of pcre_compile()), you must -now pass a similar pointer to pcre_exec() or pcre_dfa_exec(), -because the value saved with the compiled pattern will obviously be nonsense. A -field in a pcre_extra() block is used to pass this data, as described in -the +was compiled (the tableptr argument of pcre[16|32]_compile()), you +must now pass a similar pointer to pcre[16|32]_exec() or +pcre[16|32]_dfa_exec(), because the value saved with the compiled pattern +will obviously be nonsense. A field in a pcre[16|32]_extra() block is used +to pass this data, as described in the section on matching a pattern in the pcreapi documentation.
+Warning: The tables that pcre_exec() and pcre_dfa_exec() use +must be the same as those that were used when the pattern was compiled. If this +is not the case, the behaviour is undefined. +
+If you did not provide custom character tables when the pattern was compiled, -the pointer in the compiled pattern is NULL, which causes pcre_exec() to -use PCRE's internal tables. Thus, you do not need to take any special action at -run time in this case. +the pointer in the compiled pattern is NULL, which causes the matching +functions to use PCRE's internal tables. Thus, you do not need to take any +special action at run time in this case.
If you saved study data with the compiled pattern, you need to create your own -pcre_extra data block and set the study_data field to point to the -reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the -flags field to indicate that study data is present. Then pass the -pcre_extra block to pcre_exec() or pcre_dfa_exec() in the -usual way. If the pattern was studied for just-in-time optimization, that data -cannot be saved, and so is lost by a save/restore cycle. +pcre[16|32]_extra data block and set the study_data field to point +to the reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in +the flags field to indicate that study data is present. Then pass the +pcre[16|32]_extra block to the matching function in the usual way. If the +pattern was studied for just-in-time optimization, that data cannot be saved, +and so is lost by a save/restore cycle.
COMPATIBILITY WITH DIFFERENT PCRE RELEASES
@@ -144,9 +154,9 @@ Cambridge CB2 3QH, England.
REVISION
-Last updated: 26 August 2011 +Last updated: 12 November 2013
-Copyright © 1997-2011 University of Cambridge. +Copyright © 1997-2013 University of Cambridge.
Return to the PCRE index page.