[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2


regcomp Subroutine

Purpose

Compiles a specified basic or extended regular expression into an executable string.

Library

Standard C Library (libc. a)

Syntax

#include <regex.h>


int regcomp ( Preg Pattern CFlags)
const char *Preg;
const char *Pattern;
int CFlags;

Description

The regcomp subroutine compiles the basic or extended regular expression specified by the Pattern parameter and places the output in the structure pointed to by the Preg parameter.

Parameters


Preg Specifies the structure to receive the compiled output of the regcomp subroutine.
Pattern Contains the basic or extended regular expression to be compiled by the regcomp subroutine.

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.

CFlags Contains the bitwise inclusive OR of 0 or more flags for the regcomp subroutine. These flags are defined in the regex.h file:

REG_EXTENDED
Uses extended regular expressions.

REG_ICASE
Ignores case in match.

REG_NOSUB
Reports only success or failure in the regexec subroutine. If this flag is not set, the regcomp subroutine sets the re_nsub structure to the number of parenthetic expressions found in the Pattern parameter.

REG_NEWLINE
Prohibits . (period) and nonmatching bracket expression from matching a new-line character. The ^ (circumflex) and $ (dollar sign) will match the zero-length string immediately following or preceding a new-line character.

Return Values

If successful, the regcomp subroutine returns a value of 0. Otherwise, it returns another value indicating the type of failure, and the content of the Preg parameter is undefined.

Error Codes

The following macro names for error codes may be written to the errno global variable under error conditions:

REG_BADPAT Indicates a basic or extended regular expression that is not valid.
REG_ECOLLATE Indicates a collating element referenced that is not valid.
REG_ECTYPE Indicates a character class-type reference that is not valid.
REG_EESCAPE Indicates a trailing \ in pattern.
REG_ESUBREG Indicates a number in \digit is not valid or in error.
REG_EBRACK Indicates a [] imbalance.
REG_EPAREN Indicates a \(\) or () imbalance.
REG_EBRACE Indicates a \{\} imbalance.
REG_BADBR Indicates the content of \{\} is unusable: not a number, number too large, more than two numbers, or first number larger than second.
REG_ERANGE Indicates an unusable end point in range expression.
REG_ESPACE Indicates out of memory.
REG_BADRPT Indicates a ? (question mark), * (asterisk), or + (plus sign) not preceded by valid basic or extended regular expression.

If the regcomp subroutine detects an illegal basic or extended regular expression, it can return either the REG_BADPAT error code or another that more precisely describes the error.

Examples

The following example illustrates how to match a string (specified in the string parameter) against an extended regular expression (specified in the Pattern parameter):

#include <sys/types.h>
#include <regex.h>
int
match(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);
}

In the preceding example, errors are treated as no match. When there is no match or error, the calling process can get details by calling the regerror subroutine.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The regerror (regerror Subroutine) subroutine, regexec (regexec Subroutine) subroutine, regfree (regfree Subroutine) subroutine.

Subroutines Overview and Understanding Internationalized Regular Expression Subroutines in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]