regerror Subroutine

Purpose

Returns a string that describes the ErrCode parameter.

Library

Standard C Library (libc. a)

Syntax

#include <regex.h>

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

Description

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

Item Description
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.

Item Description
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.