libs/regex/doc/html/boost_regex/ref/posix.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   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">&lt;</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">&gt;</span>
  43 </pre>
  44 <p>
  45         or:
  46       </p>
  47 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</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">&gt;</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">&lt;</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">&gt;</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-&gt;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 &#169; 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>