Debian Codegraph @

upstream/mageia-cauldron/man3/regex.3

raw
1 '\" t
2 .\" Copyright 1995, Graeme W. Wilford <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH regex 3 2026-02-10 "Linux man-pages 6.17"
8 .SH NAME
9 regcomp, regexec, regerror, regfree \- POSIX regex functions
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <regex.h>
16 .P
17 .BI "int regcomp(regex_t *restrict " preg ", const char *restrict " regex ,
18 .BI " int " cflags );
19 .BI "int regexec(const regex_t *restrict " preg ,
20 .BI " const char *restrict " string ,
21 .BI " size_t " n ", regmatch_t " pmatch "[_Nullable restrict " n ],
22 .BI " int " eflags );
23 .P
24 .BR "size_t regerror(" "size_t errbuf_size;"
25 .BI " int " errcode ", const regex_t *_Nullable restrict " preg ,
26 .BI " char " errbuf "[_Nullable restrict " errbuf_size ],
27 .BI " size_t " errbuf_size );
28 .BI "void regfree(regex_t *" preg );
29 .P
30 .B typedef struct {
31 .B " size_t re_nsub;"
32 .B } regex_t;
33 .P
34 .B typedef struct {
35 .B " regoff_t rm_so;"
36 .B " regoff_t rm_eo;"
37 .B } regmatch_t;
38 .P
39 .BR typedef " /* ... */ " regoff_t;
40 .fi
41 .SH DESCRIPTION
42 .SS Compilation
43 .BR regcomp ()
44 is used to compile a regular expression into a form that is suitable
45 for subsequent
46 .BR regexec ()
47 searches.
48 .P
49 On success, the pattern buffer at
50 .I *preg
51 is initialized.
52 .I regex
53 is a null-terminated string.
54 The locale must be the same when running
55 .BR regexec ().
56 .P
57 After
58 .BR regcomp ()
59 succeeds,
60 .I preg->re_nsub
61 holds the number of subexpressions in
62 .IR regex .
63 Thus, a value of
64 .I preg->re_nsub
65 + 1
66 passed as
67 .I n
68 to
69 .BR regexec ()
70 is sufficient to capture all matches.
71 .P
72 .I cflags
73 is the
74 bitwise OR
75 of zero or more of the following:
76 .TP
77 .B REG_EXTENDED
78 Use
79 POSIX
80 Extended Regular Expression syntax when interpreting
81 .IR regex .
82 If not set,
83 POSIX
84 Basic Regular Expression syntax is used.
85 .TP
86 .B REG_ICASE
87 Do not differentiate case.
88 Subsequent
89 .BR regexec ()
90 searches using this pattern buffer will be case insensitive.
91 .TP
92 .B REG_NOSUB
93 Report only overall success.
94 .BR regexec ()
95 will use only
96 .I pmatch
97 for
98 .BR REG_STARTEND ,
99 ignoring
100 .IR n .
101 .TP
102 .B REG_NEWLINE
103 Match-any-character operators don't match a newline.
104 .IP
105 A nonmatching list
106 .RB ( [\[ha]...\&] )
107 not containing a newline does not match a newline.
108 .IP
109 Match-beginning-of-line operator
110 .RB ( \[ha] )
111 matches the empty string immediately after a newline, regardless of
112 whether
113 .IR eflags ,
114 the execution flags of
115 .BR regexec (),
116 contains
117 .BR REG_NOTBOL .
118 .IP
119 Match-end-of-line operator
120 .RB ( $ )
121 matches the empty string immediately before a newline, regardless of
122 whether
123 .I eflags
124 contains
125 .BR REG_NOTEOL .
126 .SS Matching
127 .BR regexec ()
128 is used to match a null-terminated string
129 against the compiled pattern buffer in
130 .IR *preg ,
131 which must have been initialised with
132 .BR regcomp ().
133 .I eflags
134 is the
135 bitwise OR
136 of zero or more of the following flags:
137 .TP
138 .B REG_NOTBOL
139 The match-beginning-of-line operator always fails to match (but see the
140 compilation flag
141 .B REG_NEWLINE
142 above).
143 This flag may be used when different portions of a string are passed to
144 .BR regexec ()
145 and the beginning of the string should not be interpreted as the
146 beginning of the line.
147 .TP
148 .B REG_NOTEOL
149 The match-end-of-line operator always fails to match (but see the
150 compilation flag
151 .B REG_NEWLINE
152 above).
153 .TP
154 .B REG_STARTEND
155 Match
156 .RI [ "string + pmatch[0].rm_so" , " string + pmatch[0].rm_eo" )
157 instead of
158 .RI [ string , " string + strlen(string)" ).
159 This allows matching embedded NUL bytes
160 and avoids a
161 .BR strlen (3)
162 on known-length strings.
163 If any matches are returned
164 .RB ( REG_NOSUB
165 wasn't passed to
166 .BR regcomp (),
167 the match succeeded, and
168 .I n
169 > 0), they overwrite
170 .I pmatch
171 as usual, and the match offsets remain relative to
172 .I string
173 (not
174 .IR "string + pmatch[0].rm_so" ).
175 This flag is a BSD extension, not present in POSIX.
176 .SS Match offsets
177 Unless
178 .B REG_NOSUB
179 was passed to
180 .BR regcomp (),
181 it is possible to
182 obtain the locations of matches within
183 .IR string :
184 .BR regexec ()
185 fills
186 .I n
187 elements of
188 .I pmatch
189 with results:
190 .I pmatch[0]
191 corresponds to the entire match,
192 .I pmatch[1]
193 to the first subexpression, etc.
194 If there were more matches than
195 .IR n ,
196 they are discarded;
197 if fewer,
198 unused elements of
199 .I pmatch
200 are filled with
201 .BR \-1 s.
202 .P
203 Each returned valid
204 .RB (non- \-1 )
205 match corresponds to the range
206 .RI [ "string + rm_so" , " string + rm_eo" ).
207 .P
208 .I regoff_t
209 is a signed integer type
210 capable of storing the largest value that can be stored in either an
211 .I ptrdiff_t
212 type or a
213 .I ssize_t
214 type.
215 .SS Error reporting
216 .BR regerror ()
217 is used to turn the error codes that can be returned by both
218 .BR regcomp ()
219 and
220 .BR regexec ()
221 into error message strings.
222 .P
223 If
224 .I preg
225 isn't a null pointer,
226 .I errcode
227 must be the latest error returned from an operation on
228 .IR preg .
229 .P
230 If
231 .I errbuf_size
232 isn't 0, up to
233 .I errbuf_size
234 bytes are copied to
235 .IR errbuf ;
236 the error string is always null-terminated, and truncated to fit.
237 .SS Freeing
238 .BR regfree ()
239 deinitializes the pattern buffer at
240 .IR *preg ,
241 freeing any associated memory;
242 .I *preg
243 must have been initialized via
244 .BR regcomp ().
245 .SH RETURN VALUE
246 .BR regcomp ()
247 returns zero for a successful compilation or an error code for failure.
248 .P
249 .BR regexec ()
250 returns zero for a successful match or
251 .B REG_NOMATCH
252 for failure.
253 .P
254 .BR regerror ()
255 returns the size of the buffer required to hold the string.
256 .SH ERRORS
257 The following errors can be returned by
258 .BR regcomp ():
259 .TP
260 .B REG_BADBR
261 Invalid use of back reference operator.
262 .TP
263 .B REG_BADPAT
264 Invalid use of pattern operators such as group or list.
265 .TP
266 .B REG_BADRPT
267 Invalid use of repetition operators such as using \[aq]*\[aq]
268 as the first character.
269 .TP
270 .B REG_EBRACE
271 Un-matched brace interval operators.
272 .TP
273 .B REG_EBRACK
274 Un-matched bracket list operators.
275 .TP
276 .B REG_ECOLLATE
277 Invalid collating element.
278 .TP
279 .B REG_ECTYPE
280 Unknown character class name.
281 .TP
282 .B REG_EEND
283 Nonspecific error.
284 This is not defined by POSIX.
285 .TP
286 .B REG_EESCAPE
287 Trailing backslash.
288 .TP
289 .B REG_EPAREN
290 Un-matched parenthesis group operators.
291 .TP
292 .B REG_ERANGE
293 Invalid use of the range operator;
294 for example,
295 the ending point of the range
296 occurs prior to the starting point.
297 .TP
298 .B REG_ESIZE
299 Compiled regular expression requires a pattern buffer larger than 64\ kB.
300 This is not defined by POSIX.
301 .TP
302 .B REG_ESPACE
303 The regex routines ran out of memory.
304 .TP
305 .B REG_ESUBREG
306 Invalid back reference to a subexpression.
307 .SH ATTRIBUTES
308 For an explanation of the terms used in this section, see
309 .BR attributes (7).
310 .TS
311 allbox;
312 lbx lb lb
313 l l l.
314 Interface Attribute Value
315 T{
316 .na
317 .nh
318 .BR regcomp (),
319 .BR regexec ()
320 T} Thread safety MT-Safe locale
321 T{
322 .na
323 .nh
324 .BR regerror ()
325 T} Thread safety MT-Safe env
326 T{
327 .na
328 .nh
329 .BR regfree ()
330 T} Thread safety MT-Safe
331 .TE
332 .SH STANDARDS
333 POSIX.1-2008.
334 .SH HISTORY
335 POSIX.1-2001.
336 .P
337 Prior to POSIX.1-2008,
338 .I regoff_t
339 was required to be
340 capable of storing the largest value that can be stored in either an
341 .I off_t
342 type or a
343 .I ssize_t
344 type.
345 .SH CAVEATS
346 .I re_nsub
347 is only required to be initialized if
348 .B REG_NOSUB
349 wasn't specified, but all known implementations initialize it regardless.
350 .\" glibc, musl, 4.4BSD, illumos
351 .P
352 Both
353 .I regex_t
354 and
355 .I regmatch_t
356 may (and do) have more members, in any order.
357 Always reference them by name.
358 .\" illumos has two more start/end pairs and the first one is of pointers
359 .SH EXAMPLES
360 .EX
361 #include <stdcountof.h>
362 #include <stdint.h>
363 #include <stdio.h>
364 #include <stdlib.h>
365 #include <regex.h>
366 \&
367 static const char *const str =
368 "1) John Driverhacker;\[rs]n2) John Doe;\[rs]n3) John Foo;\[rs]n";
369 static const char *const re = "John.*o";
370 \&
371 int main(void)
372 {
373 static const char *s = str;
374 regex_t regex;
375 regmatch_t pmatch[1];
376 regoff_t off, len;
377 \&
378 if (regcomp(&regex, re, REG_NEWLINE))
379 exit(EXIT_FAILURE);
380 \&
381 printf("String = \[rs]"%s\[rs]"\[rs]n", str);
382 printf("Matches:\[rs]n");
383 \&
384 for (unsigned int i = 0; ; i++) {
385 if (regexec(&regex, s, countof(pmatch), pmatch, 0))
386 break;
387 \&
388 off = pmatch[0].rm_so + (s \- str);
389 len = pmatch[0].rm_eo \- pmatch[0].rm_so;
390 printf("#%u:\[rs]n", i);
391 printf("offset = %jd; length = %jd\[rs]n", (intmax_t) off,
392 (intmax_t) len);
393 printf("substring = \[rs]"%.*s\[rs]"\[rs]n", len, s + pmatch[0].rm_so);
394 \&
395 s += pmatch[0].rm_eo;
396 }
397 \&
398 exit(EXIT_SUCCESS);
399 }
400 .EE
401 .SH SEE ALSO
402 .BR grep (1),
403 .BR regex (7)
404 .P
405 The glibc manual section,
406 .I "Regular Expressions"