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

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

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 93 by nigel, Sat Feb 24 21:41:42 2007 UTC revision 142 by ph10, Fri Mar 30 15:55:18 2007 UTC
# Line 7  PCRE - Perl-compatible regular expressio Line 7  PCRE - Perl-compatible regular expressio
7  .B #include <pcre.h>  .B #include <pcre.h>
8  .PP  .PP
9  .SM  .SM
 .br  
10  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,
11  .ti +5n  .ti +5n
12  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,
13  .ti +5n  .ti +5n
14  .B const unsigned char *\fItableptr\fP);  .B const unsigned char *\fItableptr\fP);
15  .PP  .PP
 .br  
16  .B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,  .B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,
17  .ti +5n  .ti +5n
18  .B int *\fIerrorcodeptr\fP,  .B int *\fIerrorcodeptr\fP,
# Line 23  PCRE - Perl-compatible regular expressio Line 21  PCRE - Perl-compatible regular expressio
21  .ti +5n  .ti +5n
22  .B const unsigned char *\fItableptr\fP);  .B const unsigned char *\fItableptr\fP);
23  .PP  .PP
 .br  
24  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
25  .ti +5n  .ti +5n
26  .B const char **\fIerrptr\fP);  .B const char **\fIerrptr\fP);
27  .PP  .PP
 .br  
28  .B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"  .B int pcre_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
29  .ti +5n  .ti +5n
30  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
31  .ti +5n  .ti +5n
32  .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);  .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);
33  .PP  .PP
 .br  
34  .B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"  .B int pcre_dfa_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
35  .ti +5n  .ti +5n
36  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
# Line 44  PCRE - Perl-compatible regular expressio Line 39  PCRE - Perl-compatible regular expressio
39  .ti +5n  .ti +5n
40  .B int *\fIworkspace\fP, int \fIwscount\fP);  .B int *\fIworkspace\fP, int \fIwscount\fP);
41  .PP  .PP
 .br  
42  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,
43  .ti +5n  .ti +5n
44  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B const char *\fIsubject\fP, int *\fIovector\fP,
# Line 53  PCRE - Perl-compatible regular expressio Line 47  PCRE - Perl-compatible regular expressio
47  .ti +5n  .ti +5n
48  .B char *\fIbuffer\fP, int \fIbuffersize\fP);  .B char *\fIbuffer\fP, int \fIbuffersize\fP);
49  .PP  .PP
 .br  
50  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,
51  .ti +5n  .ti +5n
52  .B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,  .B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,
53  .ti +5n  .ti +5n
54  .B int \fIbuffersize\fP);  .B int \fIbuffersize\fP);
55  .PP  .PP
 .br  
56  .B int pcre_get_named_substring(const pcre *\fIcode\fP,  .B int pcre_get_named_substring(const pcre *\fIcode\fP,
57  .ti +5n  .ti +5n
58  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B const char *\fIsubject\fP, int *\fIovector\fP,
# Line 69  PCRE - Perl-compatible regular expressio Line 61  PCRE - Perl-compatible regular expressio
61  .ti +5n  .ti +5n
62  .B const char **\fIstringptr\fP);  .B const char **\fIstringptr\fP);
63  .PP  .PP
 .br  
64  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,
65  .ti +5n  .ti +5n
66  .B const char *\fIname\fP);  .B const char *\fIname\fP);
67  .PP  .PP
 .br  
68  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
69  .ti +5n  .ti +5n
70  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);
71  .PP  .PP
 .br  
72  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
73  .ti +5n  .ti +5n
74  .B int \fIstringcount\fP, int \fIstringnumber\fP,  .B int \fIstringcount\fP, int \fIstringnumber\fP,
75  .ti +5n  .ti +5n
76  .B const char **\fIstringptr\fP);  .B const char **\fIstringptr\fP);
77  .PP  .PP
 .br  
78  .B int pcre_get_substring_list(const char *\fIsubject\fP,  .B int pcre_get_substring_list(const char *\fIsubject\fP,
79  .ti +5n  .ti +5n
80  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
81  .PP  .PP
 .br  
82  .B void pcre_free_substring(const char *\fIstringptr\fP);  .B void pcre_free_substring(const char *\fIstringptr\fP);
83  .PP  .PP
 .br  
84  .B void pcre_free_substring_list(const char **\fIstringptr\fP);  .B void pcre_free_substring_list(const char **\fIstringptr\fP);
85  .PP  .PP
 .br  
86  .B const unsigned char *pcre_maketables(void);  .B const unsigned char *pcre_maketables(void);
87  .PP  .PP
 .br  
88  .B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"  .B int pcre_fullinfo(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
89  .ti +5n  .ti +5n
90  .B int \fIwhat\fP, void *\fIwhere\fP);  .B int \fIwhat\fP, void *\fIwhere\fP);
91  .PP  .PP
 .br  
92  .B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int  .B int pcre_info(const pcre *\fIcode\fP, int *\fIoptptr\fP, int
93  .B *\fIfirstcharptr\fP);  .B *\fIfirstcharptr\fP);
94  .PP  .PP
 .br  
95  .B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);  .B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
96  .PP  .PP
 .br  
97  .B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);  .B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
98  .PP  .PP
 .br  
99  .B char *pcre_version(void);  .B char *pcre_version(void);
100  .PP  .PP
 .br  
101  .B void *(*pcre_malloc)(size_t);  .B void *(*pcre_malloc)(size_t);
102  .PP  .PP
 .br  
103  .B void (*pcre_free)(void *);  .B void (*pcre_free)(void *);
104  .PP  .PP
 .br  
105  .B void *(*pcre_stack_malloc)(size_t);  .B void *(*pcre_stack_malloc)(size_t);
106  .PP  .PP
 .br  
107  .B void (*pcre_stack_free)(void *);  .B void (*pcre_stack_free)(void *);
108  .PP  .PP
 .br  
109  .B int (*pcre_callout)(pcre_callout_block *);  .B int (*pcre_callout)(pcre_callout_block *);
110  .  .
111  .  .
# Line 754  bytes is created. Line 729  bytes is created.
729  .SH "LOCALE SUPPORT"  .SH "LOCALE SUPPORT"
730  .rs  .rs
731  .sp  .sp
732  PCRE handles caseless matching, and determines whether characters are letters  PCRE handles caseless matching, and determines whether characters are letters,
733  digits, or whatever, by reference to a set of tables, indexed by character  digits, or whatever, by reference to a set of tables, indexed by character
734  value. When running in UTF-8 mode, this applies only to characters with codes  value. When running in UTF-8 mode, this applies only to characters with codes
735  less than 128. Higher-valued codes never match escapes such as \ew or \ed, but  less than 128. Higher-valued codes never match escapes such as \ew or \ed, but
736  can be tested with \ep if PCRE is built with Unicode character property  can be tested with \ep if PCRE is built with Unicode character property
737  support. The use of locales with Unicode is discouraged.  support. The use of locales with Unicode is discouraged. If you are handling
738  .P  characters with codes greater than 128, you should either use UTF-8 and
739  An internal set of tables is created in the default C locale when PCRE is  Unicode, or use locales, but not try to mix the two.
740  built. This is used when the final argument of \fBpcre_compile()\fP is NULL,  .P
741  and is sufficient for many applications. An alternative set of tables can,  PCRE contains an internal set of tables that are used when the final argument
742  however, be supplied. These may be created in a different locale from the  of \fBpcre_compile()\fP is NULL. These are sufficient for many applications.
743  default. As more and more applications change to using Unicode, the need for  Normally, the internal tables recognize only ASCII characters. However, when
744  this locale support is expected to die away.  PCRE is built, it is possible to cause the internal tables to be rebuilt in the
745    default "C" locale of the local system, which may cause them to be different.
746    .P
747    The internal tables can always be overridden by tables supplied by the
748    application that calls PCRE. These may be created in a different locale from
749    the default. As more and more applications change to using Unicode, the need
750    for this locale support is expected to die away.
751  .P  .P
752  External tables are built by calling the \fBpcre_maketables()\fP function,  External tables are built by calling the \fBpcre_maketables()\fP function,
753  which has no arguments, in the relevant locale. The result can then be passed  which has no arguments, in the relevant locale. The result can then be passed
# Line 779  the following code could be used: Line 760  the following code could be used:
760    tables = pcre_maketables();    tables = pcre_maketables();
761    re = pcre_compile(..., tables);    re = pcre_compile(..., tables);
762  .sp  .sp
763    The locale name "fr_FR" is used on Linux and other Unix-like systems; if you
764    are using Windows, the name for the French locale is "french".
765    .P
766  When \fBpcre_maketables()\fP runs, the tables are built in memory that is  When \fBpcre_maketables()\fP runs, the tables are built in memory that is
767  obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure  obtained via \fBpcre_malloc\fP. It is the caller's responsibility to ensure
768  that the memory containing the tables remains available for as long as it is  that the memory containing the tables remains available for as long as it is
# Line 1476  Error numbers -16 to -20 are not used by Line 1460  Error numbers -16 to -20 are not used by
1460  .ti +5n  .ti +5n
1461  .B int \fIbuffersize\fP);  .B int \fIbuffersize\fP);
1462  .PP  .PP
 .br  
1463  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
1464  .ti +5n  .ti +5n
1465  .B int \fIstringcount\fP, int \fIstringnumber\fP,  .B int \fIstringcount\fP, int \fIstringnumber\fP,
1466  .ti +5n  .ti +5n
1467  .B const char **\fIstringptr\fP);  .B const char **\fIstringptr\fP);
1468  .PP  .PP
 .br  
1469  .B int pcre_get_substring_list(const char *\fIsubject\fP,  .B int pcre_get_substring_list(const char *\fIsubject\fP,
1470  .ti +5n  .ti +5n
1471  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"
# Line 1569  provided. Line 1551  provided.
1551  .ti +5n  .ti +5n
1552  .B const char *\fIname\fP);  .B const char *\fIname\fP);
1553  .PP  .PP
 .br  
1554  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,
1555  .ti +5n  .ti +5n
1556  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B const char *\fIsubject\fP, int *\fIovector\fP,
# Line 1578  provided. Line 1559  provided.
1559  .ti +5n  .ti +5n
1560  .B char *\fIbuffer\fP, int \fIbuffersize\fP);  .B char *\fIbuffer\fP, int \fIbuffersize\fP);
1561  .PP  .PP
 .br  
1562  .B int pcre_get_named_substring(const pcre *\fIcode\fP,  .B int pcre_get_named_substring(const pcre *\fIcode\fP,
1563  .ti +5n  .ti +5n
1564  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B const char *\fIsubject\fP, int *\fIovector\fP,
# Line 1614  pattern. This is needed in order to gain Line 1594  pattern. This is needed in order to gain
1594  translation table.  translation table.
1595  .P  .P
1596  These functions call \fBpcre_get_stringnumber()\fP, and if it succeeds, they  These functions call \fBpcre_get_stringnumber()\fP, and if it succeeds, they
1597  then call \fIpcre_copy_substring()\fP or \fIpcre_get_substring()\fP, as  then call \fBpcre_copy_substring()\fP or \fBpcre_get_substring()\fP, as
1598  appropriate.  appropriate. \fBNOTE:\fP If PCRE_DUPNAMES is set and there are duplicate names,
1599    the behaviour may not be what you want (see the next section).
1600  .  .
1601  .  .
1602  .SH "DUPLICATE SUBPATTERN NAMES"  .SH "DUPLICATE SUBPATTERN NAMES"
# Line 1846  extremely rare, as a vector of size 1000 Line 1827  extremely rare, as a vector of size 1000
1827  \fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3),  \fBpcrebuild\fP(3), \fBpcrecallout\fP(3), \fBpcrecpp(3)\fP(3),
1828  \fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3),  \fBpcrematching\fP(3), \fBpcrepartial\fP(3), \fBpcreposix\fP(3),
1829  \fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3).  \fBpcreprecompile\fP(3), \fBpcresample\fP(3), \fBpcrestack\fP(3).
1830  .P  .
1831  .in 0  .
1832  Last updated: 30 November 2006  .SH AUTHOR
1833  .br  .rs
1834  Copyright (c) 1997-2006 University of Cambridge.  .sp
1835    .nf
1836    Philip Hazel
1837    University Computing Service
1838    Cambridge CB2 3QH, England.
1839    .fi
1840    .
1841    .
1842    .SH REVISION
1843    .rs
1844    .sp
1845    .nf
1846    Last updated: 06 March 2007
1847    Copyright (c) 1997-2007 University of Cambridge.
1848    .fi

Legend:
Removed from v.93  
changed lines
  Added in v.142

  ViewVC Help
Powered by ViewVC 1.1.5