regexec() — Execute compiled regular expression

Standards

Standards / Extensions C or C++ Dependencies

XPG4
XPG4.2

 both  

Format

#include <regex.h>

int regexec(const regex_t *preg, const char *string,
            size_t nmatch, regmatch_t *pmatch, int eflags);
XPG4 
#define _XOPEN_SOURCE
#include <regex.h>

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

General description

Compares the NULL-terminated string specified by string against the compiled regular expression, preg. (For a description of regular expressions, see Regular expressions.)

preg is a pointer to a compiled regular expression to compare against STRING.

string is a pointer to a string to be matched.

nmatch is the number of sub-expressions to match.

pmatch is an array of offsets into STRING which matched the corresponding sub-expressions in preg.

eflags is a bit flag defining customizable behavior of regexec().
REG_NOTBOL
Indicates that the first character of STRING is not the beginning of the line.
REG_NOTEOL
Indicates that the first character of STRING is not the end of the line.

If nmatch parameter is 0 or REG_NOSUB was set on the call to regcomp(), regexec() ignores the pmatch argument. Otherwise, the pmatch argument points to an array of at least nmatch elements. The regexec() function fills in the elements of the array with offsets of the substrings of STRING that correspond to the parenthesized sub-expressions of the original pattern specified to regcomp(). The 0th element of the array corresponds to the entire pattern. If there are more than nmatch sub-expressions, only the first nmatch-1 are recorded.

When matching a basic or extended regular expression, any given parenthesized sub-expression of pattern might participate in the match of several different substrings of STRING. The following rules determine which substrings are reported in pmatch.
  1. If a sub-expression participated in a match several times, the offset of the last matching substring is reported in pmatch.
  2. If a sub-expression did not match in the source STRING, the offset shown in pmatch is set to -1.
  3. If a sub-expression contains sub-expressions, the data in pmatch refers to the last such sub-expression.
  4. If a sub-expression matches a zero-length string, the offsets in pmatch refer to the byte immediately following the matching string.

If EREG_NOSUB was set when regcomp() was called, the contents of pmatch are unspecified.

If REG_NEWLINE was set when regcomp() was called, newline characters are allowed in STRING.

Notes:
  1. With z/OS® XL C/C++, the string passed to the regexec() function is assumed to be in the initial shift state, unless REG_NOTBOL is specified. If REG_NOTBOL is specified, the shift state used is the shift state after the last call to the regexec() function.
  2. The information returned by the regexec() function in the regmatch_t structure has the shift-state at the start and end of the string added. This will assist an application to perform replacements or processing of the partial string. To perform replacements, the application must add the required shift-out and shift-in characters where necessary. No library functions are available to assist the application.
  3. If MB_CUR_MAX is specified as 4, but the charmap file does not specify the DBCS characters, and a collating-element (for example, [:a:]) is specified in the pattern, the DBCS characters will not match against the collating-element even if they have an equivalent weight to the collating-element.

Returned value

If a match is found, regexec() returns 0.

If unsuccessful, regexec() returns nonzero indicating either no match or an error.

Example

CELEBR09 
⁄* CELEBR09                                      

   This example compiles an extended regular expression, and                    
   match against a string.                                                      
                                                                                
 *⁄                                                                             
#include <regex.h>                                                              
#include <locale.h>                                                             
#include <stdio.h>                                                              
#include <stdlib.h>                                                             
                                                                                
main() {                                                                        
    regex_t    preg;                                                            
    char       *string = "a simple string";                                     
    char       *pattern = ".*(simple).*";                                       
    int        rc;                                                              
    size_t     nmatch = 2;                                                      
    regmatch_t pmatch[2];                                                       
                                                                                
    if ((rc = regcomp(&preg, pattern, REG_EXTENDED)) != 0) {                    
       printf("regcomp() failed, returning nonzero (%d)\n", rc);                
       exit(1);                                                                 
    }                                                                           
                                                                                
    if ((rc = regexec(&preg, string, nmatch, pmatch, 0)) != 0) {                
       printf("failed to ERE match '%s' with '%s',returning %d.\n",             
       string, pattern, rc);                                                    
    }                                                                           
                                                                                
    regfree(&preg);                                                             
}

Related information

Parent topic: Library functions