STRERROR(3) | Library Functions Manual | STRERROR(3) |
perror
, strerror
,
strerror_l
, strerror_r
,
sys_errlist
, sys_nerr
—
#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);
strerror
(), strerror_l
(),
strerror_r
(), and perror
()
functions look up the language-dependent error message string corresponding to
an error number.
The strerror
() 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 strerror_r
() function renders the same
result into strerrbuf for a maximum of
buflen characters (including terminator) and returns 0
upon success.
The strerror_l
() 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 perror
() 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, strerror
() 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,
strerror_r
() 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 strerror
() family of functions should be
used instead.
strerror
().
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”).
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.
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 10.0 |