/[pcre]/code/trunk/doc/pcreapi.3

Diff of /code/trunk/doc/pcreapi.3

Parent Directory | Revision Log | View Patch Patch

-revision 579 by ph10,
Wed Nov 24 17:39:25 2010 UTC
+revision 654 by ph10,
Tue Aug  2 11:00:40 2011 UTC
 Line 436 
 If \fIerrptr\fP is NULL, \fBpcre_compile
  Otherwise, if compilation of a pattern fails, \fBpcre_compile()\fP returns
  NULL, and sets the variable pointed to by \fIerrptr\fP to point to a textual
  error message. This is a static string that is part of the library. You must
- not try to free it. The offset from the start of the pattern to the byte that
+ not try to free it. Normally, the offset from the start of the pattern to the
- was being processed when the error was discovered is placed in the variable
+ byte that was being processed when the error was discovered is placed in the
- pointed to by \fIerroffset\fP, which must not be NULL. If it is, an immediate
+ variable pointed to by \fIerroffset\fP, which must not be NULL (if it is, an
- error is given. Some errors are not detected until checks are carried out when
+ immediate error is given). However, for an invalid UTF-8 string, the offset is
- the whole pattern has been scanned; in this case the offset is set to the end
+ that of the first byte of the failing character. Also, some errors are not
- of the pattern.
+ detected until checks are carried out when the whole pattern has been scanned;
+ in these cases the offset passed back is the length of the pattern.
  .P
  Note that the offset is in bytes, not characters, even in UTF-8 mode. It may
- point into the middle of a UTF-8 character (for example, when
+ sometimes point into the middle of a UTF-8 character.
- PCRE_ERROR_BADUTF8 is returned for an invalid UTF-8 string).
  .P
  If \fBpcre_compile2()\fP is used instead of \fBpcre_compile()\fP, and the
  \fIerrorcodeptr\fP argument is not NULL, a non-zero error code number is
 Line 552 
 unescaped # outside a character class an
  ignored. This is equivalent to Perl's /x option, and it can be changed within a
  pattern by a (?x) option setting.
  .P
- Which characters are interpreted as newlines
+ Which characters are interpreted as newlines is controlled by the options
- is controlled by the options passed to \fBpcre_compile()\fP or by a special
+ passed to \fBpcre_compile()\fP or by a special sequence at the start of the
- sequence at the start of the pattern, as described in the section entitled
+ pattern, as described in the section entitled
  .\" HTML <a href="pcrepattern.html#newlines">
  .\" </a>
  "Newline conventions"
 Line 946 
 one in which it was compiled. Passing ta
  below in the section on matching a pattern.
  .
  .
+ .\" HTML <a name="infoaboutpattern"></a>
  .SH "INFORMATION ABOUT A PATTERN"
  .rs
  .sp
-Line 1547 
 in the main
+Line 1548 
 in the main
  .\"
  page. If an invalid UTF-8 sequence of bytes is found, \fBpcre_exec()\fP returns
  the error PCRE_ERROR_BADUTF8 or, if PCRE_PARTIAL_HARD is set and the problem is
- a truncated UTF-8 character at the end of the subject, PCRE_ERROR_SHORTUTF8. If
+ a truncated UTF-8 character at the end of the subject, PCRE_ERROR_SHORTUTF8. In
- \fIstartoffset\fP contains a value that does not point to the start of a UTF-8
+ both cases, information about the precise nature of the error may also be
- character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is
+ returned (see the descriptions of these errors in the section entitled \fIError
+ return values from\fP \fBpcre_exec()\fP
+ .\" HTML <a href="#errorlist">
+ .\" </a>
+ below).
+ .\"
+ If \fIstartoffset\fP contains a value that does not point to the start of a
+ UTF-8 character (or to the end of the subject), PCRE_ERROR_BADUTF8_OFFSET is
  returned.
  .P
  If you already know that your subject is valid, and you want to skip these
-Line 1717 
 whatever values they previously had.
+Line 1725 
 whatever values they previously had.
  Some convenience functions are provided for extracting the captured substrings
  as separate strings. These are described below.
  .
+ .
  .\" HTML <a name="errorlist"></a>
  .SS "Error return values from \fBpcre_exec()\fP"
  .rs
-Line 1786 
 documentation for details.
+Line 1795 
 documentation for details.
  .sp
    PCRE_ERROR_BADUTF8        (-10)
  .sp
- A string that contains an invalid UTF-8 byte sequence was passed as a subject.
+ A string that contains an invalid UTF-8 byte sequence was passed as a subject,
- However, if PCRE_PARTIAL_HARD is set and the problem is a truncated UTF-8
+ and the PCRE_NO_UTF8_CHECK option was not set. If the size of the output vector
- character at the end of the subject, PCRE_ERROR_SHORTUTF8 is used instead.
+ (\fIovecsize\fP) is at least 2, the byte offset to the start of the the invalid
+ UTF-8 character is placed in the first element, and a reason code is placed in
+ the second element. The reason codes are listed in the
+ .\" HTML <a href="#badutf8reasons">
+ .\" </a>
+ following section.
+ .\"
+ For backward compatibility, if PCRE_PARTIAL_HARD is set and the problem is a
+ truncated UTF-8 character at the end of the subject (reason codes 1 to 5),
+ PCRE_ERROR_SHORTUTF8 is returned instead of PCRE_ERROR_BADUTF8.
  .sp
    PCRE_ERROR_BADUTF8_OFFSET (-11)
  .sp
- The UTF-8 byte sequence that was passed as a subject was valid, but the value
+ The UTF-8 byte sequence that was passed as a subject was checked and found to
- of \fIstartoffset\fP did not point to the beginning of a UTF-8 character or the
+ be valid (the PCRE_NO_UTF8_CHECK option was not set), but the value of
+ \fIstartoffset\fP did not point to the beginning of a UTF-8 character or the
  end of the subject.
  .sp
    PCRE_ERROR_PARTIAL        (-12)
-Line 1837 
 subject, that is, the value in \fIlength
+Line 1856 
 subject, that is, the value in \fIlength
  .sp
    PCRE_ERROR_SHORTUTF8      (-25)
  .sp
- The subject string ended with an incomplete (truncated) UTF-8 character, and
+ This error is returned instead of PCRE_ERROR_BADUTF8 when the subject string
- the PCRE_PARTIAL_HARD option was set. Without this option, PCRE_ERROR_BADUTF8
+ ends with a truncated UTF-8 character and the PCRE_PARTIAL_HARD option is set.
- is returned in this situation.
+ Information about the failure is returned as for PCRE_ERROR_BADUTF8. It is in
+ fact sufficient to detect this case, but this special error code for
+ PCRE_PARTIAL_HARD precedes the implementation of returned information; it is
+ retained for backwards compatibility.
+ .sp
+   PCRE_ERROR_RECURSELOOP    (-26)
+ .sp
+ This error is returned when \fBpcre_exec()\fP detects a recursion loop within
+ the pattern. Specifically, it means that either the whole pattern or a
+ subpattern has been called recursively for the second time at the same position
+ in the subject string. Some simple patterns that might do this are detected and
+ faulted at compile time, but more complicated cases, in particular mutual
+ recursions between two different subpatterns, cannot be detected until run
+ time.
  .P
  Error numbers -16 to -20 and -22 are not used by \fBpcre_exec()\fP.
  .
  .
+ .\" HTML <a name="badutf8reasons"></a>
+ .SS "Reason codes for invalid UTF-8 strings"
+ .rs
+ .sp
+ When \fBpcre_exec()\fP returns either PCRE_ERROR_BADUTF8 or
+ PCRE_ERROR_SHORTUTF8, and the size of the output vector (\fIovecsize\fP) is at
+ least 2, the offset of the start of the invalid UTF-8 character is placed in
+ the first output vector element (\fIovector[0]\fP) and a reason code is placed
+ in the second element (\fIovector[1]\fP). The reason codes are given names in
+ the \fBpcre.h\fP header file:
+ .sp
+   PCRE_UTF8_ERR1
+   PCRE_UTF8_ERR2
+   PCRE_UTF8_ERR3
+   PCRE_UTF8_ERR4
+   PCRE_UTF8_ERR5
+ .sp
+ The string ends with a truncated UTF-8 character; the code specifies how many
+ bytes are missing (1 to 5). Although RFC 3629 restricts UTF-8 characters to be
+ no longer than 4 bytes, the encoding scheme (originally defined by RFC 2279)
+ allows for up to 6 bytes, and this is checked first; hence the possibility of
+or 5 missing bytes.
+ .sp
+   PCRE_UTF8_ERR6
+   PCRE_UTF8_ERR7
+   PCRE_UTF8_ERR8
+   PCRE_UTF8_ERR9
+   PCRE_UTF8_ERR10
+ .sp
+ The two most significant bits of the 2nd, 3rd, 4th, 5th, or 6th byte of the
+ character do not have the binary value 0b10 (that is, either the most
+ significant bit is 0, or the next bit is 1).
+ .sp
+   PCRE_UTF8_ERR11
+   PCRE_UTF8_ERR12
+ .sp
+ A character that is valid by the RFC 2279 rules is either 5 or 6 bytes long;
+ these code points are excluded by RFC 3629.
+ .sp
+   PCRE_UTF8_ERR13
+ .sp
+ A 4-byte character has a value greater than 0x10fff; these code points are
+ excluded by RFC 3629.
+ .sp
+   PCRE_UTF8_ERR14
+ .sp
+ A 3-byte character has a value in the range 0xd800 to 0xdfff; this range of
+ code points are reserved by RFC 3629 for use with UTF-16, and so are excluded
+ from UTF-8.
+ .sp
+   PCRE_UTF8_ERR15
+   PCRE_UTF8_ERR16
+   PCRE_UTF8_ERR17
+   PCRE_UTF8_ERR18
+   PCRE_UTF8_ERR19
+ .sp
+ A 2-, 3-, 4-, 5-, or 6-byte character is "overlong", that is, it codes for a
+ value that can be represented by fewer bytes, which is invalid. For example,
+ the two bytes 0xc0, 0xae give the value 0x2e, whose correct coding uses just
+ one byte.
+ .sp
+   PCRE_UTF8_ERR20
+ .sp
+ The two most significant bits of the first byte of a character have the binary
+ value 0b10 (that is, the most significant bit is 1 and the second is 0). Such a
+ byte can only validly occur as the second or subsequent byte of a multi-byte
+ character.
+ .sp
+   PCRE_UTF8_ERR21
+ .sp
+ The first byte of a character has the value 0xfe or 0xff. These values can
+ never occur in a valid UTF-8 string.
+ .
+ .
  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
  .rs
  .sp
-Line 2039 
 fourth are pointers to variables which a
+Line 2145 
 fourth are pointers to variables which a
  has run, they point to the first and last entries in the name-to-number table
  for the given name. The function itself returns the length of each entry, or
  PCRE_ERROR_NOSUBSTRING (-7) if there are none. The format of the table is
- described above in the section entitled \fIInformation about a pattern\fP.
+ described above in the section entitled \fIInformation about a pattern\fP
+ .\" HTML <a href="#infoaboutpattern">
+ .\" </a>
+ above.
+ .\"
  Given all the relevant entries for the name, you can extract each of their
  numbers, and hence the captured data, if any.
  .
-Line 2169 
 match. There is more discussion of this
+Line 2279 
 match. There is more discussion of this
  .\"
  documentation.
  .
+ .
  .SS "Successful returns from \fBpcre_dfa_exec()\fP"
  .rs
  .sp
-Line 2202 
 matching string is given first. If there
+Line 2313 
 matching string is given first. If there
  \fIovector\fP, the yield of the function is zero, and the vector is filled with
  the longest matches.
  .
+ .
  .SS "Error returns from \fBpcre_dfa_exec()\fP"
  .rs
  .sp
-Line 2267 
 Cambridge CB2 3QH, England.
+Line 2379 
 Cambridge CB2 3QH, England.
  .rs
  .sp
  .nf
- Last updated: 21 November 2010
+ Last updated: 28 July 2011
- Copyright (c) 1997-2010 University of Cambridge.
+ Copyright (c) 1997-2011 University of Cambridge.
  .fi

 Legend:



Removed from v.579
 


changed lines


 
Added in v.654
 Legend:



Removed from v.579
 


changed lines


 
Added in v.654
-Removed from v.579
+Added in v.654

webmaster@exim.org	ViewVC Help
Powered by ViewVC 1.1.12