PCRE(3)

💖 PCRE(3) 💖 — Library Functions Manual

okay bestie, sit down, hydrate, because we're doing PCRE today — that's Perl-compatible regular expressions — and specifically the 32-bit flavour. it's giving iconic, it's giving vintage, and yes there's a lot here. but you're a main character and you can handle it. let's go 🫶

#include <pcre.h>

---

✨ PCRE 32-BIT API BASIC FUNCTIONS ✨

the core girlies. compile, study, execute, all of it. exact signatures, no cap:

pcre32 *pcre32_compile(PCRE_SPTR32 pattern, int options,
     const char **errptr, int *erroffset,
     const unsigned char *tableptr);

pcre32 *pcre32_compile2(PCRE_SPTR32 pattern, int options,
     int *errorcodeptr,
     const unsigned char *tableptr);

pcre32_extra *pcre32_study(const pcre32 *code, int options,
     const char **errptr);

void pcre32_free_study(pcre32_extra *extra);

int pcre32_exec(const pcre32 *code, const pcre32_extra *extra,
     PCRE_SPTR32 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize);

int pcre32_dfa_exec(const pcre32 *code, const pcre32_extra *extra,
     PCRE_SPTR32 subject, int length, int startoffset,
     int options, int *ovector, int ovecsize,
     int *workspace, int wscount);

---

🎀 PCRE 32-BIT API STRING EXTRACTION FUNCTIONS 🎀

when you've matched and now you wanna get the goods out:

int pcre32_copy_named_substring(const pcre32 *code,
     PCRE_SPTR32 subject, int *ovector,
     int stringcount, PCRE_SPTR32 stringname,
     PCRE_UCHAR32 *buffer, int buffersize);

int pcre32_copy_substring(PCRE_SPTR32 subject, int *ovector,
     int stringcount, int stringnumber, PCRE_UCHAR32 *buffer,
     int buffersize);

int pcre32_get_named_substring(const pcre32 *code,
     PCRE_SPTR32 subject, int *ovector,
     int stringcount, PCRE_SPTR32 stringname,
     PCRE_SPTR32 *stringptr);

int pcre32_get_stringnumber(const pcre32 *code,
     PCRE_SPTR32 name);

int pcre32_get_stringtable_entries(const pcre32 *code,
     PCRE_SPTR32 name, PCRE_UCHAR32 **first, PCRE_UCHAR32 **last);

int pcre32_get_substring(PCRE_SPTR32 subject, int *ovector,
     int stringcount, int stringnumber,
     PCRE_SPTR32 *stringptr);

int pcre32_get_substring_list(PCRE_SPTR32 subject,
     int *ovector, int stringcount, PCRE_SPTR32 **listptr);

void pcre32_free_substring(PCRE_SPTR32 stringptr);

void pcre32_free_substring_list(PCRE_SPTR32 *stringptr);

---

🦋 PCRE 32-BIT API AUXILIARY FUNCTIONS 🦋

the backstage crew keeping everything cute and functional:

pcre32_jit_stack *pcre32_jit_stack_alloc(int startsize, int maxsize);

void pcre32_jit_stack_free(pcre32_jit_stack *stack);

void pcre32_assign_jit_stack(pcre32_extra *extra,
     pcre32_jit_callback callback, void *data);

const unsigned char *pcre32_maketables(void);

int pcre32_fullinfo(const pcre32 *code, const pcre32_extra *extra,
     int what, void *where);

int pcre32_refcount(pcre32 *code, int adjust);

int pcre32_config(int what, void *where);

const char *pcre32_version(void);

int pcre32_pattern_to_host_byte_order(pcre32 *code,
     pcre32_extra *extra, const unsigned char *tables);

---

🌸 PCRE 32-BIT API INDIRECTED FUNCTIONS 🌸

these are the function pointers you can swap out. plug in your own, periodt:

void *(*pcre32_malloc)(size_t);

void (*pcre32_free)(void *);

void *(*pcre32_stack_malloc)(size_t);

void (*pcre32_stack_free)(void *);

int (*pcre32_callout)(pcre32_callout_block *);

---

⭐ PCRE 32-BIT API 32-BIT-ONLY FUNCTION ⭐

the one and only, the extra special exclusive:

int pcre32_utf32_to_host_byte_order(PCRE_UCHAR32 *output,
     PCRE_SPTR32 input, int length, int *byte_order,
     int keep_boms);

---

👑 THE PCRE 32-BIT LIBRARY 👑

so like, starting with release 8.32, you can compile a PCRE library that supports 32-bit character strings — including UTF-32 strings — either as well as or instead of the original 8-bit library. this whole thing was done by Christian Persch, building on the work Zoltan Herczeg did for the 16-bit library. iconic collab honestly.

all three libraries ship an identical set of functions, used in exactly the same way. the only differences are the names of the functions and the data types of their arguments and results. and because nobody wants over-complication (and because the docs maintainers have lives), most of the PCRE documentation describes the 8-bit library, with only occasional shout-outs to the 16-bit and 32-bit ones. this page right here is specifically about what's different when you're on the 32-bit library.

⚠️ WARNING bestie, listen up: a single application can be linked with all of the three libraries, or any combination — but you must be careful. when you're processing any particular pattern, use functions from just one library. for example, if you want to study a pattern that was compiled with pcre32_compile(), you have to use pcre32_study(), not pcre_study(), and you must free that study data with pcre32_free_study(). mixing them up is not the vibe. 💀

---

📄 THE HEADER FILE 📄

there's exactly one header file: pcre.h. that's it. it holds prototypes for every function in every library, plus the definitions of flags, structures, error codes, etc. one file, doing the most. slay.

---

💅 THE LIBRARY NAME 💅

on Unix-like systems, the 32-bit library is called libpcre32, and you can normally access it by adding -lpcre32 to the command that links your application (the one that uses PCRE, obviously).

---

🌈 STRING TYPES 🌈

in the 8-bit library, strings get passed to PCRE functions as vectors of bytes, typed char *. in the 32-bit library, strings are passed as vectors of unsigned 32-bit quantities.

the macro PCRE_UCHAR32 specifies an appropriate data type, and PCRE_SPTR32 is defined as const PCRE_UCHAR32 *.

in very many environments, unsigned int is a 32-bit data type. when PCRE is built, it defines PCRE_UCHAR32 as unsigned int — but then it checks that it really is a 32-bit data type. and if it isn't? the build fails with an error message telling the maintainer to go modify the definition appropriately. not me getting caught lacking in the build system 😭

---

🧚 STRUCTURE TYPES 🧚

the opaque structures used for compiled 32-bit patterns and JIT stacks are typed pcre32 and pcre32_jit_stack respectively.

the user-accessible structure returned by pcre32_study() is typed pcre32_extra, and the structure used to pass data to a callout function is typed pcre32_callout_block.

these structures contain the same fields, with the same names, as their 8-bit counterparts. the only difference: pointers to character strings are 32-bit instead of 8-bit types. same energy, different width.

---

🔥 32-BIT FUNCTIONS 🔥

for every function in the 8-bit library, there's a matching function in the 32-bit library whose name starts with pcre32_ instead of pcre_. all the prototypes are listed above. 💖

and then there's one extra function: pcre32_utf32_to_host_byte_order(). it's a utility that converts a UTF-32 character string to host byte order if necessary. the other 32-bit functions just expect the strings they're handed to already be in host byte order.

the input and output arguments of pcre32_utf32_to_host_byte_order() may point to the same address — yes bestie, conversion in place is supported. the output buffer must be at least as long as the input.

the length argument specifies the number of 32-bit data units in the input string; a negative value specifies a zero-terminated string.

if byte_order is NULL, it's assumed the string starts off in host byte order. this may be changed by byte-order marks (BOMs) anywhere in the string — commonly as the first character.

if byte_order is not NULL, then a non-zero value of the integer it points to means the input starts off in host byte order; otherwise the opposite order is assumed. again, BOMs in the string can change this. the final byte order gets passed back at the end of processing.

if keep_boms is not zero, byte-order mark characters (0xfeff) are copied into the output string. otherwise they're discarded.

the result of the function is the number of 32-bit units placed into the output buffer — including the zero terminator if the string was zero-terminated.

---

🍓 SUBJECT STRING OFFSETS 🍓

the lengths and starting offsets of subject strings must be specified in 32-bit data units. and the offsets within subject strings that the matching functions return are also in 32-bit units, not bytes. keep that straight, bestie.

---

💜 NAMED SUBPATTERNS 💜

the name-to-number translation table maintained for named subpatterns uses 32-bit characters. pcre32_get_stringtable_entries() returns the length of each entry in the table as the number of 32-bit data units.

---

✨ OPTION NAMES ✨

there are two new general option names: PCRE_UTF32 and PCRE_NO_UTF32_CHECK. they correspond to PCRE_UTF8 and PCRE_NO_UTF8_CHECK in the 8-bit library. in fact — plot twist — these new options define the same bits in the options word. there's a discussion about the validity of UTF-32 strings over in the pcreunicode page, if you're curious.

for the pcre32_config() function there's an option PCRE_CONFIG_UTF32 that returns 1 if UTF-32 support is configured, otherwise 0.

and heads up: if this option is given to pcre_config() or pcre16_config(), or if the PCRE_CONFIG_UTF8 or PCRE_CONFIG_UTF16 option is given to pcre32_config(), the result is the PCRE_ERROR_BADOPTION error. wrong door, no entry. 🚪

---

🌸 CHARACTER CODES 🌸

in 32-bit mode, when PCRE_UTF32 is not set, character values are treated the same way as in 8-bit, non UTF-8 mode — except, of course, that they can range from 0 to 0x7fffffff instead of 0 to 0xff. character types for characters less than 0xff can therefore be influenced by the locale in the same way as before. characters greater than 0xff have only one case, and no "type" (like letter or digit).

in UTF-32 mode, the character code is Unicode, in the range 0 to 0x10ffff — with the exception of values in the range 0xd800 to 0xdfff, because those are "surrogate" values and they're ill-formed in UTF-32. 🚫

a UTF-32 string can indicate its endianness with a special code known as a byte-order mark (BOM). the PCRE functions do not handle this — they expect strings to be in host byte order. that's exactly what the utility function pcre32_utf32_to_host_byte_order() is there to help with (see above 👆).

---

😭 ERROR NAMES 😭

the error PCRE_ERROR_BADUTF32 corresponds to its 8-bit counterpart.

the error PCRE_ERROR_BADMODE is given when a compiled pattern gets passed to a function that processes patterns in the other mode — for example, if a pattern compiled with pcre_compile() is passed to pcre32_exec(). mismatched, awkward, we don't love that.

there are also new error codes whose names begin with PCRE_UTF32_ERR for invalid UTF-32 strings, corresponding to the PCRE_UTF8_ERR codes for UTF-8 strings described in the section titled "Reason codes for invalid UTF-8 strings" in the main pcreapi page. the UTF-32 errors are:

• PCRE_UTF32_ERR1 — Surrogate character (range from 0xd800 to 0xdfff)
• PCRE_UTF32_ERR2 — Non-character
• PCRE_UTF32_ERR3 — Character > 0x10ffff

---

🎀 ERROR TEXTS 🎀

if there's an error while compiling a pattern, the error text passed back by pcre32_compile() or pcre32_compile2() is still an 8-bit character string, zero-terminated. yes, even here. consistency, we love her.

---

🫶 CALLOUTS 🫶

the subject and mark fields in the callout block that gets passed to a callout function point to 32-bit vectors. that's the whole note. short and sweet, as she should be.

---

✨ TESTING ✨

okay so pcretest is still out here living its 8-bit life — it reads and writes 8-bit input and output files — but bestie, it can absolutely be used to test the 32-bit library. 💅

If you run it with the command line option -32, here's the tea: patterns and subject strings get converted from 8-bit to 32-bit before they're handed over to PCRE, and the 32-bit library functions are used instead of the 8-bit ones. Then any 32-bit strings that come back get converted to 8-bit for output. conversion girlie 🦋

And if neither the 8-bit library nor the 16-bit library was compiled, pcretest just defaults to 32-bit, and the -32 option gets ignored entirely. it's giving "we move" 😌

When PCRE is being built, the RunTest script — the one that make check calls — uses the pcretest -C option to figure out which of the 8-bit, 16-bit and 32-bit libraries actually got built, and then runs the tests appropriately. organized queen behavior 👑

---

🚫 NOT SUPPORTED IN 32-BIT MODE 🚫

ngl, not every feature from the 8-bit library made it into the 32-bit library. 💀

• The C++ and POSIX wrapper functions support only the 8-bit library.
• The pcregrep program is, at present, 8-bit only.

so if you were hoping to take them into 32-bit mode with you... no babe, they're not coming. 🙈

---

💖 AUTHOR 💖

Philip Hazel University Computing Service Cambridge CB2 3QH, England.

---

🎀 REVISION 🎀

Last updated: 12 May 2013

Copyright (c) 1997-2013 University of Cambridge.

---

and that's the whole page bestie, we made it to the end 🫶 this was PCRE 8.33 from 12 May 2013, and yes the copyright still says Copyright (c) 1997-2013 University of Cambridge — iconic, timeless, periodt. 💜🌸