| blob | 100be4fbc82e597d907cd4a93e131ce0196e6e30 |
4 REGEX(3) C Library Functions REGEX(3)
8 NAME
9 regcomp, regexec, regerror, regfree - regular-expression
10 library
12 SYNOPSIS
13 #include <sys/types.h>
14 #include <regex.h>
16 int regcomp(regex_t *preg, const char *pattern, int cflags);
18 int regexec(const regex_t *preg, const char *string,
19 size_t nmatch, regmatch_t pmatch[], int eflags);
21 size_t regerror(int errcode, const regex_t *preg,
22 char *errbuf, size_t errbuf_size);
24 void regfree(regex_t *preg);
26 DESCRIPTION
27 These routines implement POSIX 1003.2 regular expressions
28 (``RE''s); see re_format(7). Regcomp compiles an RE written
29 as a string into an internal form, regexec matches that
30 internal form against a string and reports results, regerror
31 transforms error codes from either into human-readable mes-
32 sages, and regfree frees any dynamically-allocated storage
33 used by the internal form of an RE.
35 The header <regex.h> declares two structure types, regex_t
36 and regmatch_t, the former for compiled internal forms and
37 the latter for match reporting. It also declares the four
38 functions, a type regoff_t, and a number of constants with
39 names starting with ``REG_''.
41 Regcomp compiles the regular expression contained in the
42 pattern string, subject to the flags in cflags, and places
43 the results in the regex_t structure pointed to by preg.
44 Cflags is the bitwise OR of zero or more of the following
45 flags:
47 REG_EXTENDED Compile modern (``extended'') REs, rather than
48 the obsolete (``basic'') REs that are the
49 default.
51 REG_BASIC This is a synonym for 0, provided as a coun-
52 terpart to REG_EXTENDED to improve readabil-
53 ity.
55 REG_NOSPEC Compile with recognition of all special char-
56 acters turned off. All characters are thus
57 considered ordinary, so the ``RE'' is a
58 literal string. This is an extension, compa-
59 tible with but not specified by POSIX 1003.2,
63 SunOS 5.5 Last change: March 20, 1994 1
70 REGEX(3) C Library Functions REGEX(3)
74 and should be used with caution in software
75 intended to be portable to other systems.
76 REG_EXTENDED and REG_NOSPEC may not be used in
77 the same call to regcomp.
79 REG_ICASE Compile for matching that ignores upper/lower
80 case distinctions. See re_format(7).
82 REG_NOSUB Compile for matching that need only report
83 success or failure, not what was matched.
85 REG_NEWLINE Compile for newline-sensitive matching. By
86 default, newline is a completely ordinary
87 character with no special meaning in either
88 REs or strings. With this flag, `[^' bracket
89 expressions and `.' never match newline, a `^'
90 anchor matches the null string after any new-
91 line in the string in addition to its normal
92 function, and the `$' anchor matches the null
93 string before any newline in the string in
94 addition to its normal function.
96 REG_PEND The regular expression ends, not at the first
97 NUL, but just before the character pointed to
98 by the re_endp member of the structure pointed
99 to by preg. The re_endp member is of type
100 const char *. This flag permits inclusion of
101 NULs in the RE; they are considered ordinary
102 characters. This is an extension, compatible
103 with but not specified by POSIX 1003.2, and
104 should be used with caution in software
105 intended to be portable to other systems.
107 When successful, regcomp returns 0 and fills in the struc-
108 ture pointed to by preg. One member of that structure
109 (other than re_endp) is publicized: re_nsub, of type
110 size_t, contains the number of parenthesized subexpressions
111 within the RE (except that the value of this member is unde-
112 fined if the REG_NOSUB flag was used). If regcomp fails, it
113 returns a non-zero error code; see DIAGNOSTICS.
115 Regexec matches the compiled RE pointed to by preg against
116 the string, subject to the flags in eflags, and reports
117 results using nmatch, pmatch, and the returned value. The
118 RE must have been compiled by a previous invocation of
119 regcomp. The compiled form is not altered during execution
120 of regexec, so a single compiled RE can be used simultane-
121 ously by multiple threads.
123 By default, the NUL-terminated string pointed to by string
124 is considered to be the text of an entire line, minus any
125 terminating newline. The eflags argument is the bitwise OR
129 SunOS 5.5 Last change: March 20, 1994 2
136 REGEX(3) C Library Functions REGEX(3)
140 of zero or more of the following flags:
142 REG_NOTBOL The first character of the string is not the
143 beginning of a line, so the `^' anchor should
144 not match before it. This does not affect the
145 behavior of newlines under REG_NEWLINE.
147 REG_NOTEOL The NUL terminating the string does not end a
148 line, so the `$' anchor should not match
149 before it. This does not affect the behavior
150 of newlines under REG_NEWLINE.
152 REG_STARTEND The string is considered to start at string +
153 pmatch[0].rm_so and to have a terminating NUL
154 located at string + pmatch[0].rm_eo (there
155 need not actually be a NUL at that location),
156 regardless of the value of nmatch. See below
157 for the definition of pmatch and nmatch. This
158 is an extension, compatible with but not
159 specified by POSIX 1003.2, and should be used
160 with caution in software intended to be port-
161 able to other systems. Note that a non-zero
162 rm_so does not imply REG_NOTBOL; REG_STARTEND
163 affects only the location of the string, not
164 how it is matched.
166 See re_format(7) for a discussion of what is matched in
167 situations where an RE or a portion thereof could match any
168 of several substrings of string.
170 Normally, regexec returns 0 for success and the non-zero
171 code REG_NOMATCH for failure. Other non-zero error codes
172 may be returned in exceptional situations; see DIAGNOSTICS.
174 If REG_NOSUB was specified in the compilation of the RE, or
175 if nmatch is 0, regexec ignores the pmatch argument (but see
176 below for the case where REG_STARTEND is specified). Other-
177 wise, pmatch points to an array of nmatch structures of type
178 regmatch_t. Such a structure has at least the members rm_so
179 and rm_eo, both of type regoff_t (a signed arithmetic type
180 at least as large as an off_t and a ssize_t), containing
181 respectively the offset of the first character of a sub-
182 string and the offset of the first character after the end
183 of the substring. Offsets are measured from the beginning
184 of the string argument given to regexec. An empty substring
185 is denoted by equal offsets, both indicating the character
186 following the empty substring.
188 The 0th member of the pmatch array is filled in to indicate
189 what substring of string was matched by the entire RE.
190 Remaining members report what substring was matched by
191 parenthesized subexpressions within the RE; member i reports
195 SunOS 5.5 Last change: March 20, 1994 3
202 REGEX(3) C Library Functions REGEX(3)
206 subexpression i, with subexpressions counted (starting at 1)
207 by the order of their opening parentheses in the RE, left to
208 right. Unused entries in the array-corresponding either to
209 subexpressions that did not participate in the match at all,
210 or to subexpressions that do not exist in the RE (that is,
211 i > preg->re_nsub)-have both rm_so and rm_eo set to -1. If
212 a subexpression participated in the match several times, the
213 reported substring is the last one it matched. (Note, as an
214 example in particular, that when the RE `(b*)+' matches
215 `bbb', the parenthesized subexpression matches each of the
216 three `b's and then an infinite number of empty strings fol-
217 lowing the last `b', so the reported substring is one of the
218 empties.)
220 If REG_STARTEND is specified, pmatch must point to at least
221 one regmatch_t (even if nmatch is 0 or REG_NOSUB was speci-
222 fied), to hold the input offsets for REG_STARTEND. Use for
223 output is still entirely controlled by nmatch; if nmatch is
224 0 or REG_NOSUB was specified, the value of pmatch[0] will
225 not be changed by a successful regexec.
227 Regerror maps a non-zero errcode from either regcomp or
228 regexec to a human-readable, printable message. If preg is
229 non-NULL, the error code should have arisen from use of the
230 regex_t pointed to by preg, and if the error code came from
231 regcomp, it should have been the result from the most recent
232 regcomp using that regex_t. (Regerror may be able to supply
233 a more detailed message using information from the regex_t.)
234 Regerror places the NUL-terminated message into the buffer
235 pointed to by errbuf, limiting the length (including the
236 NUL) to at most errbuf_size bytes. If the whole message
237 won't fit, as much of it as will fit before the terminating
238 NUL is supplied. In any case, the returned value is the
239 size of buffer needed to hold the whole message (including
240 terminating NUL). If errbuf_size is 0, errbuf is ignored
241 but the return value is still correct.
243 If the errcode given to regerror is first ORed with
244 REG_ITOA, the ``message'' that results is the printable name
245 of the error code, e.g. ``REG_NOMATCH'', rather than an
246 explanation thereof. If errcode is REG_ATOI, then preg
247 shall be non-NULL and the re_endp member of the structure it
248 points to must point to the printable name of an error code;
249 in this case, the result in errbuf is the decimal digits of
250 the numeric value of the error code (0 if the name is not
251 recognized). REG_ITOA and REG_ATOI are intended primarily
252 as debugging facilities; they are extensions, compatible
253 with but not specified by POSIX 1003.2, and should be used
254 with caution in software intended to be portable to other
255 systems. Be warned also that they are considered experimen-
256 tal and changes are possible.
261 SunOS 5.5 Last change: March 20, 1994 4
268 REGEX(3) C Library Functions REGEX(3)
272 Regfree frees any dynamically-allocated storage associated
273 with the compiled RE pointed to by preg. The remaining
274 regex_t is no longer a valid compiled RE and the effect of
275 supplying it to regexec or regerror is undefined.
277 None of these functions references global variables except
278 for tables of constants; all are safe for use from multiple
279 threads if the arguments are safe.
281 IMPLEMENTATION CHOICES
282 There are a number of decisions that 1003.2 leaves up to the
283 implementor, either by explicitly saying ``undefined'' or by
284 virtue of them being forbidden by the RE grammar. This
285 implementation treats them as follows.
287 See re_format(7) for a discussion of the definition of
288 case-independent matching.
290 There is no particular limit on the length of REs, except
291 insofar as memory is limited. Memory usage is approximately
292 linear in RE size, and largely insensitive to RE complexity,
293 except for bounded repetitions. See BUGS for one short RE
294 using them that will run almost any system out of memory.
296 A backslashed character other than one specifically given a
297 magic meaning by 1003.2 (such magic meanings occur only in
298 obsolete [``basic''] REs) is taken as an ordinary character.
300 Any unmatched [ is a REG_EBRACK error.
302 Equivalence classes cannot begin or end bracket-expression
303 ranges. The endpoint of one range cannot begin another.
305 RE_DUP_MAX, the limit on repetition counts in bounded
306 repetitions, is 255.
308 A repetition operator (?, *, +, or bounds) cannot follow
309 another repetition operator. A repetition operator cannot
310 begin an expression or subexpression or follow `^' or `|'.
312 `|' cannot appear first or last in a (sub)expression or
313 after another `|', i.e. an operand of `|' cannot be an empty
314 subexpression. An empty parenthesized subexpression, `()',
315 is legal and matches an empty (sub)string. An empty string
316 is not a legal RE.
318 A `{' followed by a digit is considered the beginning of
319 bounds for a bounded repetition, which must then follow the
320 syntax for bounds. A `{' not followed by a digit is con-
321 sidered an ordinary character.
327 SunOS 5.5 Last change: March 20, 1994 5
334 REGEX(3) C Library Functions REGEX(3)
338 `^' and `$' beginning and ending subexpressions in obsolete
339 (``basic'') REs are anchors, not ordinary characters.
341 SEE ALSO
342 grep(1), re_format(7)
344 POSIX 1003.2, sections 2.8 (Regular Expression Notation) and
345 B.5 (C Binding for Regular Expression Matching).
347 DIAGNOSTICS
348 Non-zero error codes from regcomp and regexec include the
349 following:
351 REG_NOMATCH regexec() failed to match
352 REG_BADPAT invalid regular expression
353 REG_ECOLLATE invalid collating element
354 REG_ECTYPE invalid character class
355 REG_EESCAPE \ applied to unescapable character
356 REG_ESUBREG invalid backreference number
357 REG_EBRACK brackets [ ] not balanced
358 REG_EPAREN parentheses ( ) not balanced
359 REG_EBRACE braces { } not balanced
360 REG_BADBR invalid repetition count(s) in { }
361 REG_ERANGE invalid character range in [ ]
362 REG_ESPACE ran out of memory
363 REG_BADRPT ?, *, or + operand invalid
364 REG_EMPTY empty (sub)expression
365 REG_ASSERT ``can't happen''-you found a bug
366 REG_INVARG invalid argument, e.g. negative-length string
368 HISTORY
369 Originally written by Henry Spencer. Altered for inclusion
370 in the 4.4BSD distribution.
372 BUGS
373 This is an alpha release with known defects. Please report
374 problems.
376 There is one known functionality bug. The implementation of
377 internationalization is incomplete: the locale is always
378 assumed to be the default one of 1003.2, and only the col-
379 lating elements etc. of that locale are available.
381 The back-reference code is subtle and doubts linger about
382 its correctness in complex cases.
384 Regexec performance is poor. This will improve with later
385 releases. Nmatch exceeding 0 is expensive; nmatch exceeding
386 1 is worse. Regexec is largely insensitive to RE complexity
387 except that back references are massively expensive. RE
388 length does matter; in particular, there is a strong speed
389 bonus for keeping RE length under about 30 characters, with
393 SunOS 5.5 Last change: March 20, 1994 6
400 REGEX(3) C Library Functions REGEX(3)
404 most special characters counting roughly double.
406 Regcomp implements bounded repetitions by macro expansion,
407 which is costly in time and space if counts are large or
408 bounded repetitions are nested. An RE like, say,
409 `((((a{1,100}){1,100}){1,100}){1,100}){1,100}' will (eventu-
410 ally) run almost any existing machine out of swap space.
412 There are suspected problems with response to obscure error
413 conditions. Notably, certain kinds of internal overflow,
414 produced only by truly enormous REs or by multiply nested
415 bounded repetitions, are probably not handled well.
417 Due to a mistake in 1003.2, things like `a)b' are legal REs
418 because `)' is a special character only in the presence of a
419 previous unmatched `('. This can't be fixed until the spec
420 is fixed.
422 The standard's definition of back references is vague. For
423 example, does `a\(\(b\)*\2\)*d' match `abbbd'? Until the
424 standard is clarified, behavior in such cases should not be
425 relied on.
427 The implementation of word-boundary matching is a bit of a
428 kludge, and bugs may lurk in combinations of word-boundary
429 matching and anchoring.
459 SunOS 5.5 Last change: March 20, 1994 7