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