te
Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.
The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
This notice shall appear on any product containing this material.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
regcomp, regexec, regerror, regfree - regular expression matching

#include <sys/types.h>
#include <regex.h>

int regcomp(regex_t *restrict preg, const char *restrict pattern,
 int cflags);

int regexec(const regex_t *restrict preg,
 const char *restrict string, size_t nmatch,
 regmatch_t pmatch[restrict], int eflags);

size_t regerror(int errcode, const regex_t *restrict preg,
 char *restrict errbuf, size_t errbuf_size);

void regfree(regex_t *preg);

These functions interpret basic and extended regular expressions (described on the regex(5) manual page).

The structure type regex_t contains at least the following member: size_t re_nsub

The structure type regmatch_t contains at least the following members: regoff_t rm_so

regoff_t rm_eo

The regcomp() function will compile the regular expression contained in the string pointed to by the pattern argument and place the results in the structure pointed to by preg. The cflags argument is the bitwise inclusive OR of zero or more of the following flags, which are defined in the header <regex.h>: REG_EXTENDED

REG_ICASE REG_NOSUB REG_NEWLINE

The default regular expression type for pattern is a Basic Regular Expression. The application can specify Extended Regular Expressions using the REG_EXTENDED cflags flag.

If the REG_NOSUB flag was not set in cflags, then regcomp() will set re_nsub to the number of parenthesised subexpressions (delimited by \e(\e) in basic regular expressions or () in extended regular expressions) found in pattern.

The regexec() function compares the null-terminated string specified by string with the compiled regular expression preg initialized by a previous call to regcomp(). The eflags argument is the bitwise inclusive OR of zero or more of the following flags, which are defined in the header <regex.h>: REG_NOTBOL

REG_NOTEOL

If nmatch is zero or REG_NOSUB was set in the cflags argument to regcomp(), then regexec() will ignore the pmatch argument. Otherwise, the pmatch argument must point to an array with at least nmatch elements, and regexec() will fill in the elements of that array with offsets of the substrings of string that correspond to the parenthesised subexpressions of pattern: pmatch[i].rm_so will be the byte offset of the beginning and pmatch[i].rm_eo will be one greater than the byte offset of the end of substring i. (Subexpression i begins at the ith matched open parenthesis, counting from 1.) Offsets in pmatch[0] identify the substring that corresponds to the entire regular expression. Unused elements of pmatch up to pmatch[nmatch-1] will be filled with -1. If there are more than nmatch subexpressions in pattern (pattern itself counts as a subexpression), then regexec() will still do the match, but will record only the first nmatch substrings.

When matching a basic or extended regular expression, any given parenthesised subexpression of pattern might participate in the match of several different substrings of string, or it might not match any substring even though the pattern as a whole did match. The following rules are used to determine which substrings to report in pmatch when matching regular expressions: 1.

2. 3. 4. 5.

If, when regexec() is called, the locale is different from when the regular expression was compiled, the result is undefined.

If REG_NEWLINE is not set in cflags, then a NEWLINE character in pattern or string will be treated as an ordinary character. If REG_NEWLINE is set, then newline will be treated as an ordinary character except as follows: 1.

2. 3.

The regfree() function frees any memory allocated by regcomp() associated with preg.

The following constants are defined as error return values: REG_NOMATCH

REG_BADPAT REG_ECOLLATE REG_ECTYPE REG_EESCAPE REG_ESUBREG REG_EBRACK REG_ENOSYS REG_EPAREN REG_EBRACE REG_BADBR REG_ERANGE REG_ESPACE REG_BADRPT

The regerror() function provides a mapping from error codes returned by regcomp() and regexec() to unspecified printable strings. It generates a string corresponding to the value of the errcode argument, which must be the last non-zero value returned by regcomp() or regexec() with the given value of preg. If errcode is not such a value, an error message indicating that the error code is invalid is returned.

If preg is a NULL pointer, but errcode is a value returned by a previous call to regexec() or regcomp(), the regerror() still generates an error string corresponding to the value of errcode.

If the errbuf_size argument is not zero, regerror() will place the generated string into the buffer of size errbuf_size bytes pointed to by errbuf. If the string (including the terminating NULL) cannot fit in the buffer, regerror() will truncate the string and null-terminate the result.

If errbuf_size is zero, regerror() ignores the errbuf argument, and returns the size of the buffer needed to hold the generated string.

If the preg argument to regexec() or regfree() is not a compiled regular expression returned by regcomp(), the result is undefined. A preg is no longer treated as a compiled regular expression after it is given to regfree().

See regex(5) for BRE (Basic Regular Expression) Anchoring.

On successful completion, the regcomp() function returns 0. Otherwise, it returns an integer value indicating an error as described in <regex.h>, and the content of preg is undefined.

On successful completion, the regexec() function returns 0. Otherwise it returns REG_NOMATCH to indicate no match, or REG_ENOSYS to indicate that the function is not supported.

Upon successful completion, the regerror() function returns the number of bytes needed to hold the entire generated string. Otherwise, it returns 0 to indicate that the function is not implemented.

The regfree() function returns no value.

No errors are defined.

An application could use:

regerror(code,preg,(char *)NULL,(size_t)0)

to find out how big a buffer is needed for the generated string, malloc a buffer to hold the string, and then call regerror() again to get the string (see malloc(3C)). Alternately, it could allocate a fixed, static buffer that is big enough to hold most strings, and then use malloc() to allocate a larger buffer if it finds that this is too small.

Example 1 Example to match string against the extended regular expression in pattern.

#include <regex.h>
/*
* Match string against the extended regular expression in
* pattern, treating errors as no match.
*
* return 1 for match, 0 for no match
*/

int
match(const char *string, char *pattern)
{
 int status;
 regex_t re;
 if (regcomp(&re, pattern, REG_EXTENDED\||\|REG_NOSUB) != 0) {
 return(0); /* report error */
 }
 status = regexec(&re, string, (size_t) 0, NULL, 0);
 regfree(&re);
 if (status != 0) {
 return(0); /* report error */
 }
 return(1);
}

The following demonstrates how the REG_NOTBOL flag could be used with regexec() to find all substrings in a line that match a pattern supplied by a user. (For simplicity of the example, very little error checking is done.)

(void) regcomp (&re, pattern, 0);
/* this call to regexec(\|) finds the first match on the line */
error = regexec (&re, &buffer[0], 1, &pm, 0);
while (error == 0) { /* while matches found */
 /* substring found between pm.rm_so and pm.rm_eo */
 /* This call to regexec(\|) finds the next match */
 error = regexec (&re, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL);
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

CSI Enabled

Interface Stability Standard

MT-Level MT-Safe with exceptions

fnmatch(3C), glob(3C), malloc(3C), setlocale(3C), attributes(5), standards(5), regex(5)

The regcomp() function can be used safely in a multithreaded application as long as setlocale(3C) is not being called to change the locale.