regerror

Syntax

#include <sys/types.h> #include <regex.h> size_t regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size);

Description

regerror maps a non-zero value of errcode from either regcomp (Return Value, see section regcomp) or regexec (Return Value, see section regexec) to a human-readable, printable message.

If preg is non-NULL, the error code should have arisen from use of the variable of the type regex_t pointed to by preg, and if the error code came from regcomp, it should have been the result from the most recent regcomp using that regex_t variable. (regerror may be able to supply a more detailed message using information from the regex_t than from errcode alone.) regerror places the NUL-terminated message into the buffer pointed to by errbuf, limiting the length (including the NUL) to at most errbuf_size bytes. If the whole message won't fit, as much of it as will fit before the terminating NUL is supplied. In any case, the returned value is the size of buffer needed to hold the whole message (including terminating NUL). If errbuf_size is 0, errbuf is ignored but the return value is still correct.

If the errcode given to regerror is first ORed with REG_ITOA, the "message" that results is the printable name of the error code, e.g. "REG_NOMATCH", rather than an explanation thereof. If errcode is REG_ATOI, then preg shall be non-NULL and the re_endp member of the structure it points to must point to the printable name of an error code (e.g. "REG_ECOLLATE"); in this case, the result in errbuf is the decimal representation of the numeric value of the error code (0 if the name is not recognized). REG_ITOA and REG_ATOI are intended primarily as debugging facilities; they are extensions, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. Be warned also that they are considered experimental and changes are possible.

Return Value

The size of buffer needed to hold the message (including terminating NUL) is always returned, even if errbuf_size is zero.

Portability

ANSI/ISO C	No
POSIX	1003.2-1992; 1003.1-2001