regexec - Execute Compiled Regular Expression

Syntax

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

regexec compares the null-terminated string against the compiled regular expression preg to find a match between the two. (Regular expressions are described in "Regular Expressions" in the VisualAge C++ Programming Guide.)

nmatch is the number of substrings in string that regexec should try to match with subexpressions in preg. The array you supply for pmatch must have at least nmatch elements.

regexec fills in the elements of the array pmatch with offsets of the substrings in string that correspond to the parenthesized subexpressions of the original pattern given to regcomp to create preg. The zeroth element of the array corresponds to the entire pattern. If there are more than nmatch subexpressions, only the first nmatch - 1 are stored. If nmatch is 0, or if the REG_NOSUB flag was set when preg was created with regcomp, regexec ignores the pmatch argument.

The eflags flag defines customizable behavior of regexec:

REG_NOTBOL

string

When a basic or extended regular expression is matched, any given parenthesized subexpression of the original pattern could participate in the match of several different substrings of string. The following rules determine which substrings are reported in pmatch.:

If a subexpression participated in a match several times, regexec stores the offset of the last matching substring in pmatch.
If a subexpression did not match in the source string, regexec sets the offset shown in pmatch to -1.
If a subexpression contains subexpressions, the data in pmatch refers to the last such subexpression.
If a subexpression matches a zero-length string, the offsets in pmatch refer to the byte immediately following the matching string.

If the REG_NOSUB flag was set when preg was created by regcomp, the contents of pmatch are unspecified. If the REG_NEWLINE flag was not set when preg was created, new-line characters are allowed in string.

If a match is found, regexec returns 0. Otherwise, it returns a nonzero value indicating either no match or an error.

This example compiles an expression and matches a string against it. The first substring uses the full pattern. The second substring uses the sub-expression inside the full pattern.

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

int main(void)
{
   regex_t    preg;
   char       *string = "a very simple simple simple string";
   char       *pattern = "\\(sim[a-z]le\\) \\1";
   int        rc;
   size_t     nmatch = 2;
   regmatch_t pmatch[2];

   if (0 != (rc = regcomp(&preg, pattern, 0))) {
      printf("regcomp() failed, returning nonzero (%d)\n", rc);
      exit(EXIT_FAILURE);
   }

   if (0 != (rc = regexec(&preg, string, nmatch, pmatch, 0))) {
      printf("Failed to match '%s' with '%s',returning %d.\n",
      string, pattern, rc);
   }
   else {
      printf("With the whole expression, "
             "a matched substring \"%.*s\" is found at position %d to %d.\n",
             pmatch[0].rm_eo - pmatch[0].rm_so, &string[pmatch[0].rm_so],
             pmatch[0].rm_so, pmatch[0].rm_eo - 1);
      printf("With the sub-expression, "
             "a matched substring \"%.*s\" is found at position %d to %d.\n",
             pmatch[1].rm_eo - pmatch[1].rm_so, &string[pmatch[1].rm_so],
             pmatch[1].rm_so, pmatch[1].rm_eo - 1);
   }
   regfree(&preg);
   return 0;

   /****************************************************************************
      The output should be similar to :

      With the whole expression, a matched substring "simple simple" is found
      at position 7 to 19.
      With the sub-expression, a matched substring "simple" is found
      at position 7 to 12.
   ****************************************************************************/
}

[Back: regerror - Return Error Message for Regular Expression]

[Next: regfree - Free Memory for Regular Expression]