# regcomp

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           regcomp, regerror, regexec, regfree — regular expression matching
    


## SYNOPSIS



           #include <regex.h>
    
           int regcomp(regex_t *restrict _preg_ , const char *restrict _pattern_ ,
               int _cflags_);
           size_t regerror(int _errcode_ , const regex_t *restrict _preg_ ,
               char *restrict _errbuf_ , size_t _errbuf_size_);
           int regexec(const regex_t *restrict _preg_ , const char *restrict _string_ ,
               size_t _nmatch_ , regmatch_t _pmatch_[restrict], int _eflags_);
           void regfree(regex_t *_preg_);
    


## DESCRIPTION



           These functions interpret _basic_ and _extended_ regular expressions
           as described in the Base Definitions volume of POSIX.1‐2017,
           _Chapter 9_ , _Regular Expressions_.
    
           The **regex_t** structure is defined in _< regex.h>_ and contains at
           least the following member:
             ┌───────────────┬──────────────┬───────────────────────────┐
             │ **Member Type** │ **Member Name** │        **Description** │
             ├───────────────┼──────────────┼───────────────────────────┤
             │ **size_t** │ _re_nsub_       │ Number of parenthesized   │
             │               │              │ subexpressions.           │
             └───────────────┴──────────────┴───────────────────────────┘
    
           The **regmatch_t** structure is defined in _< regex.h>_ and contains at
           least the following members:
             ┌───────────────┬──────────────┬───────────────────────────┐
             │ **Member Type** │ **Member Name** │        **Description** │
             ├───────────────┼──────────────┼───────────────────────────┤
             │ **regoff_t** │ _rm_so_         │ Byte offset from start of │
             │               │              │ _string_ to start of        │
             │               │              │ substring.                │
             │ **regoff_t** │ _rm_eo_         │ Byte offset from start of │
             │               │              │ _string_ of the first       │
             │               │              │ character after the end   │
             │               │              │ of substring.             │
             └───────────────┴──────────────┴───────────────────────────┘
    
           The _regcomp_() function shall 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 _< regex.h>_ header:
    
           REG_EXTENDED  Use Extended Regular Expressions.
    
           REG_ICASE     Ignore case in match (see the Base Definitions
                         volume of POSIX.1‐2017, _Chapter 9_ , _Regular_
                         _Expressions_).
    
           REG_NOSUB     Report only success/fail in _regexec_().
    
           REG_NEWLINE   Change the handling of <newline> characters, as
                         described in the text.
    
           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_() shall
           set _re_nsub_ to the number of parenthesized subexpressions
           (delimited by **"\(\)"** 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_().  If it finds a match,
           _regexec_() shall return 0; otherwise, it shall return non-zero
           indicating either no match or an error. The _eflags_ argument is the
           bitwise-inclusive OR of zero or more of the following flags, which
           are defined in the _< regex.h>_ header:
    
           REG_NOTBOL    The first character of the string pointed to by
                         _string_ is not the beginning of the line. Therefore,
                         the <circumflex> character (**'^'**), when taken as a
                         special character, shall not match the beginning of
                         _string_.
    
           REG_NOTEOL    The last character of the string pointed to by
                         _string_ is not the end of the line. Therefore, the
                         <dollar-sign> (**'$'**), when taken as a special
                         character, shall not match the end of _string_.
    
           If _nmatch_ is 0 or REG_NOSUB was set in the _cflags_ argument to
           _regcomp_(), then _regexec_() shall ignore the _pmatch_ argument.
           Otherwise, the application shall ensure that the _pmatch_ argument
           points to an array with at least _nmatch_ elements, and _regexec_()
           shall fill in the elements of that array with offsets of the
           substrings of _string_ that correspond to the parenthesized
           subexpressions of _pattern_ : _pmatch_[_i_]._rm_so_ shall be the byte
           offset of the beginning and _pmatch_[_i_]._rm_eo_ shall be one greater
           than the byte offset of the end of substring _i_.  (Subexpression _i_
           begins at the _i_ th 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] shall be filled with -1. If there are more than
           _nmatch_ subexpressions in _pattern_ (_pattern_ itself counts as a
           subexpression), then _regexec_() shall still do the match, but shall
           record only the first _nmatch_ substrings.
    
           When matching a basic or extended regular expression, any given
           parenthesized 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 shall be used to determine which substrings to
           report in _pmatch_ when matching regular expressions:
    
            1. If subexpression _i_ in a regular expression is not contained
               within another subexpression, and it participated in the match
               several times, then the byte offsets in _pmatch_[_i_] shall
               delimit the last such match.
    
            2. If subexpression _i_ is not contained within another
               subexpression, and it did not participate in an otherwise
               successful match, the byte offsets in _pmatch_[_i_] shall be -1. A
               subexpression does not participate in the match when:
    
               **'*'** or **"\{\}"** appears immediately after the subexpression in a
               basic regular expression, or **'*'** , **'?'** , or **"{}"** appears
               immediately after the subexpression in an extended regular
               expression, and the subexpression did not match (matched 0
               times)
    
               or:
    
                      **'|'** is used in an extended regular expression to select
                      this subexpression or another, and the other
                      subexpression matched.
    
            3. If subexpression _i_ is contained within another subexpression
               _j_ , and _i_ is not contained within any other subexpression that
               is contained within _j_ , and a match of subexpression _j_ is
               reported in _pmatch_[_j_], then the match or non-match of
               subexpression _i_ reported in _pmatch_[_i_] shall be as described in
               1. and 2. above, but within the substring reported in
               _pmatch_[_j_] rather than the whole string. The offsets in
               _pmatch_[_i_] are still relative to the start of _string_.
    
            4. If subexpression _i_ is contained in subexpression _j_ , and the
               byte offsets in _pmatch_[_j_] are -1, then the pointers in
               _pmatch_[_i_] shall also be -1.
    
            5. If subexpression _i_ matched a zero-length string, then both
               byte offsets in _pmatch_[_i_] shall be the byte offset of the
               character or null terminator immediately following the zero-
               length string.
    
           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> in _pattern_
           or _string_ shall be treated as an ordinary character. If
           REG_NEWLINE is set, then <newline> shall be treated as an ordinary
           character except as follows:
    
            1. A <newline> in _string_ shall not be matched by a <period>
               outside a bracket expression or by any form of a non-matching
               list (see the Base Definitions volume of POSIX.1‐2017, _Chapter_
               _9_ , _Regular Expressions_).
    
            2. A <circumflex> (**'^'**) in _pattern_ , when used to specify
               expression anchoring (see the Base Definitions volume of
               POSIX.1‐2017, _Section 9.3.8_ , _BRE Expression Anchoring_), shall
               match the zero-length string immediately after a <newline> in
               _string_ , regardless of the setting of REG_NOTBOL.
    
            3. A <dollar-sign> (**'$'**) in _pattern_ , when used to specify
               expression anchoring, shall match the zero-length string
               immediately before a <newline> in _string_ , regardless of the
               setting of REG_NOTEOL.
    
           The _regfree_() function frees any memory allocated by _regcomp_()
           associated with _preg_.
    
           The following constants are defined as the minimum set of error
           return values, although other errors listed as implementation
           extensions in _< regex.h>_ are possible:
    
           REG_BADBR     Content of **"\{\}"** invalid: not a number, number too
                         large, more than two numbers, first larger than
                         second.
    
           REG_BADPAT    Invalid regular expression.
    
           REG_BADRPT    **'?'** , **'*'** , or **'+'** not preceded by valid regular
                         expression.
    
           REG_EBRACE    **"\{\}"** imbalance.
    
           REG_EBRACK    **"[]"** imbalance.
    
           REG_ECOLLATE  Invalid collating element referenced.
    
           REG_ECTYPE    Invalid character class type referenced.
    
           REG_EESCAPE   Trailing <backslash> character in pattern.
    
           REG_EPAREN    **"\(\)"** or **"()"** imbalance.
    
           REG_ERANGE    Invalid endpoint in range expression.
    
           REG_ESPACE    Out of memory.
    
           REG_ESUBREG   Number in **"\digit"** invalid or in error.
    
           REG_NOMATCH   _regexec_() failed to match.
    
           If more than one error occurs in processing a function call, any
           one of the possible constants may be returned, as the order of
           detection is unspecified.
    
           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 the application shall ensure is the last
           non-zero value returned by _regcomp_() or _regexec_() with the given
           value of _preg_.  If _errcode_ is not such a value, the content of the
           generated string is unspecified.
    
           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_ ,
           but it might not be as detailed under some implementations.
    
           If the _errbuf_size_ argument is not 0, _regerror_() shall 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_() shall truncate the string and
           null-terminate the result.
    
           If _errbuf_size_ is 0, _regerror_() shall ignore the _errbuf_ argument,
           and return 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_().
    


## RETURN VALUE



           Upon successful completion, the _regcomp_() function shall return 0.
           Otherwise, it shall return an integer value indicating an error as
           described in _< regex.h>_, and the content of _preg_ is undefined. If a
           code is returned, the interpretation shall be as given in
           _< regex.h>_.
    
           If _regcomp_() detects an invalid RE, it may return REG_BADPAT, or
           it may return one of the error codes that more precisely describes
           the error.
    
           Upon successful completion, the _regexec_() function shall return 0.
           Otherwise, it shall return REG_NOMATCH to indicate no match.
    
           Upon successful completion, the _regerror_() function shall return
           the number of bytes needed to hold the entire generated string,
           including the null termination. If the return value is greater
           than _errbuf_size_ , the string returned in the buffer pointed to by
           _errbuf_ has been truncated.
    
           The _regfree_() function shall not return a value.
    


## ERRORS



           No errors are defined.
    
           _The following sections are informative._
    


## EXAMPLES



               #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);
               }
    


## APPLICATION USAGE



           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. Alternatively, 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.
    
           To match a pattern as described in the Shell and Utilities volume
           of POSIX.1‐2017, _Section 2.13_ , _Pattern Matching Notation_ , use the
           _fnmatch_() function.
    


## RATIONALE



           The _regexec_() function must fill in all _nmatch_ elements of _pmatch_ ,
           where _nmatch_ and _pmatch_ are supplied by the application, even if
           some elements of _pmatch_ do not correspond to subexpressions in
           _pattern_.  The application developer should note that there is
           probably no reason for using a value of _nmatch_ that is larger than
           _preg_ ->_re_nsub_ +1.
    
           The REG_NEWLINE flag supports a use of RE matching that is needed
           in some applications like text editors. In such applications, the
           user supplies an RE asking the application to find a line that
           matches the given expression. An anchor in such an RE anchors at
           the beginning or end of any line. Such an application can pass a
           sequence of <newline>-separated lines to _regexec_() as a single
           long string and specify REG_NEWLINE to _regcomp_() to get the
           desired behavior. The application must ensure that there are no
           explicit <newline> characters in _pattern_ if it wants to ensure
           that any match occurs entirely within a single line.
    
           The REG_NEWLINE flag affects the behavior of _regexec_(), but it is
           in the _cflags_ parameter to _regcomp_() to allow flexibility of
           implementation. Some implementations will want to generate the
           same compiled RE in _regcomp_() regardless of the setting of
           REG_NEWLINE and have _regexec_() handle anchors differently based on
           the setting of the flag. Other implementations will generate
           different compiled REs based on the REG_NEWLINE.
    
           The REG_ICASE flag supports the operations taken by the _grep_ **-i**
           option and the historical implementations of _ex_ and _vi_.  Including
           this flag will make it easier for application code to be written
           that does the same thing as these utilities.
    
           The substrings reported in _pmatch_[] are defined using offsets from
           the start of the string rather than pointers. This allows type-
           safe access to both constant and non-constant strings.
    
           The type **regoff_t** is used for the elements of _pmatch_[] to ensure
           that the application can represent large arrays in memory
           (important for an application conforming to the Shell and
           Utilities volume of POSIX.1‐2017).
    
           The 1992 edition of this standard required **regoff_t** to be at least
           as wide as **off_t** , to facilitate future extensions in which the
           string to be searched is taken from a file. However, these future
           extensions have not appeared.  The requirement rules out popular
           implementations with 32-bit **regoff_t** and 64-bit **off_t** , so it has
           been removed.
    
           The standard developers rejected the inclusion of a _regsub_()
           function that would be used to do substitutions for a matched RE.
           While such a routine would be useful to some applications, its
           utility would be much more limited than the matching function
           described here. Both RE parsing and substitution are possible to
           implement without support other than that required by the ISO C
           standard, but matching is much more complex than substituting. The
           only difficult part of substitution, given the information
           supplied by _regexec_(), is finding the next character in a string
           when there can be multi-byte characters. That is a much larger
           issue, and one that needs a more general solution.
    
           The _errno_ variable has not been used for error returns to avoid
           filling the _errno_ name space for this feature.
    
           The interface is defined so that the matched substrings _rm_sp_ and
           _rm_ep_ are in a separate **regmatch_t** structure instead of in
           **regex_t**.  This allows a single compiled RE to be used
           simultaneously in several contexts; in _main_() and a signal
           handler, perhaps, or in multiple threads of lightweight processes.
           (The _preg_ argument to _regexec_() is declared with type **const** , so
           the implementation is not permitted to use the structure to store
           intermediate results.) It also allows an application to request an
           arbitrary number of substrings from an RE. The number of
           subexpressions in the RE is reported in _re_nsub_ in _preg_.  With
           this change to _regexec_(), consideration was given to dropping the
           REG_NOSUB flag since the user can now specify this with a zero
           _nmatch_ argument to _regexec_().  However, keeping REG_NOSUB allows
           an implementation to use a different (perhaps more efficient)
           algorithm if it knows in _regcomp_() that no subexpressions need be
           reported. The implementation is only required to fill in _pmatch_ if
           _nmatch_ is not zero and if REG_NOSUB is not specified. Note that
           the **size_t** type, as defined in the ISO C standard, is unsigned, so
           the description of _regexec_() does not need to address negative
           values of _nmatch_.
    
           REG_NOTBOL was added to allow an application to do repeated
           searches for the same pattern in a line. If the pattern contains a
           <circumflex> character that should match the beginning of a line,
           then the pattern should only match when matched against the
           beginning of the line.  Without the REG_NOTBOL flag, the
           application could rewrite the expression for subsequent matches,
           but in the general case this would require parsing the expression.
           The need for REG_NOTEOL is not as clear; it was added for
           symmetry.
    
           The addition of the _regerror_() function addresses the historical
           need for conforming application programs to have access to error
           information more than ``Function failed to compile/match your RE
           for unknown reasons''.
    
           This interface provides for two different methods of dealing with
           error conditions. The specific error codes (REG_EBRACE, for
           example), defined in _< regex.h>_, allow an application to recover
           from an error if it is so able. Many applications, especially
           those that use patterns supplied by a user, will not try to deal
           with specific error cases, but will just use _regerror_() to obtain
           a human-readable error message to present to the user.
    
           The _regerror_() function uses a scheme similar to _confstr_() to deal
           with the problem of allocating memory to hold the generated
           string. The scheme used by _strerror_() in the ISO C standard was
           considered unacceptable since it creates difficulties for multi-
           threaded applications.
    
           The _preg_ argument is provided to _regerror_() to allow an
           implementation to generate a more descriptive message than would
           be possible with _errcode_ alone. An implementation might, for
           example, save the character offset of the offending character of
           the pattern in a field of _preg_ , and then include that in the
           generated message string. The implementation may also ignore _preg_.
    
           A REG_FILENAME flag was considered, but omitted. This flag caused
           _regexec_() to match patterns as described in the Shell and
           Utilities volume of POSIX.1‐2017, _Section 2.13_ , _Pattern Matching_
           _Notation_ instead of REs. This service is now provided by the
           _fnmatch_() function.
    
           Notice that there is a difference in philosophy between the
           ISO POSIX‐2:1993 standard and POSIX.1‐2008 in how to handle a
           ``bad'' regular expression. The ISO POSIX‐2:1993 standard says
           that many bad constructs ``produce undefined results'', or that
           ``the interpretation is undefined''. POSIX.1‐2008, however, says
           that the interpretation of such REs is unspecified. The term
           ``undefined'' means that the action by the application is an
           error, of similar severity to passing a bad pointer to a function.
    
           The _regcomp_() and _regexec_() functions are required to accept any
           null-terminated string as the _pattern_ argument. If the meaning of
           the string is ``undefined'', the behavior of the function is
           ``unspecified''. POSIX.1‐2008 does not specify how the functions
           will interpret the pattern; they might return error codes, or they
           might do pattern matching in some completely unexpected way, but
           they should not do something like abort the process.
    


## FUTURE DIRECTIONS



           None.
    


* * *