Debian Codegraph @

upstream/debian-unstable/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-22 "Linux man-pages 6.18"
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 ,\~ strnul(string) ).
159 This allows matching embedded NUL bytes.
160 If any matches are returned
161 .RB ( REG_NOSUB
162 wasn't passed to
163 .BR regcomp (),
164 the match succeeded, and
165 .I n
166 > 0), they overwrite
167 .I pmatch
168 as usual, and the match offsets remain relative to
169 .I string
170 (not
171 .IR "string + pmatch[0].rm_so" ).
172 This flag is a BSD extension, not present in POSIX.
173 .SS Match offsets
174 Unless
175 .B REG_NOSUB
176 was passed to
177 .BR regcomp (),
178 it is possible to
179 obtain the locations of matches within
180 .IR string :
181 .BR regexec ()
182 fills
183 .I n
184 elements of
185 .I pmatch
186 with results:
187 .I pmatch[0]
188 corresponds to the entire match,
189 .I pmatch[1]
190 to the first subexpression, etc.
191 If there were more matches than
192 .IR n ,
193 they are discarded;
194 if fewer,
195 unused elements of
196 .I pmatch
197 are filled with
198 .BR \-1 s.
199 .P
200 Each returned valid
201 .RB (non- \-1 )
202 match corresponds to the range
203 .RI [ "string + rm_so" , " string + rm_eo" ).
204 .P
205 .I regoff_t
206 is a signed integer type
207 capable of storing the largest value that can be stored in either an
208 .I ptrdiff_t
209 type or a
210 .I ssize_t
211 type.
212 .SS Error reporting
213 .BR regerror ()
214 is used to turn the error codes that can be returned by both
215 .BR regcomp ()
216 and
217 .BR regexec ()
218 into error message strings.
219 .P
220 If
221 .I preg
222 isn't a null pointer,
223 .I errcode
224 must be the latest error returned from an operation on
225 .IR preg .
226 .P
227 If
228 .I errbuf_size
229 isn't 0, up to
230 .I errbuf_size
231 bytes are copied to
232 .IR errbuf ;
233 the error string is always null-terminated, and truncated to fit.
234 .SS Freeing
235 .BR regfree ()
236 deinitializes the pattern buffer at
237 .IR *preg ,
238 freeing any associated memory;
239 .I *preg
240 must have been initialized via
241 .BR regcomp ().
242 .SH RETURN VALUE
243 .BR regcomp ()
244 returns zero for a successful compilation or an error code for failure.
245 .P
246 .BR regexec ()
247 returns zero for a successful match or
248 .B REG_NOMATCH
249 for failure.
250 .P
251 .BR regerror ()
252 returns the size of the buffer required to hold the string.
253 .SH ERRORS
254 The following errors can be returned by
255 .BR regcomp ():
256 .TP
257 .B REG_BADBR
258 Invalid use of back reference operator.
259 .TP
260 .B REG_BADPAT
261 Invalid use of pattern operators such as group or list.
262 .TP
263 .B REG_BADRPT
264 Invalid use of repetition operators such as using \[aq]*\[aq]
265 as the first character.
266 .TP
267 .B REG_EBRACE
268 Un-matched brace interval operators.
269 .TP
270 .B REG_EBRACK
271 Un-matched bracket list operators.
272 .TP
273 .B REG_ECOLLATE
274 Invalid collating element.
275 .TP
276 .B REG_ECTYPE
277 Unknown character class name.
278 .TP
279 .B REG_EEND
280 Nonspecific error.
281 This is not defined by POSIX.
282 .TP
283 .B REG_EESCAPE
284 Trailing backslash.
285 .TP
286 .B REG_EPAREN
287 Un-matched parenthesis group operators.
288 .TP
289 .B REG_ERANGE
290 Invalid use of the range operator;
291 for example,
292 the ending point of the range
293 occurs prior to the starting point.
294 .TP
295 .B REG_ESIZE
296 Compiled regular expression requires a pattern buffer larger than 64\ kB.
297 This is not defined by POSIX.
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.
304 .SH ATTRIBUTES
305 For an explanation of the terms used in this section, see
306 .BR attributes (7).
307 .TS
308 allbox;
309 lbx lb lb
310 l l l.
311 Interface Attribute Value
312 T{
313 .na
314 .nh
315 .BR regcomp (),
316 .BR regexec ()
317 T} Thread safety MT-Safe locale
318 T{
319 .na
320 .nh
321 .BR regerror ()
322 T} Thread safety MT-Safe env
323 T{
324 .na
325 .nh
326 .BR regfree ()
327 T} Thread safety MT-Safe
328 .TE
329 .SH STANDARDS
330 POSIX.1-2008.
331 .SH HISTORY
332 POSIX.1-2001.
333 .P
334 Prior to POSIX.1-2008,
335 .I regoff_t
336 was required to be
337 capable of storing the largest value that can be stored in either an
338 .I off_t
339 type or a
340 .I ssize_t
341 type.
342 .SH CAVEATS
343 .I re_nsub
344 is only required to be initialized if
345 .B REG_NOSUB
346 wasn't specified, but all known implementations initialize it regardless.
347 .\" glibc, musl, 4.4BSD, illumos
348 .P
349 Both
350 .I regex_t
351 and
352 .I regmatch_t
353 may (and do) have more members, in any order.
354 Always reference them by name.
355 .\" illumos has two more start/end pairs and the first one is of pointers
356 .SH EXAMPLES
357 .EX
358 #include <stdcountof.h>
359 #include <stdint.h>
360 #include <stdio.h>
361 #include <stdlib.h>
362 #include <regex.h>
363 \&
364 static const char *const str =
365 "1) John Driverhacker;\[rs]n2) John Doe;\[rs]n3) John Foo;\[rs]n";
366 static const char *const re = "John.*o";
367 \&
368 int main(void)
369 {
370 static const char *s = str;
371 regex_t regex;
372 regmatch_t pmatch[1];
373 regoff_t off, len;
374 \&
375 if (regcomp(&regex, re, REG_NEWLINE))
376 exit(EXIT_FAILURE);
377 \&
378 printf("String = \[rs]"%s\[rs]"\[rs]n", str);
379 printf("Matches:\[rs]n");
380 \&
381 for (unsigned int i = 0; ; i++) {
382 if (regexec(&regex, s, countof(pmatch), pmatch, 0))
383 break;
384 \&
385 off = pmatch[0].rm_so + (s \- str);
386 len = pmatch[0].rm_eo \- pmatch[0].rm_so;
387 printf("#%u:\[rs]n", i);
388 printf("offset = %jd; length = %jd\[rs]n", (intmax_t) off,
389 (intmax_t) len);
390 printf("substring = \[rs]"%.*s\[rs]"\[rs]n", len, s + pmatch[0].rm_so);
391 \&
392 s += pmatch[0].rm_eo;
393 }
394 \&
395 exit(EXIT_SUCCESS);
396 }
397 .EE
398 .SH SEE ALSO
399 .BR grep (1),
400 .BR regex (7)
401 .P
402 The glibc manual section,
403 .I "Regular Expressions"