[ Bottom of Page | Previous Page | Next Page | 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.
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.2 General Programming Concepts: Writing and Debugging Programs.
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]