# regex

## NAME



           regcomp, regexec, regerror, regfree - POSIX regex functions
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <regex.h>**
    
           **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** _nmatch_**, regmatch_t** _pmatch_**[_Nullable restrict** _nmatch_**],**
                       **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 _nmatch_ 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 _nmatch_.
    
           **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_ , _string + strlen(string)_).  This allows
                  matching embedded NUL bytes and avoids a strlen(3) on
                  known-length strings.  If any matches are returned
                  (**REG_NOSUB** wasn't passed to **regcomp**(), the match succeeded,
                  and _nmatch_ > 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 _nmatch_
           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 _nmatch_ , 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).
           ┌───────────────────────────────┬───────────────┬────────────────┐
           │ **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.
    


## 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 <stdint.h>
           #include <stdio.h>
           #include <stdlib.h>
           #include <regex.h>
    
           #define ARRAY_SIZE(arr) (sizeof((arr)) / sizeof((arr)[0]))
    
           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(&regex, re, REG_NEWLINE))
                   exit(EXIT_FAILURE);
    
               printf("String = \"%s\"\n", str);
               printf("Matches:\n");
    
               for (unsigned int i = 0; ; i++) {
                   if (regexec(&regex, s, ARRAY_SIZE(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);
           }
    


* * *