1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>POSIX Compatible C API's</title> 5<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="../../index.html" title="Boost.Regex 5.1.4"> 8<link rel="up" href="../ref.html" title="Reference"> 9<link rel="prev" href="non_std_strings/mfc_strings/mfc_iter.html" title="Iterating Over the Matches Within An MFC String"> 10<link rel="next" href="concepts.html" title="Concepts"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<table cellpadding="2" width="100%"><tr> 14<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td> 15<td align="center"><a href="../../../../../../index.html">Home</a></td> 16<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td> 17<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 18<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 19<td align="center"><a href="../../../../../../more/index.htm">More</a></td> 20</tr></table> 21<hr> 22<div class="spirit-nav"> 23<a accesskey="p" href="non_std_strings/mfc_strings/mfc_iter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 24</div> 25<div class="section"> 26<div class="titlepage"><div><div><h3 class="title"> 27<a name="boost_regex.ref.posix"></a><a class="link" href="posix.html" title="POSIX Compatible C API's">POSIX Compatible C API's</a> 28</h3></div></div></div> 29<div class="note"><table border="0" summary="Note"> 30<tr> 31<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 32<th align="left">Note</th> 33</tr> 34<tr><td align="left" valign="top"><p> 35 this is an abridged reference to the POSIX API functions, these are provided 36 for compatibility with other libraries, rather than as an API to be used 37 in new code (unless you need access from a language other than C++). This 38 version of these functions should also happily coexist with other versions, 39 as the names used are macros that expand to the actual function names. 40 </p></td></tr> 41</table></div> 42<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">cregex</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span> 43</pre> 44<p> 45 or: 46 </p> 47<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span> 48</pre> 49<p> 50 The following functions are available for users who need a POSIX compatible 51 C library, they are available in both Unicode and narrow character versions, 52 the standard POSIX API names are macros that expand to one version or the 53 other depending upon whether UNICODE is defined or not. 54 </p> 55<div class="important"><table border="0" summary="Important"> 56<tr> 57<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td> 58<th align="left">Important</th> 59</tr> 60<tr><td align="left" valign="top"><p> 61 Note that all the symbols defined here are enclosed inside namespace <code class="computeroutput"><span class="identifier">boost</span></code> when used in C++ programs, unless 62 you use <code class="computeroutput"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">regex</span><span class="special">.</span><span class="identifier">h</span><span class="special">></span></code> 63 instead - in which case the symbols are still defined in namespace boost, 64 but are made available in the global namespace as well. 65 </p></td></tr> 66</table></div> 67<p> 68 The functions are defined as: 69 </p> 70<pre class="programlisting"><span class="keyword">extern</span> <span class="string">"C"</span> <span class="special">{</span> 71 72<span class="keyword">struct</span> <span class="identifier">regex_tA</span><span class="special">;</span> 73<span class="keyword">struct</span> <span class="identifier">regex_tW</span><span class="special">;</span> 74 75<span class="keyword">int</span> <span class="identifier">regcompA</span><span class="special">(</span><span class="identifier">regex_tA</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*,</span> <span class="keyword">int</span><span class="special">);</span> 76<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">regerrorA</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">regex_tA</span><span class="special">*,</span> <span class="keyword">char</span><span class="special">*,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">);</span> 77<span class="keyword">int</span> <span class="identifier">regexecA</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">regex_tA</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">regmatch_t</span><span class="special">*,</span> <span class="keyword">int</span><span class="special">);</span> 78<span class="keyword">void</span> <span class="identifier">regfreeA</span><span class="special">(</span><span class="identifier">regex_tA</span><span class="special">*);</span> 79 80<span class="keyword">int</span> <span class="identifier">regcompW</span><span class="special">(</span><span class="identifier">regex_tW</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*,</span> <span class="keyword">int</span><span class="special">);</span> 81<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">regerrorW</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">regex_tW</span><span class="special">*,</span> <span class="keyword">wchar_t</span><span class="special">*,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">);</span> 82<span class="keyword">int</span> <span class="identifier">regexecW</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">regex_tW</span><span class="special">*,</span> <span class="keyword">const</span> <span class="keyword">wchar_t</span><span class="special">*,</span> <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">,</span> <span class="identifier">regmatch_t</span><span class="special">*,</span> <span class="keyword">int</span><span class="special">);</span> 83<span class="keyword">void</span> <span class="identifier">regfreeW</span><span class="special">(</span><span class="identifier">regex_tW</span><span class="special">*);</span> 84 85<span class="preprocessor">#ifdef</span> <span class="identifier">UNICODE</span> 86<span class="preprocessor">#define</span> <span class="identifier">regcomp</span> <span class="identifier">regcompW</span> 87<span class="preprocessor">#define</span> <span class="identifier">regerror</span> <span class="identifier">regerrorW</span> 88<span class="preprocessor">#define</span> <span class="identifier">regexec</span> <span class="identifier">regexecW</span> 89<span class="preprocessor">#define</span> <span class="identifier">regfree</span> <span class="identifier">regfreeW</span> 90<span class="preprocessor">#define</span> <span class="identifier">regex_t</span> <span class="identifier">regex_tW</span> 91<span class="preprocessor">#else</span> 92<span class="preprocessor">#define</span> <span class="identifier">regcomp</span> <span class="identifier">regcompA</span> 93<span class="preprocessor">#define</span> <span class="identifier">regerror</span> <span class="identifier">regerrorA</span> 94<span class="preprocessor">#define</span> <span class="identifier">regexec</span> <span class="identifier">regexecA</span> 95<span class="preprocessor">#define</span> <span class="identifier">regfree</span> <span class="identifier">regfreeA</span> 96<span class="preprocessor">#define</span> <span class="identifier">regex_t</span> <span class="identifier">regex_tA</span> 97<span class="preprocessor">#endif</span> 98<span class="special">}</span> 99</pre> 100<p> 101 All the functions operate on structure regex_t, which exposes two public 102 members: 103 </p> 104<div class="informaltable"><table class="table"> 105<colgroup> 106<col> 107<col> 108</colgroup> 109<thead><tr> 110<th> 111 <p> 112 Member 113 </p> 114 </th> 115<th> 116 <p> 117 Meaning 118 </p> 119 </th> 120</tr></thead> 121<tbody> 122<tr> 123<td> 124 <p> 125 <code class="computeroutput"><span class="keyword">unsigned</span> <span class="keyword">int</span> 126 <span class="identifier">re_nsub</span></code> 127 </p> 128 </td> 129<td> 130 <p> 131 This is filled in by <code class="computeroutput"><span class="identifier">regcomp</span></code> 132 and indicates the number of sub-expressions contained in the regular 133 expression. 134 </p> 135 </td> 136</tr> 137<tr> 138<td> 139 <p> 140 <code class="computeroutput"><span class="keyword">const</span> <span class="identifier">TCHAR</span><span class="special">*</span> <span class="identifier">re_endp</span></code> 141 </p> 142 </td> 143<td> 144 <p> 145 Points to the end of the expression to compile when the flag REG_PEND 146 is set. 147 </p> 148 </td> 149</tr> 150</tbody> 151</table></div> 152<div class="note"><table border="0" summary="Note"> 153<tr> 154<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 155<th align="left">Note</th> 156</tr> 157<tr><td align="left" valign="top"><p> 158 <code class="computeroutput"><span class="identifier">regex_t</span></code> is actually a 159 <code class="computeroutput"><span class="preprocessor">#define</span></code> - it is either 160 <code class="computeroutput"><span class="identifier">regex_tA</span></code> or <code class="computeroutput"><span class="identifier">regex_tW</span></code> depending upon whether <code class="computeroutput"><span class="identifier">UNICODE</span></code> is defined or not, <code class="computeroutput"><span class="identifier">TCHAR</span></code> is either <code class="computeroutput"><span class="keyword">char</span></code> 161 or <code class="computeroutput"><span class="keyword">wchar_t</span></code> again depending 162 upon the macro <code class="computeroutput"><span class="identifier">UNICODE</span></code>. 163 </p></td></tr> 164</table></div> 165<a name="regcomp"></a><h5> 166<a name="boost_regex.ref.posix.h0"></a> 167 <span class="phrase"><a name="boost_regex.ref.posix.regcomp"></a></span><a class="link" href="posix.html#boost_regex.ref.posix.regcomp">regcomp</a> 168 </h5> 169<p> 170 <code class="computeroutput"><span class="identifier">regcomp</span></code> takes a pointer to 171 a <code class="computeroutput"><span class="identifier">regex_t</span></code>, a pointer to the 172 expression to compile and a flags parameter which can be a combination of: 173 </p> 174<div class="informaltable"><table class="table"> 175<colgroup> 176<col> 177<col> 178</colgroup> 179<thead><tr> 180<th> 181 <p> 182 Flag 183 </p> 184 </th> 185<th> 186 <p> 187 Meaning 188 </p> 189 </th> 190</tr></thead> 191<tbody> 192<tr> 193<td> 194 <p> 195 REG_EXTENDED 196 </p> 197 </td> 198<td> 199 <p> 200 Compiles modern regular expressions. Equivalent to <code class="computeroutput"><span class="identifier">regbase</span><span class="special">::</span><span class="identifier">char_classes</span> <span class="special">|</span> 201 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">intervals</span> <span class="special">|</span> 202 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">bk_refs</span></code>. 203 </p> 204 </td> 205</tr> 206<tr> 207<td> 208 <p> 209 REG_BASIC 210 </p> 211 </td> 212<td> 213 <p> 214 Compiles basic (obsolete) regular expression syntax. Equivalent 215 to <code class="computeroutput"><span class="identifier">regbase</span><span class="special">::</span><span class="identifier">char_classes</span> <span class="special">|</span> 216 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">intervals</span> <span class="special">|</span> 217 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">limited_ops</span> <span class="special">|</span> 218 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">bk_braces</span> <span class="special">|</span> 219 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">bk_parens</span> <span class="special">|</span> 220 <span class="identifier">regbase</span><span class="special">::</span><span class="identifier">bk_refs</span></code>. 221 </p> 222 </td> 223</tr> 224<tr> 225<td> 226 <p> 227 REG_NOSPEC 228 </p> 229 </td> 230<td> 231 <p> 232 All characters are ordinary, the expression is a literal string. 233 </p> 234 </td> 235</tr> 236<tr> 237<td> 238 <p> 239 REG_ICASE 240 </p> 241 </td> 242<td> 243 <p> 244 Compiles for matching that ignores character case. 245 </p> 246 </td> 247</tr> 248<tr> 249<td> 250 <p> 251 REG_NOSUB 252 </p> 253 </td> 254<td> 255 <p> 256 Has no effect in this library. 257 </p> 258 </td> 259</tr> 260<tr> 261<td> 262 <p> 263 REG_NEWLINE 264 </p> 265 </td> 266<td> 267 <p> 268 When this flag is set a dot does not match the newline character. 269 </p> 270 </td> 271</tr> 272<tr> 273<td> 274 <p> 275 REG_PEND 276 </p> 277 </td> 278<td> 279 <p> 280 When this flag is set the re_endp parameter of the regex_t structure 281 must point to the end of the regular expression to compile. 282 </p> 283 </td> 284</tr> 285<tr> 286<td> 287 <p> 288 REG_NOCOLLATE 289 </p> 290 </td> 291<td> 292 <p> 293 When this flag is set then locale dependent collation for character 294 ranges is turned off. 295 </p> 296 </td> 297</tr> 298<tr> 299<td> 300 <p> 301 REG_ESCAPE_IN_LISTS 302 </p> 303 </td> 304<td> 305 <p> 306 When this flag is set, then escape sequences are permitted in bracket 307 expressions (character sets). 308 </p> 309 </td> 310</tr> 311<tr> 312<td> 313 <p> 314 REG_NEWLINE_ALT 315 </p> 316 </td> 317<td> 318 <p> 319 When this flag is set then the newline character is equivalent 320 to the alternation operator |. 321 </p> 322 </td> 323</tr> 324<tr> 325<td> 326 <p> 327 REG_PERL 328 </p> 329 </td> 330<td> 331 <p> 332 Compiles Perl like regular expressions. 333 </p> 334 </td> 335</tr> 336<tr> 337<td> 338 <p> 339 REG_AWK 340 </p> 341 </td> 342<td> 343 <p> 344 A shortcut for awk-like behavior: <code class="computeroutput"><span class="identifier">REG_EXTENDED</span> 345 <span class="special">|</span> <span class="identifier">REG_ESCAPE_IN_LISTS</span></code> 346 </p> 347 </td> 348</tr> 349<tr> 350<td> 351 <p> 352 REG_GREP 353 </p> 354 </td> 355<td> 356 <p> 357 A shortcut for grep like behavior: <code class="computeroutput"><span class="identifier">REG_BASIC</span> 358 <span class="special">|</span> <span class="identifier">REG_NEWLINE_ALT</span></code> 359 </p> 360 </td> 361</tr> 362<tr> 363<td> 364 <p> 365 REG_EGREP 366 </p> 367 </td> 368<td> 369 <p> 370 A shortcut for egrep like behavior: <code class="computeroutput"><span class="identifier">REG_EXTENDED</span> 371 <span class="special">|</span> <span class="identifier">REG_NEWLINE_ALT</span></code> 372 </p> 373 </td> 374</tr> 375</tbody> 376</table></div> 377<a name="regerror"></a><h5> 378<a name="boost_regex.ref.posix.h1"></a> 379 <span class="phrase"><a name="boost_regex.ref.posix.regerror"></a></span><a class="link" href="posix.html#boost_regex.ref.posix.regerror">regerror</a> 380 </h5> 381<p> 382 regerror takes the following parameters, it maps an error code to a human 383 readable string: 384 </p> 385<div class="informaltable"><table class="table"> 386<colgroup> 387<col> 388<col> 389</colgroup> 390<thead><tr> 391<th> 392 <p> 393 Parameter 394 </p> 395 </th> 396<th> 397 <p> 398 Meaning 399 </p> 400 </th> 401</tr></thead> 402<tbody> 403<tr> 404<td> 405 <p> 406 int code 407 </p> 408 </td> 409<td> 410 <p> 411 The error code. 412 </p> 413 </td> 414</tr> 415<tr> 416<td> 417 <p> 418 const regex_t* e 419 </p> 420 </td> 421<td> 422 <p> 423 The regular expression (can be null). 424 </p> 425 </td> 426</tr> 427<tr> 428<td> 429 <p> 430 char* buf 431 </p> 432 </td> 433<td> 434 <p> 435 The buffer to fill in with the error message. 436 </p> 437 </td> 438</tr> 439<tr> 440<td> 441 <p> 442 unsigned int buf_size 443 </p> 444 </td> 445<td> 446 <p> 447 The length of buf. 448 </p> 449 </td> 450</tr> 451</tbody> 452</table></div> 453<p> 454 If the error code is OR'ed with REG_ITOA then the message that results is 455 the printable name of the code rather than a message, for example "REG_BADPAT". 456 If the code is REG_ATIO then e must not be null and e->re_pend must point 457 to the printable name of an error code, the return value is then the value 458 of the error code. For any other value of code, the return value is the number 459 of characters in the error message, if the return value is greater than or 460 equal to buf_size then regerror will have to be called again with a larger 461 buffer. 462 </p> 463<a name="regexec"></a><h5> 464<a name="boost_regex.ref.posix.h2"></a> 465 <span class="phrase"><a name="boost_regex.ref.posix.regexec"></a></span><a class="link" href="posix.html#boost_regex.ref.posix.regexec">regexec</a> 466 </h5> 467<p> 468 regexec finds the first occurrence of expression e within string buf. If 469 len is non-zero then <span class="emphasis"><em>*m</em></span> is filled in with what matched 470 the regular expression, m[0] contains what matched the whole string, m[1] 471 the first sub-expression etc, see regmatch_t in the header file declaration 472 for more details. The eflags parameter can be a combination of: 473 </p> 474<div class="informaltable"><table class="table"> 475<colgroup> 476<col> 477<col> 478</colgroup> 479<thead><tr> 480<th> 481 <p> 482 Flag 483 </p> 484 </th> 485<th> 486 <p> 487 Meaning 488 </p> 489 </th> 490</tr></thead> 491<tbody> 492<tr> 493<td> 494 <p> 495 REG_NOTBOL 496 </p> 497 </td> 498<td> 499 <p> 500 Parameter buf does not represent the start of a line. 501 </p> 502 </td> 503</tr> 504<tr> 505<td> 506 <p> 507 REG_NOTEOL 508 </p> 509 </td> 510<td> 511 <p> 512 Parameter buf does not terminate at the end of a line. 513 </p> 514 </td> 515</tr> 516<tr> 517<td> 518 <p> 519 REG_STARTEND 520 </p> 521 </td> 522<td> 523 <p> 524 The string searched starts at buf + pmatch[0].rm_so and ends at 525 buf + pmatch[0].rm_eo. 526 </p> 527 </td> 528</tr> 529</tbody> 530</table></div> 531<a name="regfree"></a><h5> 532<a name="boost_regex.ref.posix.h3"></a> 533 <span class="phrase"><a name="boost_regex.ref.posix.regfree"></a></span><a class="link" href="posix.html#boost_regex.ref.posix.regfree">regfree</a> 534 </h5> 535<p> 536 <code class="computeroutput"><span class="identifier">regfree</span></code> frees all the memory 537 that was allocated by regcomp. 538 </p> 539</div> 540<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 541<td align="left"></td> 542<td align="right"><div class="copyright-footer">Copyright © 1998-2013 John Maddock<p> 543 Distributed under the Boost Software License, Version 1.0. (See accompanying 544 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 545 </p> 546</div></td> 547</tr></table> 548<hr> 549<div class="spirit-nav"> 550<a accesskey="p" href="non_std_strings/mfc_strings/mfc_iter.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="concepts.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 551</div> 552</body> 553</html> 554
