Debian Codegraph @

upstream/debian-trixie/man3/regex.3

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