diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3p/strerror.3p')
| -rw-r--r-- | upstream/mageia-cauldron/man3p/strerror.3p | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3p/strerror.3p b/upstream/mageia-cauldron/man3p/strerror.3p new file mode 100644 index 00000000..c15777f4 --- /dev/null +++ b/upstream/mageia-cauldron/man3p/strerror.3p @@ -0,0 +1,310 @@ +'\" 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 . |