/[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 1338 by ph10, Tue May 28 09:13:59 2013 UTC revision 1339 by ph10, Fri Jun 14 09:09:28 2013 UTC
# Line 1  Line 1 
1  .TH PCREAPI 3 "12 May 2013" "PCRE 8.33"  .TH PCREAPI 3 "12 June 2013" "PCRE 8.33"
2  .SH NAME  .SH NAME
3  PCRE - Perl-compatible regular expressions  PCRE - Perl-compatible regular expressions
4  .sp  .sp
# Line 8  PCRE - Perl-compatible regular expressio Line 8  PCRE - Perl-compatible regular expressio
8  .SH "PCRE NATIVE API BASIC FUNCTIONS"  .SH "PCRE NATIVE API BASIC FUNCTIONS"
9  .rs  .rs
10  .sp  .sp
11  .SM  .nf
12  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,
13  .ti +5n  .B "     const char **\fIerrptr\fP, int *\fIerroffset\fP,"
14  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,  .B "     const unsigned char *\fItableptr\fP);"
15  .ti +5n  .sp
 .B const unsigned char *\fItableptr\fP);  
 .PP  
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  .B "     int *\fIerrorcodeptr\fP,"
18  .B int *\fIerrorcodeptr\fP,  .B "     const char **\fIerrptr\fP, int *\fIerroffset\fP,"
19  .ti +5n  .B "     const unsigned char *\fItableptr\fP);"
20  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,  .sp
 .ti +5n  
 .B const unsigned char *\fItableptr\fP);  
 .PP  
21  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
22  .ti +5n  .B "     const char **\fIerrptr\fP);"
23  .B const char **\fIerrptr\fP);  .sp
 .PP  
24  .B void pcre_free_study(pcre_extra *\fIextra\fP);  .B void pcre_free_study(pcre_extra *\fIextra\fP);
25  .PP  .sp
26  .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,"
27  .ti +5n  .B "     const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
28  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);"
29  .ti +5n  .sp
 .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);  
 .PP  
30  .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,"
31  .ti +5n  .B "     const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
32  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
33  .ti +5n  .B "     int *\fIworkspace\fP, int \fIwscount\fP);"
34  .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,  .fi
 .ti +5n  
 .B int *\fIworkspace\fP, int \fIwscount\fP);  
35  .  .
36  .  .
37  .SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS"  .SH "PCRE NATIVE API STRING EXTRACTION FUNCTIONS"
38  .rs  .rs
39  .sp  .sp
40    .nf
41  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,
42  .ti +5n  .B "     const char *\fIsubject\fP, int *\fIovector\fP,"
43  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B "     int \fIstringcount\fP, const char *\fIstringname\fP,"
44  .ti +5n  .B "     char *\fIbuffer\fP, int \fIbuffersize\fP);"
45  .B int \fIstringcount\fP, const char *\fIstringname\fP,  .sp
 .ti +5n  
 .B char *\fIbuffer\fP, int \fIbuffersize\fP);  
 .PP  
46  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,
47  .ti +5n  .B "     int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,"
48  .B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,  .B "     int \fIbuffersize\fP);"
49  .ti +5n  .sp
 .B int \fIbuffersize\fP);  
 .PP  
50  .B int pcre_get_named_substring(const pcre *\fIcode\fP,  .B int pcre_get_named_substring(const pcre *\fIcode\fP,
51  .ti +5n  .B "     const char *\fIsubject\fP, int *\fIovector\fP,"
52  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B "     int \fIstringcount\fP, const char *\fIstringname\fP,"
53  .ti +5n  .B "     const char **\fIstringptr\fP);"
54  .B int \fIstringcount\fP, const char *\fIstringname\fP,  .sp
 .ti +5n  
 .B const char **\fIstringptr\fP);  
 .PP  
55  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,
56  .ti +5n  .B "     const char *\fIname\fP);"
57  .B const char *\fIname\fP);  .sp
 .PP  
58  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
59  .ti +5n  .B "     const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);"
60  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);  .sp
 .PP  
61  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
62  .ti +5n  .B "     int \fIstringcount\fP, int \fIstringnumber\fP,"
63  .B int \fIstringcount\fP, int \fIstringnumber\fP,  .B "     const char **\fIstringptr\fP);"
64  .ti +5n  .sp
 .B const char **\fIstringptr\fP);  
 .PP  
65  .B int pcre_get_substring_list(const char *\fIsubject\fP,  .B int pcre_get_substring_list(const char *\fIsubject\fP,
66  .ti +5n  .B "     int *\fIovector\fP, int \fIstringcount\fP, const char ***\fIlistptr\fP);"
67  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"  .sp
 .PP  
68  .B void pcre_free_substring(const char *\fIstringptr\fP);  .B void pcre_free_substring(const char *\fIstringptr\fP);
69  .PP  .sp
70  .B void pcre_free_substring_list(const char **\fIstringptr\fP);  .B void pcre_free_substring_list(const char **\fIstringptr\fP);
71    .fi
72  .  .
73  .  .
74  .SH "PCRE NATIVE API AUXILIARY FUNCTIONS"  .SH "PCRE NATIVE API AUXILIARY FUNCTIONS"
75  .rs  .rs
76  .sp  .sp
77    .nf
78  .B int pcre_jit_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"  .B int pcre_jit_exec(const pcre *\fIcode\fP, "const pcre_extra *\fIextra\fP,"
79  .ti +5n  .B "     const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
80  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
81  .ti +5n  .B "     pcre_jit_stack *\fIjstack\fP);"
82  .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,  .sp
 .ti +5n  
 .B pcre_jit_stack *\fIjstack\fP);  
 .PP  
83  .B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP);  .B pcre_jit_stack *pcre_jit_stack_alloc(int \fIstartsize\fP, int \fImaxsize\fP);
84  .PP  .sp
85  .B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP);  .B void pcre_jit_stack_free(pcre_jit_stack *\fIstack\fP);
86  .PP  .sp
87  .B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP,  .B void pcre_assign_jit_stack(pcre_extra *\fIextra\fP,
88  .ti +5n  .B "     pcre_jit_callback \fIcallback\fP, void *\fIdata\fP);"
89  .B pcre_jit_callback \fIcallback\fP, void *\fIdata\fP);  .sp
 .PP  
90  .B const unsigned char *pcre_maketables(void);  .B const unsigned char *pcre_maketables(void);
91  .PP  .sp
92  .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,"
93  .ti +5n  .B "     int \fIwhat\fP, void *\fIwhere\fP);"
94  .B int \fIwhat\fP, void *\fIwhere\fP);  .sp
 .PP  
95  .B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);  .B int pcre_refcount(pcre *\fIcode\fP, int \fIadjust\fP);
96  .PP  .sp
97  .B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);  .B int pcre_config(int \fIwhat\fP, void *\fIwhere\fP);
98  .PP  .sp
99  .B const char *pcre_version(void);  .B const char *pcre_version(void);
100  .PP  .sp
101  .B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP,  .B int pcre_pattern_to_host_byte_order(pcre *\fIcode\fP,
102  .ti +5n  .B "     pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP);"
103  .B pcre_extra *\fIextra\fP, const unsigned char *\fItables\fP);  .fi
104  .  .
105  .  .
106  .SH "PCRE NATIVE API INDIRECTED FUNCTIONS"  .SH "PCRE NATIVE API INDIRECTED FUNCTIONS"
107  .rs  .rs
108  .sp  .sp
109    .nf
110  .B void *(*pcre_malloc)(size_t);  .B void *(*pcre_malloc)(size_t);
111  .PP  .sp
112  .B void (*pcre_free)(void *);  .B void (*pcre_free)(void *);
113  .PP  .sp
114  .B void *(*pcre_stack_malloc)(size_t);  .B void *(*pcre_stack_malloc)(size_t);
115  .PP  .sp
116  .B void (*pcre_stack_free)(void *);  .B void (*pcre_stack_free)(void *);
117  .PP  .sp
118  .B int (*pcre_callout)(pcre_callout_block *);  .B int (*pcre_callout)(pcre_callout_block *);
119    .fi
120  .  .
121  .  .
122  .SH "PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES"  .SH "PCRE 8-BIT, 16-BIT, AND 32-BIT LIBRARIES"
# Line 509  avoiding the use of the stack. Line 486  avoiding the use of the stack.
486  .SH "COMPILING A PATTERN"  .SH "COMPILING A PATTERN"
487  .rs  .rs
488  .sp  .sp
489    .nf
490  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,  .B pcre *pcre_compile(const char *\fIpattern\fP, int \fIoptions\fP,
491  .ti +5n  .B "     const char **\fIerrptr\fP, int *\fIerroffset\fP,"
492  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,  .B "     const unsigned char *\fItableptr\fP);"
 .ti +5n  
 .B const unsigned char *\fItableptr\fP);  
493  .sp  .sp
494  .B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,  .B pcre *pcre_compile2(const char *\fIpattern\fP, int \fIoptions\fP,
495  .ti +5n  .B "     int *\fIerrorcodeptr\fP,"
496  .B int *\fIerrorcodeptr\fP,  .B "     const char **\fIerrptr\fP, int *\fIerroffset\fP,"
497  .ti +5n  .B "     const unsigned char *\fItableptr\fP);"
498  .B const char **\fIerrptr\fP, int *\fIerroffset\fP,  .fi
 .ti +5n  
 .B const unsigned char *\fItableptr\fP);  
499  .P  .P
500  Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be  Either of the functions \fBpcre_compile()\fP or \fBpcre_compile2()\fP can be
501  called to compile a pattern into an internal form. The only difference between  called to compile a pattern into an internal form. The only difference between
# Line 993  be used if the limits were changed when Line 967  be used if the limits were changed when
967  .SH "STUDYING A PATTERN"  .SH "STUDYING A PATTERN"
968  .rs  .rs
969  .sp  .sp
970  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP  .nf
971  .ti +5n  .B pcre_extra *pcre_study(const pcre *\fIcode\fP, int \fIoptions\fP,
972  .B const char **\fIerrptr\fP);  .B "     const char **\fIerrptr\fP);"
973    .fi
974  .PP  .PP
975  If a compiled pattern is going to be used several times, it is worth spending  If a compiled pattern is going to be used several times, it is worth spending
976  more time analyzing it in order to speed up the time taken for matching. The  more time analyzing it in order to speed up the time taken for matching. The
# Line 1174  below in the section on matching a patte Line 1149  below in the section on matching a patte
1149  .SH "INFORMATION ABOUT A PATTERN"  .SH "INFORMATION ABOUT A PATTERN"
1150  .rs  .rs
1151  .sp  .sp
1152    .nf
1153  .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,"
1154  .ti +5n  .B "     int \fIwhat\fP, void *\fIwhere\fP);"
1155  .B int \fIwhat\fP, void *\fIwhere\fP);  .fi
1156  .PP  .PP
1157  The \fBpcre_fullinfo()\fP function returns information about a compiled  The \fBpcre_fullinfo()\fP function returns information about a compiled
1158  pattern. It replaces the \fBpcre_info()\fP function, which was removed from the  pattern. It replaces the \fBpcre_info()\fP function, which was removed from the
# Line 1567  is different. (This seems a highly unlik Line 1543  is different. (This seems a highly unlik
1543  .SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"  .SH "MATCHING A PATTERN: THE TRADITIONAL FUNCTION"
1544  .rs  .rs
1545  .sp  .sp
1546    .nf
1547  .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,"
1548  .ti +5n  .B "     const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,
1549  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);"
1550  .ti +5n  .fi
 .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP);  
1551  .P  .P
1552  The function \fBpcre_exec()\fP is called to match a subject string against a  The function \fBpcre_exec()\fP is called to match a subject string against a
1553  compiled pattern, which is passed in the \fIcode\fP argument. If the  compiled pattern, which is passed in the \fIcode\fP argument. If the
# Line 2423  no longer in use and is never returned. Line 2399  no longer in use and is never returned.
2399  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NUMBER"
2400  .rs  .rs
2401  .sp  .sp
2402    .nf
2403  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_copy_substring(const char *\fIsubject\fP, int *\fIovector\fP,
2404  .ti +5n  .B "     int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,"
2405  .B int \fIstringcount\fP, int \fIstringnumber\fP, char *\fIbuffer\fP,  .B "     int \fIbuffersize\fP);"
2406  .ti +5n  .sp
 .B int \fIbuffersize\fP);  
 .PP  
2407  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,  .B int pcre_get_substring(const char *\fIsubject\fP, int *\fIovector\fP,
2408  .ti +5n  .B "     int \fIstringcount\fP, int \fIstringnumber\fP,"
2409  .B int \fIstringcount\fP, int \fIstringnumber\fP,  .B "     const char **\fIstringptr\fP);"
2410  .ti +5n  .sp
 .B const char **\fIstringptr\fP);  
 .PP  
2411  .B int pcre_get_substring_list(const char *\fIsubject\fP,  .B int pcre_get_substring_list(const char *\fIsubject\fP,
2412  .ti +5n  .B "     int *\fIovector\fP, int \fIstringcount\fP, const char ***\fIlistptr\fP);"
2413  .B int *\fIovector\fP, int \fIstringcount\fP, "const char ***\fIlistptr\fP);"  .fi
2414  .PP  .PP
2415  Captured substrings can be accessed directly by using the offsets returned by  Captured substrings can be accessed directly by using the offsets returned by
2416  \fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions  \fBpcre_exec()\fP in \fIovector\fP. For convenience, the functions
# Line 2516  provided. Line 2489  provided.
2489  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"  .SH "EXTRACTING CAPTURED SUBSTRINGS BY NAME"
2490  .rs  .rs
2491  .sp  .sp
2492    .nf
2493  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,  .B int pcre_get_stringnumber(const pcre *\fIcode\fP,
2494  .ti +5n  .B "     const char *\fIname\fP);"
2495  .B const char *\fIname\fP);  .sp
 .PP  
2496  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,  .B int pcre_copy_named_substring(const pcre *\fIcode\fP,
2497  .ti +5n  .B "     const char *\fIsubject\fP, int *\fIovector\fP,"
2498  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B "     int \fIstringcount\fP, const char *\fIstringname\fP,"
2499  .ti +5n  .B "     char *\fIbuffer\fP, int \fIbuffersize\fP);"
2500  .B int \fIstringcount\fP, const char *\fIstringname\fP,  .sp
 .ti +5n  
 .B char *\fIbuffer\fP, int \fIbuffersize\fP);  
 .PP  
2501  .B int pcre_get_named_substring(const pcre *\fIcode\fP,  .B int pcre_get_named_substring(const pcre *\fIcode\fP,
2502  .ti +5n  .B "     const char *\fIsubject\fP, int *\fIovector\fP,"
2503  .B const char *\fIsubject\fP, int *\fIovector\fP,  .B "     int \fIstringcount\fP, const char *\fIstringname\fP,"
2504  .ti +5n  .B "     const char **\fIstringptr\fP);"
2505  .B int \fIstringcount\fP, const char *\fIstringname\fP,  .fi
 .ti +5n  
 .B const char **\fIstringptr\fP);  
2506  .PP  .PP
2507  To extract a substring by name, you first have to find associated number.  To extract a substring by name, you first have to find associated number.
2508  For example, for this pattern  For example, for this pattern
# Line 2586  same number causes an error at compile t Line 2554  same number causes an error at compile t
2554  .SH "DUPLICATE SUBPATTERN NAMES"  .SH "DUPLICATE SUBPATTERN NAMES"
2555  .rs  .rs
2556  .sp  .sp
2557    .nf
2558  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,  .B int pcre_get_stringtable_entries(const pcre *\fIcode\fP,
2559  .ti +5n  .B "     const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);"
2560  .B const char *\fIname\fP, char **\fIfirst\fP, char **\fIlast\fP);  .fi
2561  .PP  .PP
2562  When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns  When a pattern is compiled with the PCRE_DUPNAMES option, names for subpatterns
2563  are not required to be unique. (Duplicate names are always allowed for  are not required to be unique. (Duplicate names are always allowed for
# Line 2677  the value returned is the size of each b Line 2646  the value returned is the size of each b
2646  .SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"  .SH "MATCHING A PATTERN: THE ALTERNATIVE FUNCTION"
2647  .rs  .rs
2648  .sp  .sp
2649    .nf
2650  .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,"
2651  .ti +5n  .B "     const char *\fIsubject\fP, int \fIlength\fP, int \fIstartoffset\fP,"
2652  .B "const char *\fIsubject\fP," int \fIlength\fP, int \fIstartoffset\fP,  .B "     int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,"
2653  .ti +5n  .B "     int *\fIworkspace\fP, int \fIwscount\fP);"
2654  .B int \fIoptions\fP, int *\fIovector\fP, int \fIovecsize\fP,  .fi
 .ti +5n  
 .B int *\fIworkspace\fP, int \fIwscount\fP);  
2655  .P  .P
2656  The function \fBpcre_dfa_exec()\fP is called to match a subject string against  The function \fBpcre_dfa_exec()\fP is called to match a subject string against
2657  a compiled pattern, using a matching algorithm that scans the subject string  a compiled pattern, using a matching algorithm that scans the subject string
# Line 2886  Cambridge CB2 3QH, England. Line 2854  Cambridge CB2 3QH, England.
2854  .rs  .rs
2855  .sp  .sp
2856  .nf  .nf
2857  Last updated: 12 May 2013  Last updated: 12 June 2013
2858  Copyright (c) 1997-2013 University of Cambridge.  Copyright (c) 1997-2013 University of Cambridge.
2859  .fi  .fi

Legend:
Removed from v.1338  
changed lines
  Added in v.1339

  ViewVC Help
Powered by ViewVC 1.1.5