Technical Reference: Base Operating System and Extensions , Volume 2

regerror Subroutine

Purpose

Returns a string that describes the ErrCode parameter.

Syntax

#include <regex.h>

size_t regerror (ErrCode, Preg, ErrBuf, ErrBuf_Size) int ErrCode; const regex_t * Preg; char * ErrBuf; size_t ErrBuf_Size;

The regerror subroutine provides a mapping from error codes returned by the regcomp and regexec subroutines to printable strings. It generates a string corresponding to the value of the ErrCode parameter, which is the last nonzero value returned by the regcomp or regexec subroutine with the given value of the Preg parameter. If the ErrCode parameter is not such a value, the content of the generated string is unspecified. The string generated is obtained from the regex.cat message catalog.

If the ErrBuf_Size parameter is not 0, the regerror subroutine places the generated string into the buffer specifier by the ErrBuf parameter, whose size in bytes is specified by the ErrBuf_Size parameter. If the string (including the terminating null character) cannot fit in the buffer, the regerror subroutine truncates the string and null terminates the result.

Parameters

ErrCode	Specifies the error for which a description string is to be returned.
Preg	Specifies the structure that holds the previously compiled output of the regcomp subroutine.
ErrBuf	Specifies the buffer to receive the string generated by the regerror subroutine.
ErrBuf_Size	Specifies the size of the ErrBuf parameter.

Return Values

The regerror subroutine returns the size of the buffer needed to hold the entire generated string, including the null termination. If the return value is greater than the value of the ErrBuf_Size variable, the string returned in the ErrBuf buffer is truncated.

Error Codes

If the ErrBuf_Size value is 0, the regerror subroutine ignores the ErrBuf parameter, but returns the one of the following error codes. These error codes defined in the regex.h file.

REG_NOMATCH	Indicates the basic or extended regular expression was unable to find a match.
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.
REG_ENEWLINE	Indicates a new-line character was found before the end of the regular or extended regular expression, and REG_NEWLINE was not set.

If the Preg parameter passed to the regexec subroutine is not a compiled basic or extended regular expression returned by the regcomp subroutine, the result is undefined.

Examples

An application can use the regerror subroutine (with the parameters (Code, Preg, null, (size_t) 0) passed to it) to determine the size of buffer needed for the generated string, call the malloc subroutine to allocate a buffer to hold the string, and then call the regerror subroutine again to get the string. Alternately, this subroutine can allocate a fixed, static buffer that is large enough to hold most strings (perhaps 128 bytes), and then call the malloc subroutine to allocate a larger buffer if necessary.

Implementation Specifics

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

Related Information

The regcomp (regcomp 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.