regerror Subroutine

Purpose

Returns a string that describes the ErrCode parameter.

Library

Standard C Library (libc. a)

Syntax

include <regex.h>

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

Description

The regerror subroutine provides a mapping from error codes that are 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 that is 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 that is 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

Table 1. 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 that is 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 that is 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.

Table 2. Error Codes
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 a 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 that 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 that is 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 that is 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.