embedaddon/pcre/doc/html/pcreprecompile.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html / pcreprecompile.html
Revision 1.1.1.4 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 19:46:05 2014 UTC (10 years, 9 months ago) by misho
Branches: pcre, MAIN
CVS tags: v8_34, HEAD

pcre 8.34

1: <html> 2: <head> 3: <title>pcreprecompile specification</title> 4: </head> 5: <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6: <h1>pcreprecompile man page</h1> 7:  8: Return to the <a href="index.html">PCRE index page</a>. 9:  10:  11: This page is part of the PCRE HTML documentation. It was generated automatically 12: from the original man page. If there is any nonsense in it, please consult the 13: man page, in case the conversion went wrong. 14:   15: <ul> 16: <li><a name="TOC1" href="#SEC1">SAVING AND RE-USING PRECOMPILED PCRE PATTERNS</a> 17: <li><a name="TOC2" href="#SEC2">SAVING A COMPILED PATTERN</a> 18: <li><a name="TOC3" href="#SEC3">RE-USING A PRECOMPILED PATTERN</a> 19: <li><a name="TOC4" href="#SEC4">COMPATIBILITY WITH DIFFERENT PCRE RELEASES</a> 20: <li><a name="TOC5" href="#SEC5">AUTHOR</a> 21: <li><a name="TOC6" href="#SEC6">REVISION</a> 22: </ul> 23:  <a name="SEC1" href="#TOC1">SAVING AND RE-USING PRECOMPILED PCRE PATTERNS</a>  24:  25: If you are running an application that uses a large number of regular 26: expression patterns, it may be useful to store them in a precompiled form 27: instead of having to compile them every time the application is run. 28: If you are not using any private character tables (see the 29: <a href="pcre_maketables.html">pcre_maketables()</a> 30: documentation), this is relatively straightforward. If you are using private 31: tables, it is a little bit more complicated. However, if you are using the 32: just-in-time optimization feature, it is not possible to save and reload the 33: JIT data. 34:  35:  36: If you save compiled patterns to a file, you can copy them to a different host 37: and run them there. If the two hosts have different endianness (byte order), 38: you should run the pcre[16|32]_pattern_to_host_byte_order() function on the 39: new host before trying to match the pattern. The matching functions return 40: PCRE_ERROR_BADENDIANNESS if they detect a pattern with the wrong endianness. 41:  42:  43: Compiling regular expressions with one version of PCRE for use with a different 44: version is not guaranteed to work and may cause crashes, and saving and 45: restoring a compiled pattern loses any JIT optimization data. 46:  47:  <a name="SEC2" href="#TOC1">SAVING A COMPILED PATTERN</a>  48:  49: The value returned by pcre[16|32]_compile() points to a single block of 50: memory that holds the compiled pattern and associated data. You can find the 51: length of this block in bytes by calling pcre[16|32]_fullinfo() with an 52: argument of PCRE_INFO_SIZE. You can then save the data in any appropriate 53: manner. Here is sample code for the 8-bit library that compiles a pattern and 54: writes it to a file. It assumes that the variable fd refers to a file 55: that is open for output: 56: <pre> 57: int erroroffset, rc, size; 58: char *error; 59: pcre *re; 60: 61: re = pcre_compile("my pattern", 0, &error, &erroroffset, NULL); 62: if (re == NULL) { ... handle errors ... } 63: rc = pcre_fullinfo(re, NULL, PCRE_INFO_SIZE, &size); 64: if (rc < 0) { ... handle errors ... } 65: rc = fwrite(re, 1, size, fd); 66: if (rc != size) { ... handle errors ... } 67: </pre> 68: In this example, the bytes that comprise the compiled pattern are copied 69: exactly. Note that this is binary data that may contain any of the 256 possible 70: byte values. On systems that make a distinction between binary and non-binary 71: data, be sure that the file is opened for binary output. 72:  73:  74: If you want to write more than one pattern to a file, you will have to devise a 75: way of separating them. For binary data, preceding each pattern with its length 76: is probably the most straightforward approach. Another possibility is to write 77: out the data in hexadecimal instead of binary, one pattern to a line. 78:  79:  80: Saving compiled patterns in a file is only one possible way of storing them for 81: later use. They could equally well be saved in a database, or in the memory of 82: some daemon process that passes them via sockets to the processes that want 83: them. 84:  85:  86: If the pattern has been studied, it is also possible to save the normal study 87: data in a similar way to the compiled pattern itself. However, if the 88: PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is created cannot 89: be saved because it is too dependent on the current environment. When studying 90: generates additional information, pcre[16|32]_study() returns a pointer to a 91: pcre[16|32]_extra data block. Its format is defined in the 92: <a href="pcreapi.html#extradata">section on matching a pattern</a> 93: in the 94: <a href="pcreapi.html">pcreapi</a> 95: documentation. The study_data field points to the binary study data, and 96: this is what you must save (not the pcre[16|32]_extra block itself). The 97: length of the study data can be obtained by calling pcre[16|32]_fullinfo() 98: with an argument of PCRE_INFO_STUDYSIZE. Remember to check that 99: pcre[16|32]_study() did return a non-NULL value before trying to save the 100: study data. 101:  102:  <a name="SEC3" href="#TOC1">RE-USING A PRECOMPILED PATTERN</a>  103:  104: Re-using a precompiled pattern is straightforward. Having reloaded it into main 105: memory, called pcre[16|32]_pattern_to_host_byte_order() if necessary, you 106: pass its pointer to pcre[16|32]_exec() or pcre[16|32]_dfa_exec() in 107: the usual way. 108:  109:  110: However, if you passed a pointer to custom character tables when the pattern 111: was compiled (the tableptr argument of pcre[16|32]_compile()), you 112: must now pass a similar pointer to pcre[16|32]_exec() or 113: pcre[16|32]_dfa_exec(), because the value saved with the compiled pattern 114: will obviously be nonsense. A field in a pcre[16|32]_extra() block is used 115: to pass this data, as described in the 116: <a href="pcreapi.html#extradata">section on matching a pattern</a> 117: in the 118: <a href="pcreapi.html">pcreapi</a> 119: documentation. 120:  121:  122: Warning: The tables that pcre_exec() and pcre_dfa_exec() use 123: must be the same as those that were used when the pattern was compiled. If this 124: is not the case, the behaviour is undefined. 125:  126:  127: If you did not provide custom character tables when the pattern was compiled, 128: the pointer in the compiled pattern is NULL, which causes the matching 129: functions to use PCRE's internal tables. Thus, you do not need to take any 130: special action at run time in this case. 131:  132:  133: If you saved study data with the compiled pattern, you need to create your own 134: pcre[16|32]_extra data block and set the study_data field to point 135: to the reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in 136: the flags field to indicate that study data is present. Then pass the 137: pcre[16|32]_extra block to the matching function in the usual way. If the 138: pattern was studied for just-in-time optimization, that data cannot be saved, 139: and so is lost by a save/restore cycle. 140:  141:  <a name="SEC4" href="#TOC1">COMPATIBILITY WITH DIFFERENT PCRE RELEASES</a>  142:  143: In general, it is safest to recompile all saved patterns when you update to a 144: new PCRE release, though not all updates actually require this. 145:  146:  <a name="SEC5" href="#TOC1">AUTHOR</a>  147:  148: Philip Hazel 149:   150: University Computing Service 151:   152: Cambridge CB2 3QH, England. 153:   154:  155:  <a name="SEC6" href="#TOC1">REVISION</a>  156:  157: Last updated: 12 November 2013 158:   159: Copyright © 1997-2013 University of Cambridge. 160:   161:  162: Return to the <a href="index.html">PCRE index page</a>. 163: 