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