NAME
perror(), strerror(), strerror_r() — write system error messages
SYNOPSIS
#include <stdio.h>
void perror(const char *s);
#include <string.h>
char *strerror(int errnum);
#include <errno.h>
extern char *sys_errlist[];
extern int sys_nerr;
#include <string.h>
int strerror_r(int errnum, char *buffer, size_t buflen);
DESCRIPTION
perror()
writes a language-dependent message to the standard error output,
describing the last error encountered during a call
to a system or library function.
The argument string
s
is printed first, followed by a colon, a blank,
the message, and a newline character.
To be most useful, the argument string should include the name
of the program that incurred the error.
The error number is taken from the symbol
errno,
which is set when errors occur but not cleared when
non-erroneous calls are made.
The contents of the message is identical to those returned by the
strerror()
function with
errno
as the argument.
If given a NULL string, the
perror()
function prints only the message and a newline character.
To simplify variant formatting of messages,
the
strerror()
function and the
sys_errlist
array of message strings are provided.
The
strerror()
function maps the error number in
errnum
to a language-dependent error message string
and returns a pointer to the string.
The message string is returned without a newline character.
errno
can be used as an index into
sys_errlist
to get an untranslated message string without the newline character.
sys_nerr
is the largest message number provided for in the table;
it should be checked because new error codes
might be added to the system before they are added to the table.
strerror()
must be used to retrieve messages when translations are desired.
The
strerror_r()
function maps the error number in
errnum
to a locale-dependent error message string and
returns the string in the buffer pointed to by
buffer,
which has length
buflen.
EXTERNAL INFLUENCES
Environment Variables
The language of the message returned by
strerror()
and printed by
perror()
is specified by the
LANG
environment variable.
If the language-dependent message is not available, or if
LANG
is not set or is set to the empty string,
the default version of the message associated with the "C" language (see
lang(5))
is used.
International Code Set Support
Single and multi-byte character code sets are supported.
RETURN VALUE
perror()
returns no value.
If the
errnum
message number is valid,
strerror()
returns a pointer to a language-dependent message string.
The array pointed to should not be modified by the program,
and might be overwritten by a subsequent call to the function.
If a valid
errnum
message number does not have a corresponding language-dependent message,
strerror()
uses
errnum
as an index into
sys_errlist
to get the message string.
If the
errnum
message number is invalid,
strerror()
returns a pointer to a NULL string.
Upon successful completion,
strerror_r()
returns 0.
Otherwise, an error number is returned to indicate the error.
ERRORS
If the
strerror_r()
function fails, it will return one of the following errors:
- EINVAL
The value of
errnum
is not a valid error number.
- ERANGE
Insufficient storage was supplied via
buffer
and
buflen
to contain the generated message string.
WARNINGS
The return value for
strerror()
points to data whose content is overwritten by subsequent calls to
strerror()
from the same thread.
STANDARDS CONFORMANCE
perror(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C
strerror(): AES, SVID3, XPG3, XPG4, ANSI C
sys_errlist: SVID2, SVID3, XPG2
sys_nerr: SVID2, SVID3, XPG2
Printable version
