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