Annotation of embedaddon/pcre/doc/html/pcreprecompile.html, revision 1.1
1.1 ! misho 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>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to pcreprecompile.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html