embedaddon/pcre/doc/html/pcre32.html - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / pcre / doc / html / pcre32.html
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Sun Jun 15 19:46:05 2014 UTC (10 years, 9 months ago) by misho
Branches: pcre, MAIN
CVS tags: v8_34, HEAD

pcre 8.34

1: <html> 2: <head> 3: <title>pcre32 specification</title> 4: </head> 5: <body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6: <h1>pcre32 man page</h1> 7:  8: Return to the <a href="index.html">PCRE index page</a>. 9:  10:  11: This page is part of the PCRE HTML documentation. It was generated automatically 12: from the original man page. If there is any nonsense in it, please consult the 13: man page, in case the conversion went wrong. 14:   15: <ul> 16: <li><a name="TOC1" href="#SEC1">PCRE 32-BIT API BASIC FUNCTIONS</a> 17: <li><a name="TOC2" href="#SEC2">PCRE 32-BIT API STRING EXTRACTION FUNCTIONS</a> 18: <li><a name="TOC3" href="#SEC3">PCRE 32-BIT API AUXILIARY FUNCTIONS</a> 19: <li><a name="TOC4" href="#SEC4">PCRE 32-BIT API INDIRECTED FUNCTIONS</a> 20: <li><a name="TOC5" href="#SEC5">PCRE 32-BIT API 32-BIT-ONLY FUNCTION</a> 21: <li><a name="TOC6" href="#SEC6">THE PCRE 32-BIT LIBRARY</a> 22: <li><a name="TOC7" href="#SEC7">THE HEADER FILE</a> 23: <li><a name="TOC8" href="#SEC8">THE LIBRARY NAME</a> 24: <li><a name="TOC9" href="#SEC9">STRING TYPES</a> 25: <li><a name="TOC10" href="#SEC10">STRUCTURE TYPES</a> 26: <li><a name="TOC11" href="#SEC11">32-BIT FUNCTIONS</a> 27: <li><a name="TOC12" href="#SEC12">SUBJECT STRING OFFSETS</a> 28: <li><a name="TOC13" href="#SEC13">NAMED SUBPATTERNS</a> 29: <li><a name="TOC14" href="#SEC14">OPTION NAMES</a> 30: <li><a name="TOC15" href="#SEC15">CHARACTER CODES</a> 31: <li><a name="TOC16" href="#SEC16">ERROR NAMES</a> 32: <li><a name="TOC17" href="#SEC17">ERROR TEXTS</a> 33: <li><a name="TOC18" href="#SEC18">CALLOUTS</a> 34: <li><a name="TOC19" href="#SEC19">TESTING</a> 35: <li><a name="TOC20" href="#SEC20">NOT SUPPORTED IN 32-BIT MODE</a> 36: <li><a name="TOC21" href="#SEC21">AUTHOR</a> 37: <li><a name="TOC22" href="#SEC22">REVISION</a> 38: </ul> 39:  40: #include <pcre.h> 41:  42:  <a name="SEC1" href="#TOC1">PCRE 32-BIT API BASIC FUNCTIONS</a>  43:  44: pcre32 *pcre32_compile(PCRE_SPTR32 pattern, int options, 45:  const char **errptr, int *erroffset, 46:  const unsigned char *tableptr); 47:   48:   49: pcre32 *pcre32_compile2(PCRE_SPTR32 pattern, int options, 50:  int *errorcodeptr, 51:  const unsigned char *tableptr); 52:   53:   54: pcre32_extra *pcre32_study(const pcre32 *code, int options, 55:  const char **errptr); 56:   57:   58: void pcre32_free_study(pcre32_extra *extra); 59:   60:   61: int pcre32_exec(const pcre32 *code, const pcre32_extra *extra, 62:  PCRE_SPTR32 subject, int length, int startoffset, 63:  int options, int *ovector, int ovecsize); 64:   65:   66: int pcre32_dfa_exec(const pcre32 *code, const pcre32_extra *extra, 67:  PCRE_SPTR32 subject, int length, int startoffset, 68:  int options, int *ovector, int ovecsize, 69:  int *workspace, int wscount); 70:  71:  <a name="SEC2" href="#TOC1">PCRE 32-BIT API STRING EXTRACTION FUNCTIONS</a>  72:  73: int pcre32_copy_named_substring(const pcre32 *code, 74:  PCRE_SPTR32 subject, int *ovector, 75:  int stringcount, PCRE_SPTR32 stringname, 76:  PCRE_UCHAR32 *buffer, int buffersize); 77:   78:   79: int pcre32_copy_substring(PCRE_SPTR32 subject, int *ovector, 80:  int stringcount, int stringnumber, PCRE_UCHAR32 *buffer, 81:  int buffersize); 82:   83:   84: int pcre32_get_named_substring(const pcre32 *code, 85:  PCRE_SPTR32 subject, int *ovector, 86:  int stringcount, PCRE_SPTR32 stringname, 87:  PCRE_SPTR32 *stringptr); 88:   89:   90: int pcre32_get_stringnumber(const pcre32 *code, 91:  PCRE_SPTR32 name); 92:   93:   94: int pcre32_get_stringtable_entries(const pcre32 *code, 95:  PCRE_SPTR32 name, PCRE_UCHAR32 **first, PCRE_UCHAR32 **last); 96:   97:   98: int pcre32_get_substring(PCRE_SPTR32 subject, int *ovector, 99:  int stringcount, int stringnumber, 100:  PCRE_SPTR32 *stringptr); 101:   102:   103: int pcre32_get_substring_list(PCRE_SPTR32 subject, 104:  int *ovector, int stringcount, PCRE_SPTR32 **listptr); 105:   106:   107: void pcre32_free_substring(PCRE_SPTR32 stringptr); 108:   109:   110: void pcre32_free_substring_list(PCRE_SPTR32 *stringptr); 111:  112:  <a name="SEC3" href="#TOC1">PCRE 32-BIT API AUXILIARY FUNCTIONS</a>  113:  114: pcre32_jit_stack *pcre32_jit_stack_alloc(int startsize, int maxsize); 115:   116:   117: void pcre32_jit_stack_free(pcre32_jit_stack *stack); 118:   119:   120: void pcre32_assign_jit_stack(pcre32_extra *extra, 121:  pcre32_jit_callback callback, void *data); 122:   123:   124: const unsigned char *pcre32_maketables(void); 125:   126:   127: int pcre32_fullinfo(const pcre32 *code, const pcre32_extra *extra, 128:  int what, void *where); 129:   130:   131: int pcre32_refcount(pcre32 *code, int adjust); 132:   133:   134: int pcre32_config(int what, void *where); 135:   136:   137: const char *pcre32_version(void); 138:   139:   140: int pcre32_pattern_to_host_byte_order(pcre32 *code, 141:  pcre32_extra *extra, const unsigned char *tables); 142:  143:  <a name="SEC4" href="#TOC1">PCRE 32-BIT API INDIRECTED FUNCTIONS</a>  144:  145: void *(*pcre32_malloc)(size_t); 146:   147:   148: void (*pcre32_free)(void *); 149:   150:   151: void *(*pcre32_stack_malloc)(size_t); 152:   153:   154: void (*pcre32_stack_free)(void *); 155:   156:   157: int (*pcre32_callout)(pcre32_callout_block *); 158:  159:  <a name="SEC5" href="#TOC1">PCRE 32-BIT API 32-BIT-ONLY FUNCTION</a>  160:  161: int pcre32_utf32_to_host_byte_order(PCRE_UCHAR32 *output, 162:  PCRE_SPTR32 input, int length, int *byte_order, 163:  int keep_boms); 164:  165:  <a name="SEC6" href="#TOC1">THE PCRE 32-BIT LIBRARY</a>  166:  167: Starting with release 8.32, it is possible to compile a PCRE library that 168: supports 32-bit character strings, including UTF-32 strings, as well as or 169: instead of the original 8-bit library. This work was done by Christian Persch, 170: based on the work done by Zoltan Herczeg for the 16-bit library. All three 171: libraries contain identical sets of functions, used in exactly the same way. 172: Only the names of the functions and the data types of their arguments and 173: results are different. To avoid over-complication and reduce the documentation 174: maintenance load, most of the PCRE documentation describes the 8-bit library, 175: with only occasional references to the 16-bit and 32-bit libraries. This page 176: describes what is different when you use the 32-bit library. 177:  178:  179: WARNING: A single application can be linked with all or any of the three 180: libraries, but you must take care when processing any particular pattern 181: to use functions from just one library. For example, if you want to study 182: a pattern that was compiled with pcre32_compile(), you must do so 183: with pcre32_study(), not pcre_study(), and you must free the 184: study data with pcre32_free_study(). 185:  186:  <a name="SEC7" href="#TOC1">THE HEADER FILE</a>  187:  188: There is only one header file, pcre.h. It contains prototypes for all the 189: functions in all libraries, as well as definitions of flags, structures, error 190: codes, etc. 191:  192:  <a name="SEC8" href="#TOC1">THE LIBRARY NAME</a>  193:  194: In Unix-like systems, the 32-bit library is called libpcre32, and can 195: normally be accesss by adding -lpcre32 to the command for linking an 196: application that uses PCRE. 197:  198:  <a name="SEC9" href="#TOC1">STRING TYPES</a>  199:  200: In the 8-bit library, strings are passed to PCRE library functions as vectors 201: of bytes with the C type "char *". In the 32-bit library, strings are passed as 202: vectors of unsigned 32-bit quantities. The macro PCRE_UCHAR32 specifies an 203: appropriate data type, and PCRE_SPTR32 is defined as "const PCRE_UCHAR32 *". In 204: very many environments, "unsigned int" is a 32-bit data type. When PCRE is 205: built, it defines PCRE_UCHAR32 as "unsigned int", but checks that it really is 206: a 32-bit data type. If it is not, the build fails with an error message telling 207: the maintainer to modify the definition appropriately. 208:  209:  <a name="SEC10" href="#TOC1">STRUCTURE TYPES</a>  210:  211: The types of the opaque structures that are used for compiled 32-bit patterns 212: and JIT stacks are pcre32 and pcre32_jit_stack respectively. The 213: type of the user-accessible structure that is returned by pcre32_study() 214: is pcre32_extra, and the type of the structure that is used for passing 215: data to a callout function is pcre32_callout_block. These structures 216: contain the same fields, with the same names, as their 8-bit counterparts. The 217: only difference is that pointers to character strings are 32-bit instead of 218: 8-bit types. 219:  220:  <a name="SEC11" href="#TOC1">32-BIT FUNCTIONS</a>  221:  222: For every function in the 8-bit library there is a corresponding function in 223: the 32-bit library with a name that starts with pcre32_ instead of 224: pcre_. The prototypes are listed above. In addition, there is one extra 225: function, pcre32_utf32_to_host_byte_order(). This is a utility function 226: that converts a UTF-32 character string to host byte order if necessary. The 227: other 32-bit functions expect the strings they are passed to be in host byte 228: order. 229:  230:  231: The input and output arguments of 232: pcre32_utf32_to_host_byte_order() may point to the same address, that is, 233: conversion in place is supported. The output buffer must be at least as long as 234: the input. 235:  236:  237: The length argument specifies the number of 32-bit data units in the 238: input string; a negative value specifies a zero-terminated string. 239:  240:  241: If byte_order is NULL, it is assumed that the string starts off in host 242: byte order. This may be changed by byte-order marks (BOMs) anywhere in the 243: string (commonly as the first character). 244:  245:  246: If byte_order is not NULL, a non-zero value of the integer to which it 247: points means that the input starts off in host byte order, otherwise the 248: opposite order is assumed. Again, BOMs in the string can change this. The final 249: byte order is passed back at the end of processing. 250:  251:  252: If keep_boms is not zero, byte-order mark characters (0xfeff) are copied 253: into the output string. Otherwise they are discarded. 254:  255:  256: The result of the function is the number of 32-bit units placed into the output 257: buffer, including the zero terminator if the string was zero-terminated. 258:  259:  <a name="SEC12" href="#TOC1">SUBJECT STRING OFFSETS</a>  260:  261: The lengths and starting offsets of subject strings must be specified in 32-bit 262: data units, and the offsets within subject strings that are returned by the 263: matching functions are in also 32-bit units rather than bytes. 264:  265:  <a name="SEC13" href="#TOC1">NAMED SUBPATTERNS</a>  266:  267: The name-to-number translation table that is maintained for named subpatterns 268: uses 32-bit characters. The pcre32_get_stringtable_entries() function 269: returns the length of each entry in the table as the number of 32-bit data 270: units. 271:  272:  <a name="SEC14" href="#TOC1">OPTION NAMES</a>  273:  274: There are two new general option names, PCRE_UTF32 and PCRE_NO_UTF32_CHECK, 275: which correspond to PCRE_UTF8 and PCRE_NO_UTF8_CHECK in the 8-bit library. In 276: fact, these new options define the same bits in the options word. There is a 277: discussion about the 278: <a href="pcreunicode.html#utf32strings">validity of UTF-32 strings</a> 279: in the 280: <a href="pcreunicode.html">pcreunicode</a> 281: page. 282:  283:  284: For the pcre32_config() function there is an option PCRE_CONFIG_UTF32 285: that returns 1 if UTF-32 support is configured, otherwise 0. If this option is 286: given to pcre_config() or pcre16_config(), or if the 287: PCRE_CONFIG_UTF8 or PCRE_CONFIG_UTF16 option is given to pcre32_config(), 288: the result is the PCRE_ERROR_BADOPTION error. 289:  290:  <a name="SEC15" href="#TOC1">CHARACTER CODES</a>  291:  292: In 32-bit mode, when PCRE_UTF32 is not set, character values are treated in the 293: same way as in 8-bit, non UTF-8 mode, except, of course, that they can range 294: from 0 to 0x7fffffff instead of 0 to 0xff. Character types for characters less 295: than 0xff can therefore be influenced by the locale in the same way as before. 296: Characters greater than 0xff have only one case, and no "type" (such as letter 297: or digit). 298:  299:  300: In UTF-32 mode, the character code is Unicode, in the range 0 to 0x10ffff, with 301: the exception of values in the range 0xd800 to 0xdfff because those are 302: "surrogate" values that are ill-formed in UTF-32. 303:  304:  305: A UTF-32 string can indicate its endianness by special code knows as a 306: byte-order mark (BOM). The PCRE functions do not handle this, expecting strings 307: to be in host byte order. A utility function called 308: pcre32_utf32_to_host_byte_order() is provided to help with this (see 309: above). 310:  311:  <a name="SEC16" href="#TOC1">ERROR NAMES</a>  312:  313: The error PCRE_ERROR_BADUTF32 corresponds to its 8-bit counterpart. 314: The error PCRE_ERROR_BADMODE is given when a compiled 315: pattern is passed to a function that processes patterns in the other 316: mode, for example, if a pattern compiled with pcre_compile() is passed to 317: pcre32_exec(). 318:  319:  320: There are new error codes whose names begin with PCRE_UTF32_ERR for invalid 321: UTF-32 strings, corresponding to the PCRE_UTF8_ERR codes for UTF-8 strings that 322: are described in the section entitled 323: <a href="pcreapi.html#badutf8reasons">"Reason codes for invalid UTF-8 strings"</a> 324: in the main 325: <a href="pcreapi.html">pcreapi</a> 326: page. The UTF-32 errors are: 327: <pre> 328: PCRE_UTF32_ERR1 Surrogate character (range from 0xd800 to 0xdfff) 329: PCRE_UTF32_ERR2 Non-character 330: PCRE_UTF32_ERR3 Character > 0x10ffff 331: </PRE> 332:  333:  <a name="SEC17" href="#TOC1">ERROR TEXTS</a>  334:  335: If there is an error while compiling a pattern, the error text that is passed 336: back by pcre32_compile() or pcre32_compile2() is still an 8-bit 337: character string, zero-terminated. 338:  339:  <a name="SEC18" href="#TOC1">CALLOUTS</a>  340:  341: The subject and mark fields in the callout block that is passed to 342: a callout function point to 32-bit vectors. 343:  344:  <a name="SEC19" href="#TOC1">TESTING</a>  345:  346: The pcretest program continues to operate with 8-bit input and output 347: files, but it can be used for testing the 32-bit library. If it is run with the 348: command line option -32, patterns and subject strings are converted from 349: 8-bit to 32-bit before being passed to PCRE, and the 32-bit library functions 350: are used instead of the 8-bit ones. Returned 32-bit strings are converted to 351: 8-bit for output. If both the 8-bit and the 16-bit libraries were not compiled, 352: pcretest defaults to 32-bit and the -32 option is ignored. 353:  354:  355: When PCRE is being built, the RunTest script that is called by "make 356: check" uses the pcretest -C option to discover which of the 8-bit, 357: 16-bit and 32-bit libraries has been built, and runs the tests appropriately. 358:  359:  <a name="SEC20" href="#TOC1">NOT SUPPORTED IN 32-BIT MODE</a>  360:  361: Not all the features of the 8-bit library are available with the 32-bit 362: library. The C++ and POSIX wrapper functions support only the 8-bit library, 363: and the pcregrep program is at present 8-bit only. 364:  365:  <a name="SEC21" href="#TOC1">AUTHOR</a>  366:  367: Philip Hazel 368:   369: University Computing Service 370:   371: Cambridge CB2 3QH, England. 372:   373:  374:  <a name="SEC22" href="#TOC1">REVISION</a>  375:  376: Last updated: 12 May 2013 377:   378: Copyright © 1997-2013 University of Cambridge. 379:   380:  381: Return to the <a href="index.html">PCRE index page</a>. 382: 