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 unsigned char *tableptr);
19
20       pcre32_extra *pcre32_study(const pcre32 *code, int options,
21            const char **errptr);
22
23       void pcre32_free_study(pcre32_extra *extra);
24
25       int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
26            PCRE_SPTR32 subject, int length, int startoffset,
27            int options, int *ovector, int ovecsize);
28
29       int pcre32_dfa_exec(const pcre32 *code, const pcre32_extra *extra,
30            PCRE_SPTR32 subject, int length, int startoffset,
31            int options, int *ovector, int ovecsize,
32            int *workspace, int wscount);
33

PCRE 32-BIT API STRING EXTRACTION FUNCTIONS

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

PCRE 32-BIT API AUXILIARY FUNCTIONS

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

PCRE 32-BIT API INDIRECTED FUNCTIONS

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

PCRE 32-BIT API 32-BIT-ONLY FUNCTION

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

THE PCRE 32-BIT LIBRARY

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

THE HEADER FILE

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

THE LIBRARY NAME

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

STRING TYPES

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

STRUCTURE TYPES

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

32-BIT FUNCTIONS

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

SUBJECT STRING OFFSETS

198
199       The lengths and starting offsets of subject strings must  be  specified
200       in  32-bit  data units, and the offsets within subject strings that are
201       returned by the matching functions are in also 32-bit units rather than
202       bytes.
203

NAMED SUBPATTERNS

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

OPTION NAMES

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

CHARACTER CODES

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

ERROR NAMES

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

ERROR TEXTS

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

CALLOUTS

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

TESTING

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

NOT SUPPORTED IN 32-BIT MODE

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

AUTHOR

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

REVISION

301
302       Last updated: 12 May 2013
303       Copyright (c) 1997-2013 University of Cambridge.
304
305
306
307PCRE 8.33                         12 May 2013                          PCRE(3)
Impressum