add pcre to in tree libs

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@3732 d0543943-73ff-0310-b7d9-9358b9ac24b2

libs/pcre/doc/pcreprecompile.3

@@ -0,0 +1,131 @@
+.TH PCREPRECOMPILE 3
+.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.
+.P
+If you save compiled patterns to a file, you can copy them to a different host
+and run them there. This works even if the new host has the opposite endianness
+to the one on which the patterns were compiled. There may be a small
+performance penalty, but it should be insignificant.
+.
+.
+.SH "SAVING A COMPILED PATTERN"
+.rs
+.sh
+The value returned by \fBpcre_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_fullinfo()\fP with an argument of
+PCRE_INFO_SIZE. You can then save the data in any appropriate manner. Here is
+sample code 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 study data in
+a similar way to the compiled pattern itself. When studying generates
+additional information, \fBpcre_study()\fP returns a pointer to a
+\fBpcre_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_extra\fP block itself). The length
+of the study data can be obtained by calling \fBpcre_fullinfo()\fP with an
+argument of PCRE_INFO_STUDYSIZE. Remember to check that \fBpcre_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, you pass its pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in
+the usual way. This should work even on another host, and even if that host has
+the opposite endianness to the one where the pattern was compiled.
+.P
+However, if you passed a pointer to custom character tables when the pattern
+was compiled (the \fItableptr\fP argument of \fBpcre_compile()\fP), you must
+now pass a similar pointer to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP,
+because the value saved with the compiled pattern will obviously be nonsense. A
+field in a \fBpcre_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 \fBpcre_exec()\fP 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_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_extra\fP block to \fBpcre_exec()\fP or \fBpcre_dfa_exec()\fP in the
+usual way.
+.
+.
+.SH "COMPATIBILITY WITH DIFFERENT PCRE RELEASES"
+.rs
+.sp
+The layout of the control block that is at the start of the data that makes up
+a compiled pattern was changed for release 5.0. If you have any saved patterns
+that were compiled with previous releases (not a facility that was previously
+advertised), you will have to recompile them for release 5.0. However, from now
+on, it should be possible to make changes in a compatible manner.
+.P
+Notwithstanding the above, if you have any saved patterns in UTF-8 mode that
+use \ep or \eP that were compiled with any release up to and including 6.4, you
+will have to recompile them for release 6.5 and above.
+.P
+.in 0
+Last updated: 01 February 2006
+.br
+Copyright (c) 1997-2006 University of Cambridge.