Annotation of embedaddon/pcre/doc/pcreprecompile.3, revision 1.1.1.2
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
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),
! 21: you should run the \fBpcre[16]_pattern_to_host_byte_order()\fP function on the
! 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.2 ! misho 33: The value returned by \fBpcre[16]_compile()\fP points to a single block of
! 34: memory that holds the compiled pattern and associated data. You can find the
! 35: length of this block in bytes by calling \fBpcre[16]_fullinfo()\fP with an
! 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.2 ! misho 71: generates additional information, \fBpcre[16]_study()\fP returns a pointer to a
! 72: \fBpcre[16]_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.2 ! misho 82: this is what you must save (not the \fBpcre[16]_extra\fP block itself). The
! 83: length of the study data can be obtained by calling \fBpcre[16]_fullinfo()\fP
! 84: with an argument of PCRE_INFO_STUDYSIZE. Remember to check that
! 85: \fBpcre[16]_study()\fP did return a non-NULL value before trying to save the
! 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.2 ! misho 93: memory, called \fBpcre[16]_pattern_to_host_byte_order()\fP if necessary,
! 94: you pass its pointer to \fBpcre[16]_exec()\fP or \fBpcre[16]_dfa_exec()\fP in
! 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.2 ! misho 98: was compiled (the \fItableptr\fP argument of \fBpcre[16]_compile()\fP), you
! 99: must now pass a similar pointer to \fBpcre[16]_exec()\fP or
! 100: \fBpcre[16]_dfa_exec()\fP, because the value saved with the compiled pattern
! 101: will obviously be nonsense. A field in a \fBpcre[16]_extra()\fP block is used
! 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
113: If you did not provide custom character tables when the pattern was compiled,
1.1.1.2 ! misho 114: the pointer in the compiled pattern is NULL, which causes the matching
! 115: functions to use PCRE's internal tables. Thus, you do not need to take any
! 116: special action at run time in this case.
1.1 misho 117: .P
118: If you saved study data with the compiled pattern, you need to create your own
1.1.1.2 ! misho 119: \fBpcre[16]_extra\fP data block and set the \fIstudy_data\fP field to point to the
1.1 misho 120: reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the
121: \fIflags\fP field to indicate that study data is present. Then pass the
1.1.1.2 ! misho 122: \fBpcre[16]_extra\fP block to the matching function in the usual way. If the
! 123: pattern was studied for just-in-time optimization, that data cannot be saved,
! 124: and so is lost by a save/restore cycle.
1.1 misho 125: .
126: .
127: .SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES"
128: .rs
129: .sp
130: In general, it is safest to recompile all saved patterns when you update to a
131: new PCRE release, though not all updates actually require this.
132: .
133: .
134: .
135: .SH AUTHOR
136: .rs
137: .sp
138: .nf
139: Philip Hazel
140: University Computing Service
141: Cambridge CB2 3QH, England.
142: .fi
143: .
144: .
145: .SH REVISION
146: .rs
147: .sp
148: .nf
1.1.1.2 ! misho 149: Last updated: 10 January 2012
! 150: Copyright (c) 1997-2012 University of Cambridge.
1.1 misho 151: .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