|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH STRERROR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
strerror,
|
|
Packit |
7cfc04 |
strerror_l,
|
|
Packit |
7cfc04 |
strerror_r
|
|
Packit |
7cfc04 |
\(em get error message string
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <string.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
char *strerror(int \fIerrnum\fR);
|
|
Packit |
7cfc04 |
char *strerror_l(int \fIerrnum\fR, locale_t \fIlocale\fR);
|
|
Packit |
7cfc04 |
int strerror_r(int \fIerrnum\fR, char *\fIstrerrbuf\fR, size_t \fIbuflen\fR);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
For
|
|
Packit |
7cfc04 |
\fIstrerror\fR():
|
|
Packit |
7cfc04 |
The functionality described on this reference page is aligned with the
|
|
Packit |
7cfc04 |
ISO\ C standard. Any conflict between the requirements described here and the
|
|
Packit |
7cfc04 |
ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
function shall map the error number in
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
to a locale-dependent error message string and shall return a pointer
|
|
Packit |
7cfc04 |
to it. Typically, the values for
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
come from
|
|
Packit |
7cfc04 |
.IR errno ,
|
|
Packit |
7cfc04 |
but
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
shall map any value of type
|
|
Packit |
7cfc04 |
.BR int
|
|
Packit |
7cfc04 |
to a message.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The application shall not modify the string returned.
|
|
Packit |
7cfc04 |
The returned string pointer might be invalidated or
|
|
Packit |
7cfc04 |
the string content might be overwritten by a subsequent call to
|
|
Packit |
7cfc04 |
\fIstrerror\fR(),
|
|
Packit |
7cfc04 |
or by a subsequent call to
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
in the same thread.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The string may be overwritten by a subsequent call to
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
in the same thread.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The contents of the error message strings returned by
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
should be determined by the setting of the
|
|
Packit |
7cfc04 |
.IR LC_MESSAGES
|
|
Packit |
7cfc04 |
category in the current locale.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The implementation shall behave as if no function defined in this volume of POSIX.1\(hy2008
|
|
Packit |
7cfc04 |
calls
|
|
Packit |
7cfc04 |
\fIstrerror\fR().
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
functions shall not change the setting of
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
if successful.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Since no return value is reserved to indicate an error of
|
|
Packit |
7cfc04 |
\fIstrerror\fR(),
|
|
Packit |
7cfc04 |
an application wishing to check for error situations should set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to 0, then call
|
|
Packit |
7cfc04 |
\fIstrerror\fR(),
|
|
Packit |
7cfc04 |
then check
|
|
Packit |
7cfc04 |
.IR errno .
|
|
Packit |
7cfc04 |
Similarly, since
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
is required to return a string for some errors, an application wishing
|
|
Packit |
7cfc04 |
to check for all error situations should set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to 0, then call
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR(),
|
|
Packit |
7cfc04 |
then check
|
|
Packit |
7cfc04 |
.IR errno .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
function need not be thread-safe.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
function shall map the error number in
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
to a locale-dependent error message string in the locale represented by
|
|
Packit |
7cfc04 |
.IR locale
|
|
Packit |
7cfc04 |
and shall return a pointer to it.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
function shall map the error number in
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
to a locale-dependent error message string and shall return the string
|
|
Packit |
7cfc04 |
in the buffer pointed to by
|
|
Packit |
7cfc04 |
.IR strerrbuf ,
|
|
Packit |
7cfc04 |
with length
|
|
Packit |
7cfc04 |
.IR buflen .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the value of
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is a valid error number, the message string shall indicate what error
|
|
Packit |
7cfc04 |
occurred; if the value of
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is zero, the message string shall either be an empty string or
|
|
Packit |
7cfc04 |
indicate that no error occurred; otherwise, if these functions complete
|
|
Packit |
7cfc04 |
successfully, the message string shall indicate that an unknown error
|
|
Packit |
7cfc04 |
occurred.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The behavior is undefined if the
|
|
Packit |
7cfc04 |
.IR locale
|
|
Packit |
7cfc04 |
argument to
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
is the special locale object LC_GLOBAL_LOCALE or is not a valid locale
|
|
Packit |
7cfc04 |
object handle.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon completion, whether successful or not,
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
shall return a pointer to the generated message string.
|
|
Packit |
7cfc04 |
On error
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
may be set, but no return value is reserved to indicate an error.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
shall return a pointer to the generated message string. If
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is not a valid error number,
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
may be set to
|
|
Packit |
7cfc04 |
.BR [EINVAL] ,
|
|
Packit |
7cfc04 |
but a pointer to a message string shall still be returned. If any other
|
|
Packit |
7cfc04 |
error occurs,
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
shall be set to indicate the error and a null pointer shall be
|
|
Packit |
7cfc04 |
returned.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
shall return 0. Otherwise, an error number shall be returned to
|
|
Packit |
7cfc04 |
indicate the error.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
These functions may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The value of
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is neither a valid error number nor zero.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ERANGE
|
|
Packit |
7cfc04 |
Insufficient storage was supplied via
|
|
Packit |
7cfc04 |
.IR strerrbuf
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR buflen
|
|
Packit |
7cfc04 |
to contain the generated message string.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
Historically in some implementations, calls to
|
|
Packit |
7cfc04 |
\fIperror\fR()
|
|
Packit |
7cfc04 |
would overwrite the string that the pointer returned by
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
points to. Such implementations did not conform to the ISO\ C standard; however,
|
|
Packit |
7cfc04 |
application developers should be aware of this behavior if they wish
|
|
Packit |
7cfc04 |
their applications to be portable to such implementations.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIstrerror_l\fR()
|
|
Packit |
7cfc04 |
function is required to be thread-safe, thereby eliminating the
|
|
Packit |
7cfc04 |
need for an equivalent to the
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
function.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Earlier versions of this standard did not explicitly require that the
|
|
Packit |
7cfc04 |
error message strings returned by
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
provide any information about the error. This version of the standard
|
|
Packit |
7cfc04 |
requires a meaningful message for any successful completion.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Since no return value is reserved to indicate a
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
error, but all calls (whether successful or not) must return a pointer
|
|
Packit |
7cfc04 |
to a message string, on error
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
can return a pointer to an empty string or a pointer to a meaningful
|
|
Packit |
7cfc04 |
string that can be printed.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Note that the
|
|
Packit |
7cfc04 |
.BR [EINVAL]
|
|
Packit |
7cfc04 |
error condition is a may fail error. If an invalid error number is
|
|
Packit |
7cfc04 |
supplied as the value of
|
|
Packit |
7cfc04 |
.IR errnum ,
|
|
Packit |
7cfc04 |
applications should be prepared to handle any of the following:
|
|
Packit |
7cfc04 |
.IP " 1." 4
|
|
Packit |
7cfc04 |
Error (with no meaningful message):
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
is set to
|
|
Packit |
7cfc04 |
.BR [EINVAL] ,
|
|
Packit |
7cfc04 |
the return value is a pointer to an empty string.
|
|
Packit |
7cfc04 |
.IP " 2." 4
|
|
Packit |
7cfc04 |
Successful completion:
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
is unchanged and the return value points to a string like
|
|
Packit |
7cfc04 |
.BR \(dqunknown error\(dq
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR \(dqerror number xxx\(dq
|
|
Packit |
7cfc04 |
(where
|
|
Packit |
7cfc04 |
.IR xxx
|
|
Packit |
7cfc04 |
is the value of
|
|
Packit |
7cfc04 |
.IR errnum ).
|
|
Packit |
7cfc04 |
.IP " 3." 4
|
|
Packit |
7cfc04 |
Combination of #1 and #2:
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
is set to
|
|
Packit |
7cfc04 |
.BR [EINVAL]
|
|
Packit |
7cfc04 |
and the return value points to a string like
|
|
Packit |
7cfc04 |
.BR \(dqunknown error\(dq
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR \(dqerror number xxx\(dq
|
|
Packit |
7cfc04 |
(where
|
|
Packit |
7cfc04 |
.IR xxx
|
|
Packit |
7cfc04 |
is the value of
|
|
Packit |
7cfc04 |
.IR errnum ).
|
|
Packit |
7cfc04 |
Since applications frequently use the return value of
|
|
Packit |
7cfc04 |
\fIstrerror\fR()
|
|
Packit |
7cfc04 |
as an argument to functions like
|
|
Packit |
7cfc04 |
\fIfprintf\fR()
|
|
Packit |
7cfc04 |
(without checking the return value) and since applications have no way
|
|
Packit |
7cfc04 |
to parse an error message string to determine whether
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
represents a valid error number, implementations are encouraged to
|
|
Packit |
7cfc04 |
implement #3. Similarly, implementations are encouraged to have
|
|
Packit |
7cfc04 |
\fIstrerror_r\fR()
|
|
Packit |
7cfc04 |
return
|
|
Packit |
7cfc04 |
.BR [EINVAL]
|
|
Packit |
7cfc04 |
and put a string like
|
|
Packit |
7cfc04 |
.BR \(dqunknown error\(dq
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR \(dqerror number xxx\(dq
|
|
Packit |
7cfc04 |
in the buffer pointed to by
|
|
Packit |
7cfc04 |
.IR strerrbuf
|
|
Packit |
7cfc04 |
when the value of
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is not a valid error number.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Some applications rely on being able to set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to 0 before calling a function with no reserved value to indicate an
|
|
Packit |
7cfc04 |
error, then call
|
|
Packit |
7cfc04 |
.IR strerror ( errno )
|
|
Packit |
7cfc04 |
afterwards to detect whether an error occurred (because
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
changed) or to indicate success (because
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
remained zero). This usage pattern requires that
|
|
Packit |
7cfc04 |
.IR strerror (0)
|
|
Packit |
7cfc04 |
succeed with useful results. Previous versions of the standard did not
|
|
Packit |
7cfc04 |
specify the behavior when
|
|
Packit |
7cfc04 |
.IR errnum
|
|
Packit |
7cfc04 |
is zero.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIperror\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<string.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|