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