strerror, strerror_l, strerror_r, strerror_s, strerrorlen_s - get error message string
#include <string.h> char *strerror(int errnum);
char *strerror_l(int errnum, locale_t locale);
int strerror_r(int errnum, char *strerrbuf, size_t buflen);
#define __STDC_WANT_LIB_EXT1__ 1 #include <string.h> errno_t strerror_s(char *strerrbuf, rsize_t maxsize, errno_t errnum);
size_t strerrorlen_s(errno_t errnum);
The strerror() and strerror_l() functions map the error number in errnum to a locale-dependent error message string, and return a pointer to that string. They use the same set of error messages as perror(3C).
For strerror(), the string is determined by the setting of the LC_MESSAGES category in the current locale. For strerror_l(), the string is determined by the setting of the LC_MESSAGES category in the locale specified by the locale argument. The behavior is undefined if the locale argument to strerror_l() is the special locale object LC_GLOBAL_LOCALE or is not a valid locale object handle.
The application shall not modify the string returned. The returned string pointer might be invalidated or the string content might be overwritten by a subsequent call to strerror() or strerror_l() in the same thread. The returned pointer and the string content might also be invalidated if the calling thread is terminated.
Since no return value is reserved to indicate an error of strerror() or strerror_l(), an application wishing to check for error situations should set errno to 0, then call strerror() or strerror_l(), then check errno.
The strerror_r() function maps the error number in errnum to a locale-dependent error message string determined by the setting of the LC_MESSAGES category in the current locale, and copies the string into the buffer pointed to by strerrbuf, if the string (including the null terminator), will fit in the length specified in buflen.
The strerror_s() and strerrorlen_s() functions are part of the C11 bounds checking interfaces specified in the C11 standard, Annex K.
strerror_s() provides similar functionality to the strerror_r() function, but with additional safety checks in the form of explicit runtime constraints as defined in the C11 standard. See runtime_constraint_handler(3C) and INCITS/ISO/IEC 9899:2011.
The strerrorlen_s() function returns the length (not including the null terminator) of the message string strerror_s() would return for the given errnum in the current locale.
Upon successful completion, strerror() and strerror_l() return a pointer to the generated message string. Otherwise, they set errno and return a pointer to an error message string. They return a locale-dependent version of the string “Unknown error” if errnum is not a valid error number.
Upon successful completion, strerror_r() returns 0. Otherwise it sets errno and returns the value of errno to indicate the error. It returns the string “Unknown error” in the buffer pointed to by strerrbuf if errnum is not a valid error number.
If the length of the requested string is less than maxsize, and no runtime-constraint violation is detected, the strerror_s() function returns zero. If a runtime constraint violation is detected and the handler returns, they return a non-zero value.
The strerrorlen_s() function returns the length (not including the null terminator) of the message string strerror_s() would return.
These functions may fail if:
The value of errnum is not a valid error number.
The strerror_r() function may fail if:
The buflen argument specifies insufficient storage to contain the generated message string.
Messages returned from these functions are in the native language specified by the LC_MESSAGES locale category. See setlocale(3C).
See attributes(7) for descriptions of the following attributes:
|
The strerror() and strerror_r() functions can be used safely in multithreaded applications, as long as setlocale(3C) is not being called to change the locale.
The strerror_l() function can be used safely in multithreaded applications as long as the locale parameter is not the special locale object LC_GLOBAL_LOCALE.
The strerror_s() and strerrorlen_s() functions cannot be used safely in a multithreaded application due to the runtime constraint handler. For more information, see the runtime_constraint_handler(3C) man page. Additionally, if setlocale(3C) is called in any thread during or between the calls to strerrorlen_s() and strerror_s(), the size returned by strerrorlen_s() may not match the length of the string returned by strerror_s() in the new locale.
See standards(7) for descriptions of the following standards:
|
Intro(2), duplocale(3C), freelocale(3C), gettext(3C), newlocale(3C), perror(3C), setlocale(3C), strerrordesc_np(3C), uselocale(3C), attributes(7), standards(7)
The strerror_l(), strerror_s(), and strerrorlen_s() functions were added to Solaris in the Oracle Solaris 11.4.0 release.
The strerror_r() function was added to Solaris in the Solaris 10 3/05 release.
The strerror() function was added to Solaris in the Solaris 2.0 release.