Annotation of embedaddon/php/ext/ereg/regex/regex.3, revision 1.1.1.1
1.1 misho 1: .TH REGEX 3 "17 May 1993"
2: .BY "Henry Spencer"
3: .de ZR
4: .\" one other place knows this name: the SEE ALSO section
5: .IR regex (7) \\$1
6: ..
7: .SH NAME
8: regcomp, regexec, regerror, regfree \- regular-expression library
9: .SH SYNOPSIS
10: .ft B
11: .\".na
12: #include <sys/types.h>
13: .br
14: #include <regex.h>
15: .HP 10
16: int regcomp(regex_t\ *preg, const\ char\ *pattern, int\ cflags);
17: .HP
18: int\ regexec(const\ regex_t\ *preg, const\ char\ *string,
19: size_t\ nmatch, regmatch_t\ pmatch[], int\ eflags);
20: .HP
21: size_t\ regerror(int\ errcode, const\ regex_t\ *preg,
22: char\ *errbuf, size_t\ errbuf_size);
23: .HP
24: void\ regfree(regex_t\ *preg);
25: .\".ad
26: .ft
27: .SH DESCRIPTION
28: These routines implement POSIX 1003.2 regular expressions (``RE''s);
29: see
30: .ZR .
31: .I Regcomp
32: compiles an RE written as a string into an internal form,
33: .I regexec
34: matches that internal form against a string and reports results,
35: .I regerror
36: transforms error codes from either into human-readable messages,
37: and
38: .I regfree
39: frees any dynamically-allocated storage used by the internal form
40: of an RE.
41: .PP
42: The header
43: .I <regex.h>
44: declares two structure types,
45: .I regex_t
46: and
47: .IR regmatch_t ,
48: the former for compiled internal forms and the latter for match reporting.
49: It also declares the four functions,
50: a type
51: .IR regoff_t ,
52: and a number of constants with names starting with ``REG_''.
53: .PP
54: .I Regcomp
55: compiles the regular expression contained in the
56: .I pattern
57: string,
58: subject to the flags in
59: .IR cflags ,
60: and places the results in the
61: .I regex_t
62: structure pointed to by
63: .IR preg .
64: .I Cflags
65: is the bitwise OR of zero or more of the following flags:
66: .IP REG_EXTENDED \w'REG_EXTENDED'u+2n
67: Compile modern (``extended'') REs,
68: rather than the obsolete (``basic'') REs that
69: are the default.
70: .IP REG_BASIC
71: This is a synonym for 0,
72: provided as a counterpart to REG_EXTENDED to improve readability.
73: .IP REG_NOSPEC
74: Compile with recognition of all special characters turned off.
75: All characters are thus considered ordinary,
76: so the ``RE'' is a literal string.
77: This is an extension,
78: compatible with but not specified by POSIX 1003.2,
79: and should be used with
80: caution in software intended to be portable to other systems.
81: REG_EXTENDED and REG_NOSPEC may not be used
82: in the same call to
83: .IR regcomp .
84: .IP REG_ICASE
85: Compile for matching that ignores upper/lower case distinctions.
86: See
87: .ZR .
88: .IP REG_NOSUB
89: Compile for matching that need only report success or failure,
90: not what was matched.
91: .IP REG_NEWLINE
92: Compile for newline-sensitive matching.
93: By default, newline is a completely ordinary character with no special
94: meaning in either REs or strings.
95: With this flag,
96: `[^' bracket expressions and `.' never match newline,
97: a `^' anchor matches the null string after any newline in the string
98: in addition to its normal function,
99: and the `$' anchor matches the null string before any newline in the
100: string in addition to its normal function.
101: .IP REG_PEND
102: The regular expression ends,
103: not at the first NUL,
104: but just before the character pointed to by the
105: .I re_endp
106: member of the structure pointed to by
107: .IR preg .
108: The
109: .I re_endp
110: member is of type
111: .IR const\ char\ * .
112: This flag permits inclusion of NULs in the RE;
113: they are considered ordinary characters.
114: This is an extension,
115: compatible with but not specified by POSIX 1003.2,
116: and should be used with
117: caution in software intended to be portable to other systems.
118: .PP
119: When successful,
120: .I regcomp
121: returns 0 and fills in the structure pointed to by
122: .IR preg .
123: One member of that structure
124: (other than
125: .IR re_endp )
126: is publicized:
127: .IR re_nsub ,
128: of type
129: .IR size_t ,
130: contains the number of parenthesized subexpressions within the RE
131: (except that the value of this member is undefined if the
132: REG_NOSUB flag was used).
133: If
134: .I regcomp
135: fails, it returns a non-zero error code;
136: see DIAGNOSTICS.
137: .PP
138: .I Regexec
139: matches the compiled RE pointed to by
140: .I preg
141: against the
142: .IR string ,
143: subject to the flags in
144: .IR eflags ,
145: and reports results using
146: .IR nmatch ,
147: .IR pmatch ,
148: and the returned value.
149: The RE must have been compiled by a previous invocation of
150: .IR regcomp .
151: The compiled form is not altered during execution of
152: .IR regexec ,
153: so a single compiled RE can be used simultaneously by multiple threads.
154: .PP
155: By default,
156: the NUL-terminated string pointed to by
157: .I string
158: is considered to be the text of an entire line, minus any terminating
159: newline.
160: The
161: .I eflags
162: argument is the bitwise OR of zero or more of the following flags:
163: .IP REG_NOTBOL \w'REG_STARTEND'u+2n
164: The first character of
165: the string
166: is not the beginning of a line, so the `^' anchor should not match before it.
167: This does not affect the behavior of newlines under REG_NEWLINE.
168: .IP REG_NOTEOL
169: The NUL terminating
170: the string
171: does not end a line, so the `$' anchor should not match before it.
172: This does not affect the behavior of newlines under REG_NEWLINE.
173: .IP REG_STARTEND
174: The string is considered to start at
175: \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_so\fR
176: and to have a terminating NUL located at
177: \fIstring\fR\ + \fIpmatch\fR[0].\fIrm_eo\fR
178: (there need not actually be a NUL at that location),
179: regardless of the value of
180: .IR nmatch .
181: See below for the definition of
182: .IR pmatch
183: and
184: .IR nmatch .
185: This is an extension,
186: compatible with but not specified by POSIX 1003.2,
187: and should be used with
188: caution in software intended to be portable to other systems.
189: Note that a non-zero \fIrm_so\fR does not imply REG_NOTBOL;
190: REG_STARTEND affects only the location of the string,
191: not how it is matched.
192: .PP
193: See
194: .ZR
195: for a discussion of what is matched in situations where an RE or a
196: portion thereof could match any of several substrings of
197: .IR string .
198: .PP
199: Normally,
200: .I regexec
201: returns 0 for success and the non-zero code REG_NOMATCH for failure.
202: Other non-zero error codes may be returned in exceptional situations;
203: see DIAGNOSTICS.
204: .PP
205: If REG_NOSUB was specified in the compilation of the RE,
206: or if
207: .I nmatch
208: is 0,
209: .I regexec
210: ignores the
211: .I pmatch
212: argument (but see below for the case where REG_STARTEND is specified).
213: Otherwise,
214: .I pmatch
215: points to an array of
216: .I nmatch
217: structures of type
218: .IR regmatch_t .
219: Such a structure has at least the members
220: .I rm_so
221: and
222: .IR rm_eo ,
223: both of type
224: .I regoff_t
225: (a signed arithmetic type at least as large as an
226: .I off_t
227: and a
228: .IR ssize_t ),
229: containing respectively the offset of the first character of a substring
230: and the offset of the first character after the end of the substring.
231: Offsets are measured from the beginning of the
232: .I string
233: argument given to
234: .IR regexec .
235: An empty substring is denoted by equal offsets,
236: both indicating the character following the empty substring.
237: .PP
238: The 0th member of the
239: .I pmatch
240: array is filled in to indicate what substring of
241: .I string
242: was matched by the entire RE.
243: Remaining members report what substring was matched by parenthesized
244: subexpressions within the RE;
245: member
246: .I i
247: reports subexpression
248: .IR i ,
249: with subexpressions counted (starting at 1) by the order of their opening
250: parentheses in the RE, left to right.
251: Unused entries in the array\(emcorresponding either to subexpressions that
252: did not participate in the match at all, or to subexpressions that do not
253: exist in the RE (that is, \fIi\fR\ > \fIpreg\fR\->\fIre_nsub\fR)\(emhave both
254: .I rm_so
255: and
256: .I rm_eo
257: set to \-1.
258: If a subexpression participated in the match several times,
259: the reported substring is the last one it matched.
260: (Note, as an example in particular, that when the RE `(b*)+' matches `bbb',
261: the parenthesized subexpression matches each of the three `b's and then
262: an infinite number of empty strings following the last `b',
263: so the reported substring is one of the empties.)
264: .PP
265: If REG_STARTEND is specified,
266: .I pmatch
267: must point to at least one
268: .I regmatch_t
269: (even if
270: .I nmatch
271: is 0 or REG_NOSUB was specified),
272: to hold the input offsets for REG_STARTEND.
273: Use for output is still entirely controlled by
274: .IR nmatch ;
275: if
276: .I nmatch
277: is 0 or REG_NOSUB was specified,
278: the value of
279: .IR pmatch [0]
280: will not be changed by a successful
281: .IR regexec .
282: .PP
283: .I Regerror
284: maps a non-zero
285: .I errcode
286: from either
287: .I regcomp
288: or
289: .I regexec
290: to a human-readable, printable message.
291: If
292: .I preg
293: is non-NULL,
294: the error code should have arisen from use of
295: the
296: .I regex_t
297: pointed to by
298: .IR preg ,
299: and if the error code came from
300: .IR regcomp ,
301: it should have been the result from the most recent
302: .I regcomp
303: using that
304: .IR regex_t .
305: .RI ( Regerror
306: may be able to supply a more detailed message using information
307: from the
308: .IR regex_t .)
309: .I Regerror
310: places the NUL-terminated message into the buffer pointed to by
311: .IR errbuf ,
312: limiting the length (including the NUL) to at most
313: .I errbuf_size
314: bytes.
315: If the whole message won't fit,
316: as much of it as will fit before the terminating NUL is supplied.
317: In any case,
318: the returned value is the size of buffer needed to hold the whole
319: message (including terminating NUL).
320: If
321: .I errbuf_size
322: is 0,
323: .I errbuf
324: is ignored but the return value is still correct.
325: .PP
326: If the
327: .I errcode
328: given to
329: .I regerror
330: is first ORed with REG_ITOA,
331: the ``message'' that results is the printable name of the error code,
332: e.g. ``REG_NOMATCH'',
333: rather than an explanation thereof.
334: If
335: .I errcode
336: is REG_ATOI,
337: then
338: .I preg
339: shall be non-NULL and the
340: .I re_endp
341: member of the structure it points to
342: must point to the printable name of an error code;
343: in this case, the result in
344: .I errbuf
345: is the decimal digits of
346: the numeric value of the error code
347: (0 if the name is not recognized).
348: REG_ITOA and REG_ATOI are intended primarily as debugging facilities;
349: they are extensions,
350: compatible with but not specified by POSIX 1003.2,
351: and should be used with
352: caution in software intended to be portable to other systems.
353: Be warned also that they are considered experimental and changes are possible.
354: .PP
355: .I Regfree
356: frees any dynamically-allocated storage associated with the compiled RE
357: pointed to by
358: .IR preg .
359: The remaining
360: .I regex_t
361: is no longer a valid compiled RE
362: and the effect of supplying it to
363: .I regexec
364: or
365: .I regerror
366: is undefined.
367: .PP
368: None of these functions references global variables except for tables
369: of constants;
370: all are safe for use from multiple threads if the arguments are safe.
371: .SH IMPLEMENTATION CHOICES
372: There are a number of decisions that 1003.2 leaves up to the implementor,
373: either by explicitly saying ``undefined'' or by virtue of them being
374: forbidden by the RE grammar.
375: This implementation treats them as follows.
376: .PP
377: See
378: .ZR
379: for a discussion of the definition of case-independent matching.
380: .PP
381: There is no particular limit on the length of REs,
382: except insofar as memory is limited.
383: Memory usage is approximately linear in RE size, and largely insensitive
384: to RE complexity, except for bounded repetitions.
385: See BUGS for one short RE using them
386: that will run almost any system out of memory.
387: .PP
388: A backslashed character other than one specifically given a magic meaning
389: by 1003.2 (such magic meanings occur only in obsolete [``basic''] REs)
390: is taken as an ordinary character.
391: .PP
392: Any unmatched [ is a REG_EBRACK error.
393: .PP
394: Equivalence classes cannot begin or end bracket-expression ranges.
395: The endpoint of one range cannot begin another.
396: .PP
397: RE_DUP_MAX, the limit on repetition counts in bounded repetitions, is 255.
398: .PP
399: A repetition operator (?, *, +, or bounds) cannot follow another
400: repetition operator.
401: A repetition operator cannot begin an expression or subexpression
402: or follow `^' or `|'.
403: .PP
404: `|' cannot appear first or last in a (sub)expression or after another `|',
405: i.e. an operand of `|' cannot be an empty subexpression.
406: An empty parenthesized subexpression, `()', is legal and matches an
407: empty (sub)string.
408: An empty string is not a legal RE.
409: .PP
410: A `{' followed by a digit is considered the beginning of bounds for a
411: bounded repetition, which must then follow the syntax for bounds.
412: A `{' \fInot\fR followed by a digit is considered an ordinary character.
413: .PP
414: `^' and `$' beginning and ending subexpressions in obsolete (``basic'')
415: REs are anchors, not ordinary characters.
416: .SH SEE ALSO
417: grep(1), regex(7)
418: .PP
419: POSIX 1003.2, sections 2.8 (Regular Expression Notation)
420: and
421: B.5 (C Binding for Regular Expression Matching).
422: .SH DIAGNOSTICS
423: Non-zero error codes from
424: .I regcomp
425: and
426: .I regexec
427: include the following:
428: .PP
429: .nf
430: .ta \w'REG_ECOLLATE'u+3n
431: REG_NOMATCH regexec() failed to match
432: REG_BADPAT invalid regular expression
433: REG_ECOLLATE invalid collating element
434: REG_ECTYPE invalid character class
435: REG_EESCAPE \e applied to unescapable character
436: REG_ESUBREG invalid backreference number
437: REG_EBRACK brackets [ ] not balanced
438: REG_EPAREN parentheses ( ) not balanced
439: REG_EBRACE braces { } not balanced
440: REG_BADBR invalid repetition count(s) in { }
441: REG_ERANGE invalid character range in [ ]
442: REG_ESPACE ran out of memory
443: REG_BADRPT ?, *, or + operand invalid
444: REG_EMPTY empty (sub)expression
445: REG_ASSERT ``can't happen''\(emyou found a bug
446: REG_INVARG invalid argument, e.g. negative-length string
447: .fi
448: .SH HISTORY
449: Written by Henry Spencer at University of Toronto,
450: henry@zoo.toronto.edu.
451: .SH BUGS
452: This is an alpha release with known defects.
453: Please report problems.
454: .PP
455: There is one known functionality bug.
456: The implementation of internationalization is incomplete:
457: the locale is always assumed to be the default one of 1003.2,
458: and only the collating elements etc. of that locale are available.
459: .PP
460: The back-reference code is subtle and doubts linger about its correctness
461: in complex cases.
462: .PP
463: .I Regexec
464: performance is poor.
465: This will improve with later releases.
466: .I Nmatch
467: exceeding 0 is expensive;
468: .I nmatch
469: exceeding 1 is worse.
470: .I Regexec
471: is largely insensitive to RE complexity \fIexcept\fR that back
472: references are massively expensive.
473: RE length does matter; in particular, there is a strong speed bonus
474: for keeping RE length under about 30 characters,
475: with most special characters counting roughly double.
476: .PP
477: .I Regcomp
478: implements bounded repetitions by macro expansion,
479: which is costly in time and space if counts are large
480: or bounded repetitions are nested.
481: An RE like, say,
482: `((((a{1,100}){1,100}){1,100}){1,100}){1,100}'
483: will (eventually) run almost any existing machine out of swap space.
484: .PP
485: There are suspected problems with response to obscure error conditions.
486: Notably,
487: certain kinds of internal overflow,
488: produced only by truly enormous REs or by multiply nested bounded repetitions,
489: are probably not handled well.
490: .PP
491: Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is
492: a special character only in the presence of a previous unmatched `('.
493: This can't be fixed until the spec is fixed.
494: .PP
495: The standard's definition of back references is vague.
496: For example, does
497: `a\e(\e(b\e)*\e2\e)*d' match `abbbd'?
498: Until the standard is clarified,
499: behavior in such cases should not be relied on.
500: .PP
501: The implementation of word-boundary matching is a bit of a kludge,
502: and bugs may lurk in combinations of word-boundary matching and anchoring.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to regex.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / ext / ereg / regex