]>
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 | .. | |
05eabe65 | 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 ); | |
8af1ba10 MK |
53 | .SH DESCRIPTION |
54 | .SS "POSIX Regex Compiling" | |
e511ffb6 | 55 | .BR regcomp () |
fea681da | 56 | is used to compile a regular expression into a form that is suitable |
c13182ef | 57 | for subsequent |
e511ffb6 | 58 | .BR regexec () |
fea681da MK |
59 | searches. |
60 | ||
e511ffb6 | 61 | .BR regcomp () |
c13182ef MK |
62 | is supplied with |
63 | .IR preg , | |
64 | a pointer to a pattern buffer storage area; | |
fea681da MK |
65 | .IR regex , |
66 | a pointer to the null-terminated string and | |
67 | .IR cflags , | |
68 | flags used to determine the type of compilation. | |
69 | ||
70 | All regular expression searching must be done via a compiled pattern | |
c13182ef | 71 | buffer, thus |
e511ffb6 | 72 | .BR regexec () |
c13182ef | 73 | must always be supplied with the address of a |
e511ffb6 | 74 | .BR regcomp () |
fea681da MK |
75 | initialized pattern buffer. |
76 | ||
c13182ef MK |
77 | .I cflags |
78 | may be the | |
fea681da MK |
79 | .RB bitwise- or |
80 | of one or more of the following: | |
c13182ef | 81 | .TP |
fea681da | 82 | .B REG_EXTENDED |
c13182ef | 83 | Use |
fea681da | 84 | .B POSIX |
c13182ef | 85 | Extended Regular Expression syntax when interpreting |
fea681da MK |
86 | .IR regex . |
87 | If not set, | |
88 | .B POSIX | |
89 | Basic Regular Expression syntax is used. | |
c13182ef | 90 | .TP |
fea681da | 91 | .B REG_ICASE |
c13182ef MK |
92 | Do not differentiate case. |
93 | Subsequent | |
e511ffb6 | 94 | .BR regexec () |
fea681da | 95 | searches using this pattern buffer will be case insensitive. |
c13182ef | 96 | .TP |
fea681da MK |
97 | .B REG_NOSUB |
98 | Support for substring addressing of matches is not required. | |
99 | The | |
100 | .I nmatch | |
101 | and | |
102 | .I pmatch | |
c13182ef | 103 | parameters to |
e511ffb6 | 104 | .BR regexec () |
fea681da | 105 | are ignored if the pattern buffer supplied was compiled with this flag set. |
c13182ef | 106 | .TP |
fea681da MK |
107 | .B REG_NEWLINE |
108 | Match-any-character operators don't match a newline. | |
109 | ||
c13182ef | 110 | A non-matching list |
fea681da MK |
111 | .RB ( [^...] ) |
112 | not containing a newline does not match a newline. | |
c13182ef | 113 | |
fea681da MK |
114 | Match-beginning-of-line operator |
115 | .RB ( ^ ) | |
116 | matches the empty string immediately after a newline, regardless of | |
117 | whether | |
118 | .IR eflags , | |
119 | the execution flags of | |
e511ffb6 | 120 | .BR regexec (), |
c13182ef | 121 | contains |
fea681da MK |
122 | .BR REG_NOTBOL . |
123 | ||
c13182ef | 124 | Match-end-of-line operator |
fea681da MK |
125 | .RB ( $ ) |
126 | matches the empty string immediately before a newline, regardless of | |
c13182ef MK |
127 | whether |
128 | .IR eflags | |
fea681da MK |
129 | contains |
130 | .BR REG_NOTEOL . | |
8af1ba10 | 131 | .SS "POSIX Regex Matching" |
e511ffb6 | 132 | .BR regexec () |
fea681da | 133 | is used to match a null-terminated string |
c13182ef | 134 | against the precompiled pattern buffer, |
fea681da MK |
135 | .IR preg . |
136 | .I nmatch | |
137 | and | |
138 | .I pmatch | |
c13182ef | 139 | are used to provide information regarding the location of any matches. |
fea681da | 140 | .I eflags |
c13182ef | 141 | may be the |
fea681da | 142 | .RB bitwise- or |
c13182ef | 143 | of one or both of |
fea681da MK |
144 | .B REG_NOTBOL |
145 | and | |
c13182ef | 146 | .B REG_NOTEOL |
d9bfdb9c | 147 | which cause changes in matching behavior described below. |
fea681da MK |
148 | .TP |
149 | .B REG_NOTBOL | |
150 | The match-beginning-of-line operator always fails to match (but see the | |
151 | compilation flag | |
c13182ef | 152 | .B REG_NEWLINE |
fea681da | 153 | above) |
c13182ef | 154 | This flag may be used when different portions of a string are passed to |
e511ffb6 | 155 | .BR regexec () |
fea681da MK |
156 | and the beginning of the string should not be interpreted as the |
157 | beginning of the line. | |
158 | .TP | |
159 | .B REG_NOTEOL | |
160 | The match-end-of-line operator always fails to match (but see the | |
161 | compilation flag | |
162 | .B REG_NEWLINE | |
163 | above) | |
164 | .SS "BYTE OFFSETS" | |
c13182ef | 165 | Unless |
fea681da MK |
166 | .B REG_NOSUB |
167 | was set for the compilation of the pattern buffer, it is possible to | |
c13182ef | 168 | obtain substring match addressing information. |
fea681da MK |
169 | .I pmatch |
170 | must be dimensioned to have at least | |
171 | .I nmatch | |
172 | elements. | |
173 | These are filled in by | |
e511ffb6 | 174 | .BR regexec () |
c13182ef MK |
175 | with substring match addresses. |
176 | Any unused structure elements will contain the value \-1. | |
fea681da | 177 | |
c13182ef MK |
178 | The |
179 | .B regmatch_t | |
fea681da MK |
180 | structure which is the type of |
181 | .I pmatch | |
182 | is defined in | |
183 | .IR regex.h . | |
184 | ||
185 | .RS | |
186 | .B typedef struct | |
187 | .br | |
188 | .B { | |
189 | .br | |
190 | .BI " regoff_t " rm_so ; | |
191 | .br | |
192 | .BI " regoff_t " rm_eo ; | |
193 | .br | |
194 | .B } | |
195 | .B regmatch_t; | |
196 | .RE | |
197 | ||
c13182ef | 198 | Each |
fea681da | 199 | .I rm_so |
8729177b | 200 | element that is not \-1 indicates the start offset of the next largest |
c13182ef MK |
201 | substring match within the string. |
202 | The relative | |
203 | .I rm_eo | |
fea681da | 204 | element indicates the end offset of the match. |
8af1ba10 | 205 | .SS "Posix Error Reporting" |
e511ffb6 | 206 | .BR regerror () |
c13182ef | 207 | is used to turn the error codes that can be returned by both |
e511ffb6 | 208 | .BR regcomp () |
fea681da | 209 | and |
e511ffb6 | 210 | .BR regexec () |
fea681da MK |
211 | into error message strings. |
212 | ||
e511ffb6 | 213 | .BR regerror () |
fea681da MK |
214 | is passed the error code, |
215 | .IR errcode , | |
216 | the pattern buffer, | |
217 | .IR preg , | |
218 | a pointer to a character string buffer, | |
219 | .IR errbuf , | |
220 | and the size of the string buffer, | |
221 | .IR errbuf_size . | |
222 | It returns the size of the | |
223 | .I errbuf | |
c13182ef MK |
224 | required to contain the null-terminated error message string. |
225 | If both | |
fea681da MK |
226 | .I errbuf |
227 | and | |
228 | .I errbuf_size | |
c13182ef | 229 | are non-zero, |
fea681da | 230 | .I errbuf |
c13182ef | 231 | is filled in with the first |
c65433e6 | 232 | .I "errbuf_size \- 1" |
fea681da | 233 | characters of the error message and a terminating null. |
8af1ba10 | 234 | .SS "POSIX Pattern Buffer Freeing" |
c13182ef | 235 | Supplying |
e511ffb6 | 236 | .BR regfree () |
fea681da MK |
237 | with a precompiled pattern buffer, |
238 | .I preg | |
239 | will free the memory allocated to the pattern buffer by the compiling | |
240 | process, | |
e511ffb6 | 241 | .BR regcomp (). |
fea681da | 242 | .SH "RETURN VALUE" |
e511ffb6 | 243 | .BR regcomp () |
fea681da MK |
244 | returns zero for a successful compilation or an error code for failure. |
245 | ||
e511ffb6 | 246 | .BR regexec () |
c13182ef | 247 | returns zero for a successful match or |
fea681da MK |
248 | .B REG_NOMATCH |
249 | for failure. | |
250 | .SH ERRORS | |
c13182ef | 251 | The following errors can be returned by |
e511ffb6 | 252 | .BR regcomp (): |
fea681da MK |
253 | .TP |
254 | .B REG_BADBR | |
255 | Invalid use of back reference operator. | |
256 | .TP | |
257 | .B REG_BADPAT | |
258 | Invalid use of pattern operators such as group or list. | |
259 | .TP | |
260 | .B REG_BADRPT | |
c13182ef | 261 | Invalid use of repetition operators such as using |
fea681da MK |
262 | .RB ` * ' |
263 | as the first character. | |
264 | .TP | |
265 | .B REG_EBRACE | |
266 | Un-matched brace interval operators. | |
267 | .TP | |
268 | .B REG_EBRACK | |
269 | Un-matched bracket list operators. | |
270 | .TP | |
271 | .B REG_ECOLLATE | |
272 | Invalid collating element. | |
273 | .TP | |
274 | .B REG_ECTYPE | |
275 | Unknown character class name. | |
276 | .TP | |
277 | .B REG_EEND | |
c13182ef MK |
278 | Non specific error. |
279 | This is not defined by POSIX.2. | |
fea681da MK |
280 | .TP |
281 | .B REG_EESCAPE | |
282 | Trailing backslash. | |
283 | .TP | |
284 | .B REG_EPAREN | |
285 | Un-matched parenthesis group operators. | |
286 | .TP | |
287 | .B REG_ERANGE | |
288 | Invalid use of the range operator, eg. the ending point of the range | |
289 | occurs prior to the starting point. | |
290 | .TP | |
291 | .B REG_ESIZE | |
292 | Compiled regular expression requires a pattern buffer larger than 64Kb. | |
293 | This is not defined by POSIX.2. | |
294 | .TP | |
295 | .B REG_ESPACE | |
296 | The regex routines ran out of memory. | |
297 | .TP | |
298 | .B REG_ESUBREG | |
299 | Invalid back reference to a subexpression. | |
300 | .SH "CONFORMING TO" | |
68e1685c | 301 | POSIX.1-2001. |
fea681da | 302 | .SH "SEE ALSO" |
79e7547f | 303 | .BR grep (1), |
fea681da MK |
304 | .BR regex (7), |
305 | GNU regex manual | |
c13182ef | 306 |