1<html> 2<head> 3<title>pcreposix specification</title> 4</head> 5<body bgcolor="#FFFFFF" text="#00005A" link="#0066FF" alink="#3399FF" vlink="#2222BB"> 6<h1>pcreposix man page</h1> 7<p> 8Return to the <a href="index.html">PCRE index page</a>. 9</p> 10<p> 11This page is part of the PCRE HTML documentation. It was generated automatically 12from the original man page. If there is any nonsense in it, please consult the 13man page, in case the conversion went wrong. 14<br> 15<ul> 16<li><a name="TOC1" href="#SEC1">SYNOPSIS</a> 17<li><a name="TOC2" href="#SEC2">DESCRIPTION</a> 18<li><a name="TOC3" href="#SEC3">COMPILING A PATTERN</a> 19<li><a name="TOC4" href="#SEC4">MATCHING NEWLINE CHARACTERS</a> 20<li><a name="TOC5" href="#SEC5">MATCHING A PATTERN</a> 21<li><a name="TOC6" href="#SEC6">ERROR MESSAGES</a> 22<li><a name="TOC7" href="#SEC7">MEMORY USAGE</a> 23<li><a name="TOC8" href="#SEC8">AUTHOR</a> 24<li><a name="TOC9" href="#SEC9">REVISION</a> 25</ul> 26<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br> 27<P> 28<b>#include <pcreposix.h></b> 29</P> 30<P> 31<b>int regcomp(regex_t *<i>preg</i>, const char *<i>pattern</i>,</b> 32<b> int <i>cflags</i>);</b> 33<br> 34<br> 35<b>int regexec(regex_t *<i>preg</i>, const char *<i>string</i>,</b> 36<b> size_t <i>nmatch</i>, regmatch_t <i>pmatch</i>[], int <i>eflags</i>);</b> 37<b> size_t regerror(int <i>errcode</i>, const regex_t *<i>preg</i>,</b> 38<b> char *<i>errbuf</i>, size_t <i>errbuf_size</i>);</b> 39<br> 40<br> 41<b>void regfree(regex_t *<i>preg</i>);</b> 42</P> 43<br><a name="SEC2" href="#TOC1">DESCRIPTION</a><br> 44<P> 45This set of functions provides a POSIX-style API for the PCRE regular 46expression 8-bit library. See the 47<a href="pcreapi.html"><b>pcreapi</b></a> 48documentation for a description of PCRE's native API, which contains much 49additional functionality. There is no POSIX-style wrapper for PCRE's 16-bit 50and 32-bit library. 51</P> 52<P> 53The functions described here are just wrapper functions that ultimately call 54the PCRE native API. Their prototypes are defined in the <b>pcreposix.h</b> 55header file, and on Unix systems the library itself is called 56<b>pcreposix.a</b>, so can be accessed by adding <b>-lpcreposix</b> to the 57command for linking an application that uses them. Because the POSIX functions 58call the native ones, it is also necessary to add <b>-lpcre</b>. 59</P> 60<P> 61I have implemented only those POSIX option bits that can be reasonably mapped 62to PCRE native options. In addition, the option REG_EXTENDED is defined with 63the value zero. This has no effect, but since programs that are written to the 64POSIX interface often use it, this makes it easier to slot in PCRE as a 65replacement library. Other POSIX options are not even defined. 66</P> 67<P> 68There are also some other options that are not defined by POSIX. These have 69been added at the request of users who want to make use of certain 70PCRE-specific features via the POSIX calling interface. 71</P> 72<P> 73When PCRE is called via these functions, it is only the API that is POSIX-like 74in style. The syntax and semantics of the regular expressions themselves are 75still those of Perl, subject to the setting of various PCRE options, as 76described below. "POSIX-like in style" means that the API approximates to the 77POSIX definition; it is not fully POSIX-compatible, and in multi-byte encoding 78domains it is probably even less compatible. 79</P> 80<P> 81The header for these functions is supplied as <b>pcreposix.h</b> to avoid any 82potential clash with other POSIX libraries. It can, of course, be renamed or 83aliased as <b>regex.h</b>, which is the "correct" name. It provides two 84structure types, <i>regex_t</i> for compiled internal forms, and 85<i>regmatch_t</i> for returning captured substrings. It also defines some 86constants whose names start with "REG_"; these are used for setting options and 87identifying error codes. 88</P> 89<br><a name="SEC3" href="#TOC1">COMPILING A PATTERN</a><br> 90<P> 91The function <b>regcomp()</b> is called to compile a pattern into an 92internal form. The pattern is a C string terminated by a binary zero, and 93is passed in the argument <i>pattern</i>. The <i>preg</i> argument is a pointer 94to a <b>regex_t</b> structure that is used as a base for storing information 95about the compiled regular expression. 96</P> 97<P> 98The argument <i>cflags</i> is either zero, or contains one or more of the bits 99defined by the following macros: 100<pre> 101 REG_DOTALL 102</pre> 103The PCRE_DOTALL option is set when the regular expression is passed for 104compilation to the native function. Note that REG_DOTALL is not part of the 105POSIX standard. 106<pre> 107 REG_ICASE 108</pre> 109The PCRE_CASELESS option is set when the regular expression is passed for 110compilation to the native function. 111<pre> 112 REG_NEWLINE 113</pre> 114The PCRE_MULTILINE option is set when the regular expression is passed for 115compilation to the native function. Note that this does <i>not</i> mimic the 116defined POSIX behaviour for REG_NEWLINE (see the following section). 117<pre> 118 REG_NOSUB 119</pre> 120The PCRE_NO_AUTO_CAPTURE option is set when the regular expression is passed 121for compilation to the native function. In addition, when a pattern that is 122compiled with this flag is passed to <b>regexec()</b> for matching, the 123<i>nmatch</i> and <i>pmatch</i> arguments are ignored, and no captured strings 124are returned. 125<pre> 126 REG_UCP 127</pre> 128The PCRE_UCP option is set when the regular expression is passed for 129compilation to the native function. This causes PCRE to use Unicode properties 130when matchine \d, \w, etc., instead of just recognizing ASCII values. Note 131that REG_UTF8 is not part of the POSIX standard. 132<pre> 133 REG_UNGREEDY 134</pre> 135The PCRE_UNGREEDY option is set when the regular expression is passed for 136compilation to the native function. Note that REG_UNGREEDY is not part of the 137POSIX standard. 138<pre> 139 REG_UTF8 140</pre> 141The PCRE_UTF8 option is set when the regular expression is passed for 142compilation to the native function. This causes the pattern itself and all data 143strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF8 144is not part of the POSIX standard. 145</P> 146<P> 147In the absence of these flags, no options are passed to the native function. 148This means the the regex is compiled with PCRE default semantics. In 149particular, the way it handles newline characters in the subject string is the 150Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only 151<i>some</i> of the effects specified for REG_NEWLINE. It does not affect the way 152newlines are matched by . (they are not) or by a negative class such as [^a] 153(they are). 154</P> 155<P> 156The yield of <b>regcomp()</b> is zero on success, and non-zero otherwise. The 157<i>preg</i> structure is filled in on success, and one member of the structure 158is public: <i>re_nsub</i> contains the number of capturing subpatterns in 159the regular expression. Various error codes are defined in the header file. 160</P> 161<P> 162NOTE: If the yield of <b>regcomp()</b> is non-zero, you must not attempt to 163use the contents of the <i>preg</i> structure. If, for example, you pass it to 164<b>regexec()</b>, the result is undefined and your program is likely to crash. 165</P> 166<br><a name="SEC4" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br> 167<P> 168This area is not simple, because POSIX and Perl take different views of things. 169It is not possible to get PCRE to obey POSIX semantics, but then PCRE was never 170intended to be a POSIX engine. The following table lists the different 171possibilities for matching newline characters in PCRE: 172<pre> 173 Default Change with 174 175 . matches newline no PCRE_DOTALL 176 newline matches [^a] yes not changeable 177 $ matches \n at end yes PCRE_DOLLARENDONLY 178 $ matches \n in middle no PCRE_MULTILINE 179 ^ matches \n in middle no PCRE_MULTILINE 180</pre> 181This is the equivalent table for POSIX: 182<pre> 183 Default Change with 184 185 . matches newline yes REG_NEWLINE 186 newline matches [^a] yes REG_NEWLINE 187 $ matches \n at end no REG_NEWLINE 188 $ matches \n in middle no REG_NEWLINE 189 ^ matches \n in middle no REG_NEWLINE 190</pre> 191PCRE's behaviour is the same as Perl's, except that there is no equivalent for 192PCRE_DOLLAR_ENDONLY in Perl. In both PCRE and Perl, there is no way to stop 193newline from matching [^a]. 194</P> 195<P> 196The default POSIX newline handling can be obtained by setting PCRE_DOTALL and 197PCRE_DOLLAR_ENDONLY, but there is no way to make PCRE behave exactly as for the 198REG_NEWLINE action. 199</P> 200<br><a name="SEC5" href="#TOC1">MATCHING A PATTERN</a><br> 201<P> 202The function <b>regexec()</b> is called to match a compiled pattern <i>preg</i> 203against a given <i>string</i>, which is by default terminated by a zero byte 204(but see REG_STARTEND below), subject to the options in <i>eflags</i>. These can 205be: 206<pre> 207 REG_NOTBOL 208</pre> 209The PCRE_NOTBOL option is set when calling the underlying PCRE matching 210function. 211<pre> 212 REG_NOTEMPTY 213</pre> 214The PCRE_NOTEMPTY option is set when calling the underlying PCRE matching 215function. Note that REG_NOTEMPTY is not part of the POSIX standard. However, 216setting this option can give more POSIX-like behaviour in some situations. 217<pre> 218 REG_NOTEOL 219</pre> 220The PCRE_NOTEOL option is set when calling the underlying PCRE matching 221function. 222<pre> 223 REG_STARTEND 224</pre> 225The string is considered to start at <i>string</i> + <i>pmatch[0].rm_so</i> and 226to have a terminating NUL located at <i>string</i> + <i>pmatch[0].rm_eo</i> 227(there need not actually be a NUL at that location), regardless of the value of 228<i>nmatch</i>. This is a BSD extension, compatible with but not specified by 229IEEE Standard 1003.2 (POSIX.2), and should be used with caution in software 230intended to be portable to other systems. Note that a non-zero <i>rm_so</i> does 231not imply REG_NOTBOL; REG_STARTEND affects only the location of the string, not 232how it is matched. 233</P> 234<P> 235If the pattern was compiled with the REG_NOSUB flag, no data about any matched 236strings is returned. The <i>nmatch</i> and <i>pmatch</i> arguments of 237<b>regexec()</b> are ignored. 238</P> 239<P> 240If the value of <i>nmatch</i> is zero, or if the value <i>pmatch</i> is NULL, 241no data about any matched strings is returned. 242</P> 243<P> 244Otherwise,the portion of the string that was matched, and also any captured 245substrings, are returned via the <i>pmatch</i> argument, which points to an 246array of <i>nmatch</i> structures of type <i>regmatch_t</i>, containing the 247members <i>rm_so</i> and <i>rm_eo</i>. These contain the offset to the first 248character of each substring and the offset to the first character after the end 249of each substring, respectively. The 0th element of the vector relates to the 250entire portion of <i>string</i> that was matched; subsequent elements relate to 251the capturing subpatterns of the regular expression. Unused entries in the 252array have both structure members set to -1. 253</P> 254<P> 255A successful match yields a zero return; various error codes are defined in the 256header file, of which REG_NOMATCH is the "expected" failure code. 257</P> 258<br><a name="SEC6" href="#TOC1">ERROR MESSAGES</a><br> 259<P> 260The <b>regerror()</b> function maps a non-zero errorcode from either 261<b>regcomp()</b> or <b>regexec()</b> to a printable message. If <i>preg</i> is not 262NULL, the error should have arisen from the use of that structure. A message 263terminated by a binary zero is placed in <i>errbuf</i>. The length of the 264message, including the zero, is limited to <i>errbuf_size</i>. The yield of the 265function is the size of buffer needed to hold the whole message. 266</P> 267<br><a name="SEC7" href="#TOC1">MEMORY USAGE</a><br> 268<P> 269Compiling a regular expression causes memory to be allocated and associated 270with the <i>preg</i> structure. The function <b>regfree()</b> frees all such 271memory, after which <i>preg</i> may no longer be used as a compiled expression. 272</P> 273<br><a name="SEC8" href="#TOC1">AUTHOR</a><br> 274<P> 275Philip Hazel 276<br> 277University Computing Service 278<br> 279Cambridge CB2 3QH, England. 280<br> 281</P> 282<br><a name="SEC9" href="#TOC1">REVISION</a><br> 283<P> 284Last updated: 09 January 2012 285<br> 286Copyright © 1997-2012 University of Cambridge. 287<br> 288<p> 289Return to the <a href="index.html">PCRE index page</a>. 290</p> 291