Regex: Add PCRE 8.32 in tools directory.

tools/pcre/doc/pcreprecompile.3

@@ -0,0 +1,151 @@
+.TH PCREPRECOMPILE 3 "24 June 2012" "PCRE 8.30"
+.SH NAME
+PCRE - Perl-compatible regular expressions
+.SH "SAVING AND RE-USING PRECOMPILED PCRE PATTERNS"
+.rs
+.sp
+If you are running an application that uses a large number of regular
+expression patterns, it may be useful to store them in a precompiled form
+instead of having to compile them every time the application is run.
+If you are not using any private character tables (see the
+.\" HREF
+\fBpcre_maketables()\fP
+.\"
+documentation), this is relatively straightforward. If you are using private
+tables, it is a little bit more complicated. However, if you are using the
+just-in-time optimization feature, it is not possible to save and reload the
+JIT data.
+.P
+If you save compiled patterns to a file, you can copy them to a different host
+and run them there. If the two hosts have different endianness (byte order),
+you should run the \fBpcre[16|32]_pattern_to_host_byte_order()\fP function on the
+new host before trying to match the pattern. The matching functions return
+PCRE_ERROR_BADENDIANNESS if they detect a pattern with the wrong endianness.
+.P
+Compiling regular expressions with one version of PCRE for use with a different
+version is not guaranteed to work and may cause crashes, and saving and
+restoring a compiled pattern loses any JIT optimization data.
+.
+.
+.SH "SAVING A COMPILED PATTERN"
+.rs
+.sp
+The value returned by \fBpcre[16|32]_compile()\fP points to a single block of
+memory that holds the compiled pattern and associated data. You can find the
+length of this block in bytes by calling \fBpcre[16|32]_fullinfo()\fP with an
+argument of PCRE_INFO_SIZE. You can then save the data in any appropriate
+manner. Here is sample code for the 8-bit library that compiles a pattern and
+writes it to a file. It assumes that the variable \fIfd\fP refers to a file
+that is open for output:
+.sp
+  int erroroffset, rc, size;
+  char *error;
+  pcre *re;
+.sp
+  re = pcre_compile("my pattern", 0, &error, &erroroffset, NULL);
+  if (re == NULL) { ... handle errors ... }
+  rc = pcre_fullinfo(re, NULL, PCRE_INFO_SIZE, &size);
+  if (rc < 0) { ... handle errors ... }
+  rc = fwrite(re, 1, size, fd);
+  if (rc != size) { ... handle errors ... }
+.sp
+In this example, the bytes that comprise the compiled pattern are copied
+exactly. Note that this is binary data that may contain any of the 256 possible
+byte values. On systems that make a distinction between binary and non-binary
+data, be sure that the file is opened for binary output.
+.P
+If you want to write more than one pattern to a file, you will have to devise a
+way of separating them. For binary data, preceding each pattern with its length
+is probably the most straightforward approach. Another possibility is to write
+out the data in hexadecimal instead of binary, one pattern to a line.
+.P
+Saving compiled patterns in a file is only one possible way of storing them for
+later use. They could equally well be saved in a database, or in the memory of
+some daemon process that passes them via sockets to the processes that want
+them.
+.P
+If the pattern has been studied, it is also possible to save the normal study
+data in a similar way to the compiled pattern itself. However, if the
+PCRE_STUDY_JIT_COMPILE was used, the just-in-time data that is created cannot
+be saved because it is too dependent on the current environment. When studying
+generates additional information, \fBpcre[16|32]_study()\fP returns a pointer to a
+\fBpcre[16|32]_extra\fP data block. Its format is defined in the
+.\" HTML <a href="pcreapi.html#extradata">
+.\" </a>
+section on matching a pattern
+.\"
+in the
+.\" HREF
+\fBpcreapi\fP
+.\"
+documentation. The \fIstudy_data\fP field points to the binary study data, and
+this is what you must save (not the \fBpcre[16|32]_extra\fP block itself). The
+length of the study data can be obtained by calling \fBpcre[16|32]_fullinfo()\fP
+with an argument of PCRE_INFO_STUDYSIZE. Remember to check that
+\fBpcre[16|32]_study()\fP did return a non-NULL value before trying to save the
+study data.
+.
+.
+.SH "RE-USING A PRECOMPILED PATTERN"
+.rs
+.sp
+Re-using a precompiled pattern is straightforward. Having reloaded it into main
+memory, called \fBpcre[16|32]_pattern_to_host_byte_order()\fP if necessary,
+you pass its pointer to \fBpcre[16|32]_exec()\fP or \fBpcre[16|32]_dfa_exec()\fP in
+the usual way.
+.P
+However, if you passed a pointer to custom character tables when the pattern
+was compiled (the \fItableptr\fP argument of \fBpcre[16|32]_compile()\fP), you
+must now pass a similar pointer to \fBpcre[16|32]_exec()\fP or
+\fBpcre[16|32]_dfa_exec()\fP, because the value saved with the compiled pattern
+will obviously be nonsense. A field in a \fBpcre[16|32]_extra()\fP block is used
+to pass this data, as described in the
+.\" HTML <a href="pcreapi.html#extradata">
+.\" </a>
+section on matching a pattern
+.\"
+in the
+.\" HREF
+\fBpcreapi\fP
+.\"
+documentation.
+.P
+If you did not provide custom character tables when the pattern was compiled,
+the pointer in the compiled pattern is NULL, which causes the matching
+functions to use PCRE's internal tables. Thus, you do not need to take any
+special action at run time in this case.
+.P
+If you saved study data with the compiled pattern, you need to create your own
+\fBpcre[16|32]_extra\fP data block and set the \fIstudy_data\fP field to point to the
+reloaded study data. You must also set the PCRE_EXTRA_STUDY_DATA bit in the
+\fIflags\fP field to indicate that study data is present. Then pass the
+\fBpcre[16|32]_extra\fP block to the matching function in the usual way. If the
+pattern was studied for just-in-time optimization, that data cannot be saved,
+and so is lost by a save/restore cycle.
+.
+.
+.SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES"
+.rs
+.sp
+In general, it is safest to recompile all saved patterns when you update to a
+new PCRE release, though not all updates actually require this.
+.
+.
+.
+.SH AUTHOR
+.rs
+.sp
+.nf
+Philip Hazel
+University Computing Service
+Cambridge CB2 3QH, England.
+.fi
+.
+.
+.SH REVISION
+.rs
+.sp
+.nf
+Last updated: 24 June 2012
+Copyright (c) 1997-2012 University of Cambridge.
+.fi