1PCRE(3)                    Library Functions Manual                    PCRE(3)
2
3
4

NAME

6       PCRE - Perl-compatible regular expressions
7
8       #include <pcre.h>
9

PCRE 32-BIT API BASIC FUNCTIONS

11
12       pcre32 *pcre32_compile(PCRE_SPTR32 pattern, int options,
13            const char **errptr, int *erroffset,
14            const unsigned char *tableptr);
15
16       pcre32 *pcre32_compile2(PCRE_SPTR32 pattern, int options,
17            int *errorcodeptr,
18            const char **errptr, int *erroffset,
19            const unsigned char *tableptr);
20
21       pcre32_extra *pcre32_study(const pcre32 *code, int options,
22            const char **errptr);
23
24       void pcre32_free_study(pcre32_extra *extra);
25
26       int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
27            PCRE_SPTR32 subject, int length, int startoffset,
28            int options, int *ovector, int ovecsize);
29
30       int pcre32_dfa_exec(const pcre32 *code, const pcre32_extra *extra,
31            PCRE_SPTR32 subject, int length, int startoffset,
32            int options, int *ovector, int ovecsize,
33            int *workspace, int wscount);
34

PCRE 32-BIT API STRING EXTRACTION FUNCTIONS

36
37       int pcre32_copy_named_substring(const pcre32 *code,
38            PCRE_SPTR32 subject, int *ovector,
39            int stringcount, PCRE_SPTR32 stringname,
40            PCRE_UCHAR32 *buffer, int buffersize);
41
42       int pcre32_copy_substring(PCRE_SPTR32 subject, int *ovector,
43            int stringcount, int stringnumber, PCRE_UCHAR32 *buffer,
44            int buffersize);
45
46       int pcre32_get_named_substring(const pcre32 *code,
47            PCRE_SPTR32 subject, int *ovector,
48            int stringcount, PCRE_SPTR32 stringname,
49            PCRE_SPTR32 *stringptr);
50
51       int pcre32_get_stringnumber(const pcre32 *code,
52            PCRE_SPTR32 name);
53
54       int pcre32_get_stringtable_entries(const pcre32 *code,
55            PCRE_SPTR32 name, PCRE_UCHAR32 **first, PCRE_UCHAR32 **last);
56
57       int pcre32_get_substring(PCRE_SPTR32 subject, int *ovector,
58            int stringcount, int stringnumber,
59            PCRE_SPTR32 *stringptr);
60
61       int pcre32_get_substring_list(PCRE_SPTR32 subject,
62            int *ovector, int stringcount, PCRE_SPTR32 **listptr);
63
64       void pcre32_free_substring(PCRE_SPTR32 stringptr);
65
66       void pcre32_free_substring_list(PCRE_SPTR32 *stringptr);
67

PCRE 32-BIT API AUXILIARY FUNCTIONS

69
70       pcre32_jit_stack *pcre32_jit_stack_alloc(int startsize, int maxsize);
71
72       void pcre32_jit_stack_free(pcre32_jit_stack *stack);
73
74       void pcre32_assign_jit_stack(pcre32_extra *extra,
75            pcre32_jit_callback callback, void *data);
76
77       const unsigned char *pcre32_maketables(void);
78
79       int pcre32_fullinfo(const pcre32 *code, const pcre32_extra *extra,
80            int what, void *where);
81
82       int pcre32_refcount(pcre32 *code, int adjust);
83
84       int pcre32_config(int what, void *where);
85
86       const char *pcre32_version(void);
87
88       int pcre32_pattern_to_host_byte_order(pcre32 *code,
89            pcre32_extra *extra, const unsigned char *tables);
90

PCRE 32-BIT API INDIRECTED FUNCTIONS

92
93       void *(*pcre32_malloc)(size_t);
94
95       void (*pcre32_free)(void *);
96
97       void *(*pcre32_stack_malloc)(size_t);
98
99       void (*pcre32_stack_free)(void *);
100
101       int (*pcre32_callout)(pcre32_callout_block *);
102

PCRE 32-BIT API 32-BIT-ONLY FUNCTION

104
105       int pcre32_utf32_to_host_byte_order(PCRE_UCHAR32 *output,
106            PCRE_SPTR32 input, int length, int *byte_order,
107            int keep_boms);
108

THE PCRE 32-BIT LIBRARY

110
111       Starting  with  release  8.32, it is possible to compile a PCRE library
112       that supports 32-bit character strings, including  UTF-32  strings,  as
113       well as or instead of the original 8-bit library. This work was done by
114       Christian Persch, based on the work done  by  Zoltan  Herczeg  for  the
115       16-bit  library.  All  three  libraries contain identical sets of func‐
116       tions, used in exactly the same way.  Only the names of  the  functions
117       and  the  data  types  of their arguments and results are different. To
118       avoid over-complication and reduce the documentation maintenance  load,
119       most  of  the PCRE documentation describes the 8-bit library, with only
120       occasional references to the 16-bit and  32-bit  libraries.  This  page
121       describes what is different when you use the 32-bit library.
122
123       WARNING:  A  single  application  can  be linked with all or any of the
124       three libraries, but you must take care when processing any  particular
125       pattern  to  use  functions  from just one library. For example, if you
126       want to study a pattern that was compiled  with  pcre32_compile(),  you
127       must do so with pcre32_study(), not pcre_study(), and you must free the
128       study data with pcre32_free_study().
129

THE HEADER FILE

131
132       There is only one header file, pcre.h. It contains prototypes  for  all
133       the functions in all libraries, as well as definitions of flags, struc‐
134       tures, error codes, etc.
135

THE LIBRARY NAME

137
138       In Unix-like systems, the 32-bit library is called libpcre32,  and  can
139       normally  be  accesss  by adding -lpcre32 to the command for linking an
140       application that uses PCRE.
141

STRING TYPES

143
144       In the 8-bit library, strings are passed to PCRE library  functions  as
145       vectors  of  bytes  with  the  C  type "char *". In the 32-bit library,
146       strings are passed as vectors of unsigned 32-bit quantities. The  macro
147       PCRE_UCHAR32  specifies  an  appropriate  data type, and PCRE_SPTR32 is
148       defined as "const PCRE_UCHAR32 *". In very many environments, "unsigned
149       int" is a 32-bit data type. When PCRE is built, it defines PCRE_UCHAR32
150       as "unsigned int", but checks that it really is a 32-bit data type.  If
151       it is not, the build fails with an error message telling the maintainer
152       to modify the definition appropriately.
153

STRUCTURE TYPES

155
156       The types of the opaque structures that are used  for  compiled  32-bit
157       patterns  and  JIT stacks are pcre32 and pcre32_jit_stack respectively.
158       The  type  of  the  user-accessible  structure  that  is  returned   by
159       pcre32_study()  is  pcre32_extra, and the type of the structure that is
160       used for passing data to a callout  function  is  pcre32_callout_block.
161       These structures contain the same fields, with the same names, as their
162       8-bit counterparts. The only difference is that pointers  to  character
163       strings are 32-bit instead of 8-bit types.
164

32-BIT FUNCTIONS

166
167       For  every function in the 8-bit library there is a corresponding func‐
168       tion in the 32-bit library with a name that starts with pcre32_ instead
169       of  pcre_.  The  prototypes are listed above. In addition, there is one
170       extra function, pcre32_utf32_to_host_byte_order(). This  is  a  utility
171       function  that converts a UTF-32 character string to host byte order if
172       necessary. The other 32-bit  functions  expect  the  strings  they  are
173       passed to be in host byte order.
174
175       The input and output arguments of pcre32_utf32_to_host_byte_order() may
176       point to the same address, that is, conversion in place  is  supported.
177       The output buffer must be at least as long as the input.
178
179       The  length  argument  specifies the number of 32-bit data units in the
180       input string; a negative value specifies a zero-terminated string.
181
182       If byte_order is NULL, it is assumed that the string starts off in host
183       byte  order. This may be changed by byte-order marks (BOMs) anywhere in
184       the string (commonly as the first character).
185
186       If byte_order is not NULL, a non-zero value of the integer to which  it
187       points  means  that  the input starts off in host byte order, otherwise
188       the opposite order is assumed. Again, BOMs in  the  string  can  change
189       this. The final byte order is passed back at the end of processing.
190
191       If  keep_boms  is  not  zero,  byte-order  mark characters (0xfeff) are
192       copied into the output string. Otherwise they are discarded.
193
194       The result of the function is the number of 32-bit  units  placed  into
195       the  output  buffer,  including  the  zero terminator if the string was
196       zero-terminated.
197

SUBJECT STRING OFFSETS

199
200       The offsets within subject strings that are returned  by  the  matching
201       functions are in 32-bit units rather than bytes.
202

NAMED SUBPATTERNS

204
205       The  name-to-number translation table that is maintained for named sub‐
206       patterns uses 32-bit characters.  The  pcre32_get_stringtable_entries()
207       function returns the length of each entry in the table as the number of
208       32-bit data units.
209

OPTION NAMES

211
212       There   are   two   new   general   option   names,   PCRE_UTF32    and
213       PCRE_NO_UTF32_CHECK,     which     correspond    to    PCRE_UTF8    and
214       PCRE_NO_UTF8_CHECK in the 8-bit library. In  fact,  these  new  options
215       define  the  same bits in the options word. There is a discussion about
216       the validity of UTF-32 strings in the pcreunicode page.
217
218       For the pcre32_config() function there is an  option  PCRE_CONFIG_UTF32
219       that  returns  1  if UTF-32 support is configured, otherwise 0. If this
220       option  is  given  to  pcre_config()  or  pcre16_config(),  or  if  the
221       PCRE_CONFIG_UTF8  or  PCRE_CONFIG_UTF16  option is given to pcre32_con‐
222       fig(), the result is the PCRE_ERROR_BADOPTION error.
223

CHARACTER CODES

225
226       In 32-bit mode, when  PCRE_UTF32  is  not  set,  character  values  are
227       treated in the same way as in 8-bit, non UTF-8 mode, except, of course,
228       that they can range from 0 to 0x7fffffff instead of 0 to 0xff.  Charac‐
229       ter  types for characters less than 0xff can therefore be influenced by
230       the locale in the same way as before.   Characters  greater  than  0xff
231       have only one case, and no "type" (such as letter or digit).
232
233       In  UTF-32  mode,  the  character  code  is  Unicode, in the range 0 to
234       0x10ffff, with the exception of values in the range  0xd800  to  0xdfff
235       because those are "surrogate" values that are ill-formed in UTF-32.
236
237       A  UTF-32 string can indicate its endianness by special code knows as a
238       byte-order mark (BOM). The PCRE functions do not handle this, expecting
239       strings   to   be  in  host  byte  order.  A  utility  function  called
240       pcre32_utf32_to_host_byte_order() is provided to help  with  this  (see
241       above).
242

ERROR NAMES

244
245       The  error  PCRE_ERROR_BADUTF32  corresponds  to its 8-bit counterpart.
246       The error PCRE_ERROR_BADMODE is given when a compiled pattern is passed
247       to  a  function that processes patterns in the other mode, for example,
248       if a pattern compiled with pcre_compile() is passed to pcre32_exec().
249
250       There are new error codes whose names  begin  with  PCRE_UTF32_ERR  for
251       invalid  UTF-32  strings,  corresponding to the PCRE_UTF8_ERR codes for
252       UTF-8 strings that are described in the section entitled "Reason  codes
253       for  invalid UTF-8 strings" in the main pcreapi page. The UTF-32 errors
254       are:
255
256         PCRE_UTF32_ERR1  Surrogate character (range from 0xd800 to 0xdfff)
257         PCRE_UTF32_ERR2  Non-character
258         PCRE_UTF32_ERR3  Character > 0x10ffff
259

ERROR TEXTS

261
262       If there is an error while compiling a pattern, the error text that  is
263       passed  back by pcre32_compile() or pcre32_compile2() is still an 8-bit
264       character string, zero-terminated.
265

CALLOUTS

267
268       The subject and mark fields in the callout block that is  passed  to  a
269       callout function point to 32-bit vectors.
270

TESTING

272
273       The  pcretest  program continues to operate with 8-bit input and output
274       files, but it can be used for testing the 32-bit library. If it is  run
275       with the command line option -32, patterns and subject strings are con‐
276       verted from 8-bit to 32-bit before being passed to PCRE, and the 32-bit
277       library  functions  are used instead of the 8-bit ones. Returned 32-bit
278       strings are converted to 8-bit for output. If both the  8-bit  and  the
279       16-bit libraries were not compiled, pcretest defaults to 32-bit and the
280       -32 option is ignored.
281
282       When PCRE is being built, the RunTest script that is  called  by  "make
283       check"  uses  the  pcretest  -C  option to discover which of the 8-bit,
284       16-bit and 32-bit libraries has been built, and runs the  tests  appro‐
285       priately.
286

NOT SUPPORTED IN 32-BIT MODE

288
289       Not all the features of the 8-bit library are available with the 32-bit
290       library. The C++ and POSIX wrapper functions  support  only  the  8-bit
291       library, and the pcregrep program is at present 8-bit only.
292

AUTHOR

294
295       Philip Hazel
296       University Computing Service
297       Cambridge CB2 3QH, England.
298

REVISION

300
301       Last updated: 08 November 2012
302       Copyright (c) 1997-2012 University of Cambridge.
303
304
305
306PCRE 8.32                      08 November 2012                        PCRE(3)
Impressum