1 .\" Copyright (C), 1995, Graeme W. Wilford. (Wilf.)
3 .\" Permission is granted to make and distribute verbatim copies of this
4 .\" manual provided the copyright notice and this permission notice are
5 .\" preserved on all copies.
7 .\" Permission is granted to copy and distribute modified versions of this
8 .\" manual under the conditions for verbatim copying, provided that the
9 .\" entire resulting derived work is distributed under the terms of a
10 .\" permission notice identical to this one.
12 .\" Since the Linux kernel and libraries are constantly changing, this
13 .\" manual page may be incorrect or out-of-date. The author(s) assume no
14 .\" responsibility for errors or omissions, or for damages resulting from
15 .\" the use of the information contained herein. The author(s) may not
16 .\" have taken the same level of care in the production of this manual,
17 .\" which is licensed free of charge, as they might when working
20 .\" Formatted or processed versions of this manual, if unaccompanied by
21 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" Wed Jun 14 16:10:28 BST 1995 Wilf. (G.Wilford@ee.surrey.ac.uk)
24 .\" Tiny change in formatting - aeb, 950812
25 .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
27 .\" show the synopsis section nicely
32 .TH REGEX 3 2011-09-27 "GNU" "Linux Programmer's Manual"
34 regcomp, regexec, regerror, regfree \- POSIX regex functions
37 .B #include <sys/types.h>
40 .BI "int regcomp(regex_t *" preg ", const char *" regex ", int " cflags );
42 .BI "int regexec(const regex_t *" preg ", const char *" string \
44 .BI " regmatch_t " pmatch[] ", int " eflags );
46 .BI "size_t regerror(int " errcode ", const regex_t *" preg ", char *" errbuf ,
47 .BI " size_t " errbuf_size );
49 .BI "void regfree(regex_t *" preg );
52 .SS "POSIX Regex Compiling"
54 is used to compile a regular expression into a form that is suitable
62 a pointer to a pattern buffer storage area;
64 a pointer to the null-terminated string and
66 flags used to determine the type of compilation.
68 All regular expression searching must be done via a compiled pattern
71 must always be supplied with the address of a
73 initialized pattern buffer.
78 of one or more of the following:
83 Extended Regular Expression syntax when interpreting
87 Basic Regular Expression syntax is used.
90 Do not differentiate case.
93 searches using this pattern buffer will be case insensitive.
96 Support for substring addressing of matches is not required.
103 are ignored if the pattern buffer supplied was compiled with this flag set.
106 Match-any-character operators don't match a newline.
110 not containing a newline does not match a newline.
112 Match-beginning-of-line operator
114 matches the empty string immediately after a newline, regardless of
117 the execution flags of
122 Match-end-of-line operator
124 matches the empty string immediately before a newline, regardless of
129 .SS "POSIX Regex Matching"
131 is used to match a null-terminated string
132 against the precompiled pattern buffer,
137 are used to provide information regarding the location of any matches.
145 which cause changes in matching behavior described below.
148 The match-beginning-of-line operator always fails to match (but see the
152 This flag may be used when different portions of a string are passed to
154 and the beginning of the string should not be interpreted as the
155 beginning of the line.
158 The match-end-of-line operator always fails to match (but see the
165 was set for the compilation of the pattern buffer, it is possible to
166 obtain substring match addressing information.
168 must be dimensioned to have at least
171 These are filled in by
173 with substring match addresses.
174 Any unused structure elements will contain the value \-1.
178 structure which is the type of
194 element that is not \-1 indicates the start offset of the next largest
195 substring match within the string.
198 element indicates the end offset of the match,
199 which is the offset of the first character after the matching text.
200 .SS "Posix Error Reporting"
202 is used to turn the error codes that can be returned by both
206 into error message strings.
209 is passed the error code,
213 a pointer to a character string buffer,
215 and the size of the string buffer,
217 It returns the size of the
219 required to contain the null-terminated error message string.
226 is filled in with the first
227 .I "errbuf_size \- 1"
228 characters of the error message and a terminating null byte (\(aq\\0\(aq).
229 .SS "POSIX Pattern Buffer Freeing"
232 with a precompiled pattern buffer,
234 will free the memory allocated to the pattern buffer by the compiling
239 returns zero for a successful compilation or an error code for failure.
242 returns zero for a successful match or
246 The following errors can be returned by
250 Invalid use of back reference operator.
253 Invalid use of pattern operators such as group or list.
256 Invalid use of repetition operators such as using \(aq*\(aq
257 as the first character.
260 Un-matched brace interval operators.
263 Un-matched bracket list operators.
266 Invalid collating element.
269 Unknown character class name.
273 This is not defined by POSIX.2.
279 Un-matched parenthesis group operators.
282 Invalid use of the range operator, e.g., the ending point of the range
283 occurs prior to the starting point.
286 Compiled regular expression requires a pattern buffer larger than 64Kb.
287 This is not defined by POSIX.2.
290 The regex routines ran out of memory.
293 Invalid back reference to a subexpression.