--- name: "regexec" section: "3" platform: "linux" package: "man-pages" version: "6.19-1" release: "Arch Linux 2026-11-01" platforms: ["linux", "freebsd"] url: "https://new.carta.tech/regex" --- # regexec(3) POSIX regex functions Part of [regex(3)](/regex/3.md). ## NAME regcomp, regexec, regerror, regfree - POSIX regex functions ## LIBRARY Standard C library (*libc*, *-lc*) ## SYNOPSIS ``` #include ``` **int regcomp(regex\_t \*restrict** *preg***, const char \*restrict** *regex***,** **int** *cflags***);** **int regexec(const regex\_t \*restrict** *preg***,** **const char \*restrict** *string***,** **size\_t** *n***, regmatch\_t** *pmatch***\[\_Nullable restrict** *n***\],** **int** *eflags***);** **size\_t regerror(**size\_t errbuf\_size; **int** *errcode***, const regex\_t \*\_Nullable restrict** *preg***,** **char** *errbuf***\[\_Nullable restrict** *errbuf\_size***\],** **size\_t** *errbuf\_size***);** **void regfree(regex\_t \****preg***);** **typedef struct {** **size\_t re\_nsub;** **} regex\_t;** **typedef struct {** **regoff\_t rm\_so;** **regoff\_t rm\_eo;** **} regmatch\_t;** **typedef** /\* ... \*/ **regoff\_t;** ## DESCRIPTION ### Compilation **regcomp**() is used to compile a regular expression into a form that is suitable for subsequent **regexec**() searches. On success, the pattern buffer at *\*preg* is initialized. *regex* is a null-terminated string. The locale must be the same when running **regexec**(). After **regcomp**() succeeds, *preg-\>re\_nsub* holds the number of subexpressions in *regex*. Thus, a value of *preg-\>re\_nsub* + 1 passed as *n* to **regexec**() is sufficient to capture all matches. *cflags* is the bitwise OR of zero or more of the following: - **REG\_EXTENDED** Use POSIX Extended Regular Expression syntax when interpreting *regex*. If not set, POSIX Basic Regular Expression syntax is used. - **REG\_ICASE** Do not differentiate case. Subsequent **regexec**() searches using this pattern buffer will be case insensitive. - **REG\_NOSUB** Report only overall success. **regexec**() will use only *pmatch* for **REG\_STARTEND**, ignoring *n*. - **REG\_NEWLINE** Match-any-character operators don't match a newline. - A nonmatching list (**\[^...\]**) not containing a newline does not match a newline. - Match-beginning-of-line operator (**^**) matches the empty string immediately after a newline, regardless of whether *eflags*, the execution flags of **regexec**(), contains **REG\_NOTBOL**. - Match-end-of-line operator (**$**) matches the empty string immediately before a newline, regardless of whether *eflags* contains **REG\_NOTEOL**. ### Matching **regexec**() is used to match a null-terminated string against the compiled pattern buffer in *\*preg*, which must have been initialised with **regcomp**(). *eflags* is the bitwise OR of zero or more of the following flags: - **REG\_NOTBOL** The match-beginning-of-line operator always fails to match (but see the compilation flag **REG\_NEWLINE** above). This flag may be used when different portions of a string are passed to **regexec**() and the beginning of the string should not be interpreted as the beginning of the line. - **REG\_NOTEOL** The match-end-of-line operator always fails to match (but see the compilation flag **REG\_NEWLINE** above). - **REG\_STARTEND** Match \[*string + pmatch\[0\].rm\_so*, *string + pmatch\[0\].rm\_eo*) instead of \[*string*, *strnul(string)*). This allows matching embedded NUL bytes. If any matches are returned (**REG\_NOSUB** wasn't passed to **regcomp**(), the match succeeded, and *n* \> 0), they overwrite *pmatch* as usual, and the match offsets remain relative to *string* (not *string + pmatch\[0\].rm\_so*). This flag is a BSD extension, not present in POSIX. ### Match offsets Unless **REG\_NOSUB** was passed to **regcomp**(), it is possible to obtain the locations of matches within *string*: **regexec**() fills *n* elements of *pmatch* with results: *pmatch\[0\]* corresponds to the entire match, *pmatch\[1\]* to the first subexpression, etc. If there were more matches than *n*, they are discarded; if fewer, unused elements of *pmatch* are filled with **-1**s. Each returned valid (non-**-1**) match corresponds to the range \[*string + rm\_so*, *string + rm\_eo*). *regoff\_t* is a signed integer type capable of storing the largest value that can be stored in either an *ptrdiff\_t* type or a *ssize\_t* type. ### Error reporting **regerror**() is used to turn the error codes that can be returned by both **regcomp**() and **regexec**() into error message strings. If *preg* isn't a null pointer, *errcode* must be the latest error returned from an operation on *preg*. If *errbuf\_size* isn't 0, up to *errbuf\_size* bytes are copied to *errbuf*; the error string is always null-terminated, and truncated to fit. ### Freeing **regfree**() deinitializes the pattern buffer at *\*preg*, freeing any associated memory; *\*preg* must have been initialized via **regcomp**(). ## RETURN VALUE **regcomp**() returns zero for a successful compilation or an error code for failure. **regexec**() returns zero for a successful match or **REG\_NOMATCH** for failure. **regerror**() returns the size of the buffer required to hold the string. ## ERRORS The following errors can be returned by **regcomp**(): - **REG\_BADBR** Invalid use of back reference operator. - **REG\_BADPAT** Invalid use of pattern operators such as group or list. - **REG\_BADRPT** Invalid use of repetition operators such as using '\*' as the first character. - **REG\_EBRACE** Un-matched brace interval operators. - **REG\_EBRACK** Un-matched bracket list operators. - **REG\_ECOLLATE** Invalid collating element. - **REG\_ECTYPE** Unknown character class name. - **REG\_EEND** Nonspecific error. This is not defined by POSIX. - **REG\_EESCAPE** Trailing backslash. - **REG\_EPAREN** Un-matched parenthesis group operators. - **REG\_ERANGE** Invalid use of the range operator; for example, the ending point of the range occurs prior to the starting point. - **REG\_ESIZE** Compiled regular expression requires a pattern buffer larger than 64 kB. This is not defined by POSIX. - **REG\_ESPACE** The regex routines ran out of memory. - **REG\_ESUBREG** Invalid back reference to a subexpression. ## ATTRIBUTES For an explanation of the terms used in this section, see [**attributes**(7)](/attributes/7.md). | | | | | --- | --- | --- | | **Interface** | **Attribute** | **Value** | | **regcomp**(), **regexec**() | Thread safety | MT-Safe locale | | **regerror**() | Thread safety | MT-Safe env | | **regfree**() | Thread safety | MT-Safe | ## STANDARDS POSIX.1-2008. ## HISTORY POSIX.1-2001. Prior to POSIX.1-2008, *regoff\_t* was required to be capable of storing the largest value that can be stored in either an *off\_t* type or a *ssize\_t* type. ## CAVEATS *re\_nsub* is only required to be initialized if **REG\_NOSUB** wasn't specified, but all known implementations initialize it regardless. Both *regex\_t* and *regmatch\_t* may (and do) have more members, in any order. Always reference them by name. ## EXAMPLES ``` #include #include #include #include #include static const char *const str = "1) John Driverhacker;\n2) John Doe;\n3) John Foo;\n"; static const char *const re = "John.*o"; int main(void) { static const char *s = str; regex_t regex; regmatch_t pmatch[1]; regoff_t off, len; if (regcomp(®ex, re, REG_NEWLINE)) exit(EXIT_FAILURE); printf("String = \"%s\"\n", str); printf("Matches:\n"); for (unsigned int i = 0; ; i++) { if (regexec(®ex, s, countof(pmatch), pmatch, 0)) break; off = pmatch[0].rm_so + (s - str); len = pmatch[0].rm_eo - pmatch[0].rm_so; printf("#%u:\n", i); printf("offset = %jd; length = %jd\n", (intmax_t) off, (intmax_t) len); printf("substring = \"%.*s\"\n", len, s + pmatch[0].rm_so); s += pmatch[0].rm_eo; } exit(EXIT_SUCCESS); } ``` ## SEE ALSO [**grep**(1)](/grep/1.md), [**regex**(7)](/regex/7.md) The glibc manual section, *Regular Expressions*