STRERROR(3) Library Functions Manual STRERROR(3)

perror, strerror, strerror_l, strerror_r, sys_errlist, sys_nerr — system error messages

Standard C Library (libc, -lc)

#include <stdio.h>

void
perror(const char *string);

#include <errno.h>

extern const char * const sys_errlist[];
extern const int sys_nerr;

#include <string.h>

char *
strerror(int errnum);

int
strerror_r(int errnum, char *strerrbuf, size_t buflen);

char *
strerror_l(int errnum, locale_t loc);

The (), strerror_l(), strerror_r(), and perror() functions look up the language-dependent error message string corresponding to an error number.

The () function accepts an error number argument errnum and returns a pointer to the corresponding message string. The application should not attempt to modify the returned string, it may be shared, or read only.

The () function renders the same result into strerrbuf for a maximum of buflen characters (including terminator) and returns 0 upon success.

The () function is like strerror() but provides in loc the locale to be used to obtain the language for the message, rather than using the application's current locale.

The () function finds the error message corresponding to the current value of the global variable errno (intro(2)) and writes it, followed by a newline, to the standard error file descriptor. If the argument string is non-NULL and does not point to the nul character, this string is prepended to the message string and separated from it by a colon and space (“: ”); otherwise, only the error message string is printed. Note that in most cases the err(3) and warn(3) family of functions is preferable to perror(); they are more flexible and also print the program name.

If the error number is not recognized, these functions return an error message string containing “Unknown error: ” followed by the error number in decimal. To warn about this, () and strerror_l() set errno to EINVAL, and strerror_r() returns EINVAL. In other cases, except where noted below, errno is not altered, so applications should set it to a known value (usually zero) before calling either strerror() or strerror_l() if the resulting value in errno is to be tested for this condition. Error numbers recognized by this implementation fall in the range 0 < errnum < sys_nerr.

If insufficient storage is provided in strerrbuf (as specified in buflen) to contain the error string, () returns ERANGE and strerrbuf will contain an error message that has been truncated and NUL terminated to fit the length specified by buflen. In extraordinary cases, it is possible that the internal buffer used by strerror() and strerror_l() may be too small for a translated message, in which case it will be truncated as indicated for strerror_r() and errno will be set to ERANGE.

The POSIX locale message strings can be accessed directly using the external array sys_errlist. The external value sys_nerr contains a count of the messages in sys_errlist. The use of these variables is deprecated; one of the () family of functions should be used instead.

Programs that attempt to use the deprecated sys_errlist variable often fail to compile because they provide their own, inconsistent, declaration of it. Such programs should be updated to use strerror().

These functions may fail if:

[]
The error number was out of range.
[]
The string buffer supplied was not large enough to hold the complete error message.

intro(2), err(3), psignal(3), warn(3)

The perror() and strerror() functions conform to ISO/IEC 9899:1999 (“ISO C99”). The strerror_r() function conforms to IEEE Std 1003.1-2001 (“POSIX.1”). The strerror_l() function conforms to IEEE Std 1003.1-2008 (“POSIX.1”).

The perror() function first appeared in Version 4 AT&T UNIX. The strerror() function first appeared in 4.3BSD-Reno. The strerror_r() function first appeared in NetBSD 4.0. The strerror_l() function was first released in NetBSD 7.0.

The strerror() function may return its result in a static buffer which will be overwritten by subsequent calls. For portable use, this must be assumed to be a subsequent call from the current, or any other, thread in the process. This implementation limits the issue to calls from the current thread. The strerror_l() function has a similar restriction, but even in other implementations, is required to use thread local storage, so only other calls from the calling thread can overwrite the result. Both strerror() and strerror_l() use the same thread local storage; a call to either will destroy the result from an earlier call by the same thread of either of them.

April 4, 2020 NetBSD 11.0