]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk) | |
24 | .\" Tiny change in formatting - aeb, 950812 | |
25 | .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) | |
26 | .\" | |
27 | .\" show the synopsis section nicely | |
28 | .de xx | |
29 | .in \\n(INu+\\$1 | |
30 | .ti -\\$1 | |
31 | .. | |
e6d3de00 | 32 | .TH REGEX 3 1998-05-08 GNU "Linux Programmer's Manual" |
fea681da MK |
33 | .SH NAME |
34 | regcomp, regexec, regerror, regfree \- POSIX regex functions | |
35 | .SH SYNOPSIS | |
36 | .B #include <sys/types.h> | |
37 | .br | |
38 | .B #include <regex.h> | |
39 | .sp | |
40 | .xx \w'\fBint\ regcomp(\fR'u | |
c13182ef | 41 | .BI "int\ regcomp(regex_t *" preg ", const char *" regex , |
fea681da MK |
42 | .BI "int " cflags ); |
43 | .xx \w'\fBint\ regexec(\fR'u | |
44 | .BI "int\ regexec(const regex_t *" preg ", const char *" string , | |
c13182ef | 45 | .BI "size_t " nmatch ", regmatch_t " pmatch[] , |
fea681da MK |
46 | .BI "int " eflags ); |
47 | .xx \w'\fBsize_t\ regerror(\fR'u | |
c13182ef MK |
48 | .BI "size_t\ regerror(int " errcode , |
49 | .BI "const regex_t *" preg ", char *" errbuf , | |
fea681da MK |
50 | .BI "size_t " errbuf_size ); |
51 | .xx \w'\fBvoid\ regfree(\fR' | |
52 | .BI "void\ regfree(regex_t *" preg ); | |
53 | .SH "POSIX REGEX COMPILING" | |
e511ffb6 | 54 | .BR regcomp () |
fea681da | 55 | is used to compile a regular expression into a form that is suitable |
c13182ef | 56 | for subsequent |
e511ffb6 | 57 | .BR regexec () |
fea681da MK |
58 | searches. |
59 | ||
e511ffb6 | 60 | .BR regcomp () |
c13182ef MK |
61 | is supplied with |
62 | .IR preg , | |
63 | a pointer to a pattern buffer storage area; | |
fea681da MK |
64 | .IR regex , |
65 | a pointer to the null-terminated string and | |
66 | .IR cflags , | |
67 | flags used to determine the type of compilation. | |
68 | ||
69 | All regular expression searching must be done via a compiled pattern | |
c13182ef | 70 | buffer, thus |
e511ffb6 | 71 | .BR regexec () |
c13182ef | 72 | must always be supplied with the address of a |
e511ffb6 | 73 | .BR regcomp () |
fea681da MK |
74 | initialized pattern buffer. |
75 | ||
c13182ef MK |
76 | .I cflags |
77 | may be the | |
fea681da MK |
78 | .RB bitwise- or |
79 | of one or more of the following: | |
c13182ef | 80 | .TP |
fea681da | 81 | .B REG_EXTENDED |
c13182ef | 82 | Use |
fea681da | 83 | .B POSIX |
c13182ef | 84 | Extended Regular Expression syntax when interpreting |
fea681da MK |
85 | .IR regex . |
86 | If not set, | |
87 | .B POSIX | |
88 | Basic Regular Expression syntax is used. | |
c13182ef | 89 | .TP |
fea681da | 90 | .B REG_ICASE |
c13182ef MK |
91 | Do not differentiate case. |
92 | Subsequent | |
e511ffb6 | 93 | .BR regexec () |
fea681da | 94 | searches using this pattern buffer will be case insensitive. |
c13182ef | 95 | .TP |
fea681da MK |
96 | .B REG_NOSUB |
97 | Support for substring addressing of matches is not required. | |
98 | The | |
99 | .I nmatch | |
100 | and | |
101 | .I pmatch | |
c13182ef | 102 | parameters to |
e511ffb6 | 103 | .BR regexec () |
fea681da | 104 | are ignored if the pattern buffer supplied was compiled with this flag set. |
c13182ef | 105 | .TP |
fea681da MK |
106 | .B REG_NEWLINE |
107 | Match-any-character operators don't match a newline. | |
108 | ||
c13182ef | 109 | A non-matching list |
fea681da MK |
110 | .RB ( [^...] ) |
111 | not containing a newline does not match a newline. | |
c13182ef | 112 | |
fea681da MK |
113 | Match-beginning-of-line operator |
114 | .RB ( ^ ) | |
115 | matches the empty string immediately after a newline, regardless of | |
116 | whether | |
117 | .IR eflags , | |
118 | the execution flags of | |
e511ffb6 | 119 | .BR regexec (), |
c13182ef | 120 | contains |
fea681da MK |
121 | .BR REG_NOTBOL . |
122 | ||
c13182ef | 123 | Match-end-of-line operator |
fea681da MK |
124 | .RB ( $ ) |
125 | matches the empty string immediately before a newline, regardless of | |
c13182ef MK |
126 | whether |
127 | .IR eflags | |
fea681da MK |
128 | contains |
129 | .BR REG_NOTEOL . | |
130 | .SH "POSIX REGEX MATCHING" | |
e511ffb6 | 131 | .BR regexec () |
fea681da | 132 | is used to match a null-terminated string |
c13182ef | 133 | against the precompiled pattern buffer, |
fea681da MK |
134 | .IR preg . |
135 | .I nmatch | |
136 | and | |
137 | .I pmatch | |
c13182ef | 138 | are used to provide information regarding the location of any matches. |
fea681da | 139 | .I eflags |
c13182ef | 140 | may be the |
fea681da | 141 | .RB bitwise- or |
c13182ef | 142 | of one or both of |
fea681da MK |
143 | .B REG_NOTBOL |
144 | and | |
c13182ef | 145 | .B REG_NOTEOL |
fea681da MK |
146 | which cause changes in matching behaviour described below. |
147 | .TP | |
148 | .B REG_NOTBOL | |
149 | The match-beginning-of-line operator always fails to match (but see the | |
150 | compilation flag | |
c13182ef | 151 | .B REG_NEWLINE |
fea681da | 152 | above) |
c13182ef | 153 | This flag may be used when different portions of a string are passed to |
e511ffb6 | 154 | .BR regexec () |
fea681da MK |
155 | and the beginning of the string should not be interpreted as the |
156 | beginning of the line. | |
157 | .TP | |
158 | .B REG_NOTEOL | |
159 | The match-end-of-line operator always fails to match (but see the | |
160 | compilation flag | |
161 | .B REG_NEWLINE | |
162 | above) | |
163 | .SS "BYTE OFFSETS" | |
c13182ef | 164 | Unless |
fea681da MK |
165 | .B REG_NOSUB |
166 | was set for the compilation of the pattern buffer, it is possible to | |
c13182ef | 167 | obtain substring match addressing information. |
fea681da MK |
168 | .I pmatch |
169 | must be dimensioned to have at least | |
170 | .I nmatch | |
171 | elements. | |
172 | These are filled in by | |
e511ffb6 | 173 | .BR regexec () |
c13182ef MK |
174 | with substring match addresses. |
175 | Any unused structure elements will contain the value \-1. | |
fea681da | 176 | |
c13182ef MK |
177 | The |
178 | .B regmatch_t | |
fea681da MK |
179 | structure which is the type of |
180 | .I pmatch | |
181 | is defined in | |
182 | .IR regex.h . | |
183 | ||
184 | .RS | |
185 | .B typedef struct | |
186 | .br | |
187 | .B { | |
188 | .br | |
189 | .BI " regoff_t " rm_so ; | |
190 | .br | |
191 | .BI " regoff_t " rm_eo ; | |
192 | .br | |
193 | .B } | |
194 | .B regmatch_t; | |
195 | .RE | |
196 | ||
c13182ef | 197 | Each |
fea681da | 198 | .I rm_so |
8729177b | 199 | element that is not \-1 indicates the start offset of the next largest |
c13182ef MK |
200 | substring match within the string. |
201 | The relative | |
202 | .I rm_eo | |
fea681da MK |
203 | element indicates the end offset of the match. |
204 | .SH "POSIX ERROR REPORTING" | |
e511ffb6 | 205 | .BR regerror () |
c13182ef | 206 | is used to turn the error codes that can be returned by both |
e511ffb6 | 207 | .BR regcomp () |
fea681da | 208 | and |
e511ffb6 | 209 | .BR regexec () |
fea681da MK |
210 | into error message strings. |
211 | ||
e511ffb6 | 212 | .BR regerror () |
fea681da MK |
213 | is passed the error code, |
214 | .IR errcode , | |
215 | the pattern buffer, | |
216 | .IR preg , | |
217 | a pointer to a character string buffer, | |
218 | .IR errbuf , | |
219 | and the size of the string buffer, | |
220 | .IR errbuf_size . | |
221 | It returns the size of the | |
222 | .I errbuf | |
c13182ef MK |
223 | required to contain the null-terminated error message string. |
224 | If both | |
fea681da MK |
225 | .I errbuf |
226 | and | |
227 | .I errbuf_size | |
c13182ef | 228 | are non-zero, |
fea681da | 229 | .I errbuf |
c13182ef | 230 | is filled in with the first |
c65433e6 | 231 | .I "errbuf_size \- 1" |
fea681da MK |
232 | characters of the error message and a terminating null. |
233 | .SH "POSIX PATTERN BUFFER FREEING" | |
c13182ef | 234 | Supplying |
e511ffb6 | 235 | .BR regfree () |
fea681da MK |
236 | with a precompiled pattern buffer, |
237 | .I preg | |
238 | will free the memory allocated to the pattern buffer by the compiling | |
239 | process, | |
e511ffb6 | 240 | .BR regcomp (). |
fea681da | 241 | .SH "RETURN VALUE" |
e511ffb6 | 242 | .BR regcomp () |
fea681da MK |
243 | returns zero for a successful compilation or an error code for failure. |
244 | ||
e511ffb6 | 245 | .BR regexec () |
c13182ef | 246 | returns zero for a successful match or |
fea681da MK |
247 | .B REG_NOMATCH |
248 | for failure. | |
249 | .SH ERRORS | |
c13182ef | 250 | The following errors can be returned by |
e511ffb6 | 251 | .BR regcomp (): |
fea681da MK |
252 | .TP |
253 | .B REG_BADBR | |
254 | Invalid use of back reference operator. | |
255 | .TP | |
256 | .B REG_BADPAT | |
257 | Invalid use of pattern operators such as group or list. | |
258 | .TP | |
259 | .B REG_BADRPT | |
c13182ef | 260 | Invalid use of repetition operators such as using |
fea681da MK |
261 | .RB ` * ' |
262 | as the first character. | |
263 | .TP | |
264 | .B REG_EBRACE | |
265 | Un-matched brace interval operators. | |
266 | .TP | |
267 | .B REG_EBRACK | |
268 | Un-matched bracket list operators. | |
269 | .TP | |
270 | .B REG_ECOLLATE | |
271 | Invalid collating element. | |
272 | .TP | |
273 | .B REG_ECTYPE | |
274 | Unknown character class name. | |
275 | .TP | |
276 | .B REG_EEND | |
c13182ef MK |
277 | Non specific error. |
278 | This is not defined by POSIX.2. | |
fea681da MK |
279 | .TP |
280 | .B REG_EESCAPE | |
281 | Trailing backslash. | |
282 | .TP | |
283 | .B REG_EPAREN | |
284 | Un-matched parenthesis group operators. | |
285 | .TP | |
286 | .B REG_ERANGE | |
287 | Invalid use of the range operator, eg. the ending point of the range | |
288 | occurs prior to the starting point. | |
289 | .TP | |
290 | .B REG_ESIZE | |
291 | Compiled regular expression requires a pattern buffer larger than 64Kb. | |
292 | This is not defined by POSIX.2. | |
293 | .TP | |
294 | .B REG_ESPACE | |
295 | The regex routines ran out of memory. | |
296 | .TP | |
297 | .B REG_ESUBREG | |
298 | Invalid back reference to a subexpression. | |
299 | .SH "CONFORMING TO" | |
68e1685c | 300 | POSIX.1-2001. |
fea681da MK |
301 | .SH "SEE ALSO" |
302 | .BR regex (7), | |
303 | GNU regex manual | |
c13182ef | 304 |