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