regcomp(3)						     Library Functions Manual							regcomp(3)

NAME

       regcomp, regerror, regexec, regfree - Compares string to regular expression

LIBRARY

       Standard C Library (libc.so, libc.a)

SYNOPSIS

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

       int regcomp(	 regex_t *preg,      const char *pattern,      int cflags);

       size_t regerror(      int errcode,      const regex_t *preg,	 char *errbuf,	    size_t errbuf_size);

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

       void regfree(	  regex_t *preg);

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       regcomp(), regexec(), regerror(), regfree():  POSIX.2, XPG4, XPG4-UNIX

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Specifies  the  flags  for  regcomp().  The  cflags parameter is the bitwise inclusive OR of zero or more of the following flags, which are
       defined in the /usr/include/regex.h file.  Uses extended regular expressions.  Ignores case in match.  Reports only success or  failure	in
       regexec();  does  not  report  subexpressions.  Treats newline as a special character marking the end and beginning of lines.  Contains the
       basic or extended regular expression to be compiled by regcomp().  The structure that contains  the  compiled  basic  or  extended  regular
       expression.   Identifies  the error code.  Points to the buffer where regerror() stores the message text.  Specifies the size of the errbuf
       buffer.	Contains the data to be matched.  Contains the number of subexpressions to match.  Contains the array of offsets into  the  string
       parameter  that	match the corresponding subexpression in the preg parameter.  Specifies the flags controlling the customizable behavior of
       the regexec function.  The eflags parameter modifies the interpretation of the contents of the string parameter.  The value for this param-
       eter  is  formed  by  bitwise inclusive ORing zero or more of the following flags, which are defined in the /usr/include/regex.h file.  The
       first character of the string pointed to by the string parameter is not the beginning of the line. Therefore, the  circumflex  character  ^
       (circumflex),  when  taken  as a special character, does not match the beginning of the string parameter.  The last character of the string
       pointed to by the string parameter is not the end of the line. Therefore, the $ (dollar sign), when taken as a special character, does  not
       match the end of the string parameter.

DESCRIPTION

       The  regcomp(), regerror(), regexec(), and regfree() functions perform regular expression matching. The regcomp() function compiles a regu-
       lar expression and the regexec() function compares the compiled regular expression to a string.	The regerror() function returns text asso-
       ciated  with  an error condition encountered by regcomp() or regexec(). The regfree() function frees the internal storage allocated for the
       compiled regular expression.

       The regcomp() function compiles the basic or extended regular expression specified by the pattern parameter and places the  output  in  the
       preg  structure.   The  default regular expression type for the pattern parameter is a basic regular expression. An application can specify
       extended regular expressions with the REG_EXTENDED flag.

       If the REG_NOSUB flag is not set in cflags, the regcomp() function sets the number of parenthetic subexpressions (delimited by ( and ) in
       basic regular expressions or by () in extended regular expressions) to the number found in pattern.

       The  regexec()  function compares the null-terminated string in the string parameter against the compiled basic or extended regular expres-
       sion in the preg parameter.  If a match is found, the regexec() function returns a value  of  0	(zero).  The  regexec()  function  returns
       REG_NOMATCH if there is no match.  Any other nonzero value returned indicates an error.

       If  the	value  of  the	nmatch parameter is 0 (zero) or if the REG_NOSUB flag was set on the call to the regcomp() function, the regexec()
       function ignores the pmatch parameter. Otherwise, the pmatch parameter points to an array of at least the number of elements  specified	by
       the nmatch parameter. The regexec() function fills in the elements of the array pointed to by the pmatch parameter with offsets of the sub-
       strings of the string parameter.  The elements of the pmatch array correspond to the parenthetic subexpressions	of  the  original  pattern
       parameter that was specified to the regcomp() function. The pmatch[i].rm_so structure is the byte offset of the beginning of the substring,
       and the pmatch[i].rm_eo structure is one greater than the byte offset of the end of the substring.   Subexpression  i  begins  at  the  ith
       matched	open  parenthesis,  counting from 1.  The 0 (zero) element of the array corresponds to the entire pattern.  Unused elements of the
       pmatch parameter, up to the value pmatch[nmatch-1], are filled with -1.	If the number of subexpressions exceeds the  number  specified	by
       the nmatch parameter (the pattern parameter itself counts as a subexpression), only the first nmatch-1 are recorded.

       When  matching  a basic or extended regular expression, any given parenthetic subexpression of the pattern parameter can participate in the
       match of several different substrings of the string parameter; however, it may not match any substring even though the pattern as  a  whole
       did match.  The following rules are used to determine which substrings to report in the pmatch parameter when matching regular expressions:
       If a subexpression in a regular expression participated in the match several times, the offset of the last matching substring  is  reported
       in  the pmatch parameter.  If a subexpression did not participate in a match, the byte offset in the pmatch parameter is a value of -1.	If
       a subexpression is contained in a subexpression, the data in the pmatch parameter refers to the last such subexpression.  If  a	subexpres-
       sion  is contained in a subexpression and the byte offsets in the pmatch parameter have a value of -1, the pointers in the pmatch parameter
       also have a value of -1.  If a subexpression matched a zero-length string, the offsets in the pmatch parameter refer to	the  byte  immedi-
       ately following the matching string.

       If  the	REG_NOSUB  flag  was  set in the cflags parameter in the call to the regcomp() function and the nmatch parameter is not equal to 0
       (zero) in the call to the regexec function, the content of the pmatch array is unspecified.

       If the REG_NEWLINE flag was not set in the cflags parameter when the regcomp() function was called, a newline character in the  pattern	or
       string  parameter  is treated as an ordinary character. If the REG_NEWLINE flag was set when the regcomp() function was called, the newline
       character is treated as an ordinary character, except as follows: A newline character in the string parameter is not matched by a  .  (dot)
       outside	of  a  bracket	expression  or by any form of a nonmatching list.  A ^ (circumflex) in the pattern parameter, when used to specify
       expression anchoring, matches the zero-length string immediately after a newline character in the string parameter, regardless of the  set-
       ting  of  the  REG_NOTBOL  flag.   A $ (dollar sign) in the pattern parameter, when used to specify expression anchoring, matches the zero-
       length string immediately before a newline character in the string parameter, regardless of the setting of the REG_NOTEOL flag.

       The regerror() function returns the text associated with the specified error code. If the regcomp() or regexec() function fails, it returns
       a nonzero error code. If this return value is assigned to the errcode parameter, the regerror() function returns the text of the associated
       message.

       If the errbuf_size parameter is not 0, regerror() places the generated string into the buffer size errbuf_size bytes pointed to by  errbuf.
       If the string (including the terminating null) cannot fit in the buffer, regerror() truncates the string and null-terminates the result.

       If errbuf_size is 0, regerror() ignores the errbuf parameter and returns the size of the buffer needed to hold the generated string.

       The  regfree()  function  frees any memory allocated by the regcomp() function associated with the preg parameter. An expression defined by
       the preg parameter is no longer treated as a compiled basic or extended regular expression after it is given to the regfree() function.

EXAMPLES

       The following example demonstrates how the REG_NOTBOL flag can be used with the regexec() function to find all substrings in  a	line  that
       match a pattern supplied by a user. The main() function in the example accepts two input strings from the user. The match() function in the
       example uses regcomp() and regexec() to search for matches.

       #include <sys/types.h> #include <regex.h> #include  <locale.h>  #include  <stdio.h>  #include  <string.h>  #include  <nl_types.h>  #include
       "reg_example.h" #define SLENGTH 128

       main() {
	   char    patt[SLENGTH], strng[SLENGTH];
	   char    *eol;
	   nl_catd catd;

	   (void)setlocale(LC_ALL, "");
	   catd = catopen("reg_example.cat", NL_CAT_LOCALE);

	   printf(catgets(catd,SET1,INPUT,
		  "Enter a regular expression:"));
	   fgets(patt, SLENGTH, stdin);
	   if ((eol = strchr(patt, '
')) != NULL)
	       *eol = '';  /* Replace newline with null */
	   else
	       return;	/* Line entered too long */
	   printf(catgets(catd,SET1,COMPARE,
		  "Enter string to compare
String: "));
	   fgets(strng, SLENGTH, stdin);
	   if ((eol = strchr(strng, '
')) != NULL)
	       *eol = '';  /* Replace newline with null */
	   else
	       return;	/* Line entered too long */

	   match(patt, strng); }

       int    match(char *pattern, char *string) {
	   char    message[SLENGTH];
	   char    *start_search;
	   int	  error, msize, count;
	   regex_t preg;
	   regmatch_t pmatch;

	   error = regcomp(&preg, pattern,
		   REG_ICASE | REG_EXTENDED);
	   if (error) {
	       msize = regerror(error, &preg, message, SLENGTH);
	       printf("%s
", message);
	       if (msize > SLENGTH)
		   printf(catgets(catd,SET1,LOST,"Additional text lost
"));
	       return;
	   }
	   error = regexec(&preg, string, 1, &pmatch, 0);
	   if (error == REG_NOMATCH) {
	       printf(catgets(catd,SET1,NO_MATCH,
		      "No matches in string
"));
	       return;
	   } else if (error != 0) {
	       msize = regerror(error, &preg, message, SLENGTH);
	       printf("%s
", message);
	       if (msize > SLENGTH)
		   printf(catgets(catd,SET1,LOST,
			  "Additional text lost
"));
	       return;
	   };
	   count = 1;
	   start_search = string + pmatch.rm_eo;
	   while (error == 0) {
	       error =
		   regexec(&preg, start_search, 1, &pmatch,
		   REG_NOTBOL);
	       start_search = start_search + pmatch.rm_eo;
	       count++;
	   };
	   count--;
	   printf(catgets(catd,SET1,MATCH,
		  "There are %i matches
"), count);
	   regfree(&preg);
	   catclose(catd); }

       The  following  example	finds  out  which  subexpressions in the regular expression have matches in the string. This example uses the same
       main() program as the preceding example. This example does not specify REG_EXTENDED in the call to regcomp() and, consequently, uses  basic
       regular expressions, not extended regular expressions.

       #define MAX_MATCH 10 int    match(char *pattern, char *string) {
	   char    message[SLENGTH];
	   char    *start_search;
	   int	  error, msize, count, matches_tocheck;
	   regex_t preg;
	   regmatch_t pmatch[MAX_MATCH];

	   error = regcomp(&preg, pattern, REG_ICASE);
	   if (error) {
	       msize = regerror(error, &preg, message, SLENGTH);
	       printf("regcomp: %s
", message);
	       if (msize > SLENGTH)
		   printf(catgets(catd,SET1,LOST,
			  "Additional text lost
"));
	       return;
	   }

	   if (preg.re_nsub > MAX_MATCH) {
	       printf(catgets(catd,SET1,SUBEXPR,
		   "There are %1$i subexpressions, checking %2$i
"),
		    preg.re_nsub, MAX_MATCH);
	       matches_tocheck = MAX_MATCH;
	   } else {
	       printf(catgets(catd,SET1,SUB_EXPR_NUM,
		   "There are %i subexpressions in the regular expression
"),
		    preg.re_nsub);
	       matches_tocheck = preg.re_nsub;
	   }
	   error = regexec(&preg, string, MAX_MATCH, &pmatch[0], 0);
	   if (error == REG_NOMATCH) {
	       printf(catgets(catd,SET1,NO_MATCH_ENT,
		   "String did not contain match for entire regular expression
"));
	       return;
	   } else if (error != 0) {
	       msize = regerror(error, &preg, message, SLENGTH);
	       printf("regexe: %s
", message);
	       if (msize > SLENGTH)
		   printf(catgets(catd,SET1,LOST,
			  "Additional text lost
"));
	       return;
	   } else
	       printf(catgets(catd,SET1,MATCH_ENT,
		   "String contained match for the entire regular expression
"));
	   for (count = 0; count <= matches_tocheck; count++) {
	       if (pmatch[count].rm_so != -1) {
		   printf(catgets(catd,SET1,SUB_EXPR_MATCH
		     "Subexpression %i matched in string
"),count);
		   printf(catgets(catd,SET1,MATCH_WHERE,
			  "Match starts at %1$i. Byte after match is %2$i
"),
			   pmatch[count].rm_so, pmatch[count].rm_eo);
	       } else
		   printf(catgets(catd,SET1,NO_MATCH_SUB,
			  "Subexpression %i had NO match
"), count);
	   }
	   regfree(&preg);
	   catclose(catd); }

RETURN VALUES

       Upon  successful  completion, the regcomp() function returns a value of 0 (zero).  Otherwise, regcomp() returns an integer value indicating
       an error as described below, and the contents of the preg parameter is undefined.  If the regcomp() function detects an	illegal  basic	or
       extended regular expression, it returns REG_BADPAT or an error code that more precisely describes the error.

       If  the regexec() function finds a match, the function returns a value of 0 (zero).  Otherwise, it returns REG_NOMATCH to indicate no match
       or REG_NOSYS to indicate that the function is not supported.

       Upon successful completion, the regerror() function returns the number of bytes needed to hold the entire generated string. This value  may
       be greater than the value of the errbuf_size  parameter. If regerror fails, it returns 0 (zero) to indicate that the function is not imple-
       mented.

       The regfree() function returns no value.

       The following constants are defined as error return values: The contents within the pair { and } are invalid: not a  number,  number  too
       large, more than two numbers, or first number larger than second.  The pattern contains an invalid regular expression.  The ?, *, or + sym-
       bols are not preceded by a valid regular expression.  The use of a pair of { and } or {} is unbalanced.  The use of [] is unbalanced.	An
       invalid	collating element was referenced.  An invalid character class type was referenced.  The pattern contains a trailing  (backslash).
       The function is unsupported.  The use of a pair of ( and ) or () is unbalanced.  An endpoint in the range expression is invalid.   Insuf-
       ficient memory space is available.  The number in digit is invalid or in error.  The pattern contains too many parenthetic subexpressions.
       The regexec() function did not find a match.

ERRORS

       These functions do not set errno to indicate an error.

RELATED INFORMATION

       Commands: grep(1)

       Standards: standards(5) delim off

																	regcomp(3)