/[pcre]/code/trunk/doc/html/pcreposix.html

Diff of /code/trunk/doc/html/pcreposix.html

Parent Directory | Revision Log | View Patch Patch

-revision 77 by nigel,
Sat Feb 24 21:40:45 2007 UTC
+revision 453 by ph10,
Fri Sep 18 19:12:35 2009 UTC
 Line 21 
 man page, in case the conversion went wr
  <li><a name="TOC6" href="#SEC6">ERROR MESSAGES</a>
  <li><a name="TOC7" href="#SEC7">MEMORY USAGE</a>
  <li><a name="TOC8" href="#SEC8">AUTHOR</a>
+ <li><a name="TOC9" href="#SEC9">REVISION</a>
  </ul>
  <br><a name="SEC1" href="#TOC1">SYNOPSIS OF POSIX API</a><br>
  <P>
-Line 58 
 command for linking an application that
+Line 59 
 command for linking an application that
  call the native ones, it is also necessary to add <b>-lpcre</b>.
  </P>
  <P>
- I have implemented only those option bits that can be reasonably mapped to PCRE
+ I have implemented only those POSIX option bits that can be reasonably mapped
- native options. In addition, the options REG_EXTENDED and REG_NOSUB are defined
+ to PCRE native options. In addition, the option REG_EXTENDED is defined with
- with the value zero. They have no effect, but since programs that are written
+ the value zero. This has no effect, but since programs that are written to the
- to the POSIX interface often use them, this makes it easier to slot in PCRE as
+ POSIX interface often use it, this makes it easier to slot in PCRE as a
- a replacement library. Other POSIX options are not even defined.
+ replacement library. Other POSIX options are not even defined.
+ </P>
+ <P>
+ There are also some other options that are not defined by POSIX. These have
+ been added at the request of users who want to make use of certain
+ PCRE-specific features via the POSIX calling interface.
  </P>
  <P>
  When PCRE is called via these functions, it is only the API that is POSIX-like
-Line 89 
 The function regcomp() is called
+Line 95 
 The function regcomp() is called
  internal form. The pattern is a C string terminated by a binary zero, and
  is passed in the argument <i>pattern</i>. The <i>preg</i> argument is a pointer
  to a <b>regex_t</b> structure that is used as a base for storing information
- about the compiled expression.
+ about the compiled regular expression.
  </P>
  <P>
  The argument <i>cflags</i> is either zero, or contains one or more of the bits
-Line 97 
 defined by the following macros:
+Line 103 
 defined by the following macros:
  <pre>
    REG_DOTALL
  </pre>
- The PCRE_DOTALL option is set when the expression is passed for compilation to
+ The PCRE_DOTALL option is set when the regular expression is passed for
- the native function. Note that REG_DOTALL is not part of the POSIX standard.
+ compilation to the native function. Note that REG_DOTALL is not part of the
+ POSIX standard.
  <pre>
    REG_ICASE
  </pre>
- The PCRE_CASELESS option is set when the expression is passed for compilation
+ The PCRE_CASELESS option is set when the regular expression is passed for
- to the native function.
+ compilation to the native function.
  <pre>
    REG_NEWLINE
  </pre>
- The PCRE_MULTILINE option is set when the expression is passed for compilation
+ The PCRE_MULTILINE option is set when the regular expression is passed for
- to the native function. Note that this does <i>not</i> mimic the defined POSIX
+ compilation to the native function. Note that this does <i>not</i> mimic the
- behaviour for REG_NEWLINE (see the following section).
+ defined POSIX behaviour for REG_NEWLINE (see the following section).
+ <pre>
+   REG_NOSUB
+ </pre>
+ The PCRE_NO_AUTO_CAPTURE option is set when the regular expression is passed
+ for compilation to the native function. In addition, when a pattern that is
+ compiled with this flag is passed to <b>regexec()</b> for matching, the
+ <i>nmatch</i> and <i>pmatch</i> arguments are ignored, and no captured strings
+ are returned.
+ <pre>
+   REG_UNGREEDY
+ </pre>
+ The PCRE_UNGREEDY option is set when the regular expression is passed for
+ compilation to the native function. Note that REG_UNGREEDY is not part of the
+ POSIX standard.
+ <pre>
+   REG_UTF8
+ </pre>
+ The PCRE_UTF8 option is set when the regular expression is passed for
+ compilation to the native function. This causes the pattern itself and all data
+ strings used for matching it to be treated as UTF-8 strings. Note that REG_UTF8
+ is not part of the POSIX standard.
  </P>
  <P>
  In the absence of these flags, no options are passed to the native function.
-Line 117 
 This means the the regex is compiled wit
+Line 145 
 This means the the regex is compiled wit
  particular, the way it handles newline characters in the subject string is the
  Perl way, not the POSIX way. Note that setting PCRE_MULTILINE has only
  <i>some</i> of the effects specified for REG_NEWLINE. It does not affect the way
- newlines are matched by . (they aren't) or by a negative class such as [^a]
+ newlines are matched by . (they are not) or by a negative class such as [^a]
  (they are).
  </P>
  <P>
-Line 126 
 The yield of regcomp() is zero on
+Line 154 
 The yield of regcomp() is zero on
  is public: <i>re_nsub</i> contains the number of capturing subpatterns in
  the regular expression. Various error codes are defined in the header file.
  </P>
+ <P>
+ NOTE: If the yield of <b>regcomp()</b> is non-zero, you must not attempt to
+ use the contents of the <i>preg</i> structure. If, for example, you pass it to
+ <b>regexec()</b>, the result is undefined and your program is likely to crash.
+ </P>
  <br><a name="SEC4" href="#TOC1">MATCHING NEWLINE CHARACTERS</a><br>
  <P>
  This area is not simple, because POSIX and Perl take different views of things.
-Line 163 
 REG_NEWLINE action.
+Line 196 
 REG_NEWLINE action.
  <br><a name="SEC5" href="#TOC1">MATCHING A PATTERN</a><br>
  <P>
  The function <b>regexec()</b> is called to match a compiled pattern <i>preg</i>
- against a given <i>string</i>, which is terminated by a zero byte, subject to
+ against a given <i>string</i>, which is by default terminated by a zero byte
- the options in <i>eflags</i>. These can be:
+ (but see REG_STARTEND below), subject to the options in <i>eflags</i>. These can
+ be:
  <pre>
    REG_NOTBOL
  </pre>
  The PCRE_NOTBOL option is set when calling the underlying PCRE matching
  function.
  <pre>
+   REG_NOTEMPTY
+ </pre>
+ The PCRE_NOTEMPTY option is set when calling the underlying PCRE matching
+ function. Note that REG_NOTEMPTY is not part of the POSIX standard. However,
+ setting this option can give more POSIX-like behaviour in some situations.
+ <pre>
    REG_NOTEOL
  </pre>
  The PCRE_NOTEOL option is set when calling the underlying PCRE matching
  function.
- </P>
+ <pre>
- <P>
+   REG_STARTEND
- The portion of the string that was matched, and also any captured substrings,
+ </pre>
- are returned via the <i>pmatch</i> argument, which points to an array of
+ The string is considered to start at <i>string</i> + <i>pmatch[0].rm_so</i> and
- <i>nmatch</i> structures of type <i>regmatch_t</i>, containing the members
+ to have a terminating NUL located at <i>string</i> + <i>pmatch[0].rm_eo</i>
- <i>rm_so</i> and <i>rm_eo</i>. These contain the offset to the first character of
+ (there need not actually be a NUL at that location), regardless of the value of
- each substring and the offset to the first character after the end of each
+ <i>nmatch</i>. This is a BSD extension, compatible with but not specified by
- substring, respectively. The 0th element of the vector relates to the entire
+ IEEE Standard 1003.2 (POSIX.2), and should be used with caution in software
- portion of <i>string</i> that was matched; subsequent elements relate to the
+ intended to be portable to other systems. Note that a non-zero <i>rm_so</i> does
- capturing subpatterns of the regular expression. Unused entries in the array
+ not imply REG_NOTBOL; REG_STARTEND affects only the location of the string, not
- have both structure members set to -1.
+ how it is matched.
+ </P>
+ <P>
+ If the pattern was compiled with the REG_NOSUB flag, no data about any matched
+ strings is returned. The <i>nmatch</i> and <i>pmatch</i> arguments of
+ <b>regexec()</b> are ignored.
+ </P>
+ <P>
+ If the value of <i>nmatch</i> is zero, or if the value <i>pmatch</i> is NULL,
+ no data about any matched strings is returned.
+ </P>
+ <P>
+ Otherwise,the portion of the string that was matched, and also any captured
+ substrings, are returned via the <i>pmatch</i> argument, which points to an
+ array of <i>nmatch</i> structures of type <i>regmatch_t</i>, containing the
+ members <i>rm_so</i> and <i>rm_eo</i>. These contain the offset to the first
+ character of each substring and the offset to the first character after the end
+ of each substring, respectively. The 0th element of the vector relates to the
+ entire portion of <i>string</i> that was matched; subsequent elements relate to
+ the capturing subpatterns of the regular expression. Unused entries in the
+ array have both structure members set to -1.
  </P>
  <P>
  A successful match yields a zero return; various error codes are defined in the
-Line 210 
 memory, after which preg may no l
+Line 270 
 memory, after which preg may no l
  <P>
  Philip Hazel
  <br>
- University Computing Service,
+ University Computing Service
+ <br>
+ Cambridge CB2 3QH, England.
  <br>
- Cambridge CB2 3QG, England.
  </P>
+ <br><a name="SEC9" href="#TOC1">REVISION</a><br>
  <P>
- Last updated: 28 February 2005
+ Last updated: 02 September 2009
+ <br>
+ Copyright &copy; 1997-2009 University of Cambridge.
  <br>
- Copyright &copy; 1997-2005 University of Cambridge.
  <p>
  Return to the <a href="index.html">PCRE index page</a>.
  </p>

 Legend:



Removed from v.77
 


changed lines


 
Added in v.453
 Legend:



Removed from v.77
 


changed lines


 
Added in v.453
-Removed from v.77
+Added in v.453

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12