STRERROR(3)                POSIX Programmer's Manual               STRERROR(3)



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.

NNAAMMEE
       strerror, strerror_l, strerror_r -- get error message string

SSYYNNOOPPSSIISS
       #include <string.h>

       char *strerror(int _e_r_r_n_u_m);
       char *strerror_l(int _e_r_r_n_u_m, locale_t _l_o_c_a_l_e);
       int strerror_r(int _e_r_r_n_u_m, char *_s_t_r_e_r_r_b_u_f, size_t _b_u_f_l_e_n);

DDEESSCCRRIIPPTTIIOONN
       For _s_t_r_e_r_r_o_r(): 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-2017 defers to the ISO C standard.

       The _s_t_r_e_r_r_o_r() function shall map the error number in _e_r_r_n_u_m to a
       locale-dependent error message string and shall return a pointer to it.
       Typically, the values for _e_r_r_n_u_m come from _e_r_r_n_o, but _s_t_r_e_r_r_o_r() shall
       map any value of type iinntt to a message.

       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 _s_t_r_e_r_r_o_r(), or by a subsequent call
       to _s_t_r_e_r_r_o_r___l() in the same thread. The returned pointer and the string
       content might also be invalidated if the calling thread is terminated.

       The string may be overwritten by a subsequent call to _s_t_r_e_r_r_o_r___l() in
       the same thread.

       The contents of the error message strings returned by _s_t_r_e_r_r_o_r() should
       be determined by the setting of the _L_C___M_E_S_S_A_G_E_S category in the current
       locale.

       The implementation shall behave as if no function defined in this
       volume of POSIX.1-2017 calls _s_t_r_e_r_r_o_r().

       The _s_t_r_e_r_r_o_r() and _s_t_r_e_r_r_o_r___l() functions shall not change the setting
       of _e_r_r_n_o if successful.

       Since no return value is reserved to indicate an error of _s_t_r_e_r_r_o_r(),
       an application wishing to check for error situations should set _e_r_r_n_o
       to 0, then call _s_t_r_e_r_r_o_r(), then check _e_r_r_n_o.  Similarly, since
       _s_t_r_e_r_r_o_r___l() is required to return a string for some errors, an
       application wishing to check for all error situations should set _e_r_r_n_o
       to 0, then call _s_t_r_e_r_r_o_r___l(), then check _e_r_r_n_o.

       The _s_t_r_e_r_r_o_r() function need not be thread-safe.

       The _s_t_r_e_r_r_o_r___l() function shall map the error number in _e_r_r_n_u_m to a
       locale-dependent error message string in the locale represented by
       _l_o_c_a_l_e and shall return a pointer to it.

       The _s_t_r_e_r_r_o_r___r() function shall map the error number in _e_r_r_n_u_m to a
       locale-dependent error message string and shall return the string in
       the buffer pointed to by _s_t_r_e_r_r_b_u_f, with length _b_u_f_l_e_n.

       If the value of _e_r_r_n_u_m is a valid error number, the message string
       shall indicate what error occurred; if the value of _e_r_r_n_u_m 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.

       The behavior is undefined if the _l_o_c_a_l_e argument to _s_t_r_e_r_r_o_r___l() is the
       special locale object LC_GLOBAL_LOCALE or is not a valid locale object
       handle.

RREETTUURRNN VVAALLUUEE
       Upon completion, whether successful or not, _s_t_r_e_r_r_o_r() shall return a
       pointer to the generated message string.  On error _e_r_r_n_o may be set,
       but no return value is reserved to indicate an error.

       Upon successful completion, _s_t_r_e_r_r_o_r___l() shall return a pointer to the
       generated message string. If _e_r_r_n_u_m is not a valid error number, _e_r_r_n_o
       may be set to [[EEIINNVVAALL]], but a pointer to a message string shall still
       be returned. If any other error occurs, _e_r_r_n_o shall be set to indicate
       the error and a null pointer shall be returned.

       Upon successful completion, _s_t_r_e_r_r_o_r___r() shall return 0. Otherwise, an
       error number shall be returned to indicate the error.

EERRRROORRSS
       These functions may fail if:

       EEIINNVVAALL The value of _e_r_r_n_u_m is neither a valid error number nor zero.

       The _s_t_r_e_r_r_o_r___r() function may fail if:

       EERRAANNGGEE Insufficient storage was supplied via _s_t_r_e_r_r_b_u_f and _b_u_f_l_e_n to
              contain the generated message string.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       None.

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       Historically in some implementations, calls to _p_e_r_r_o_r() would overwrite
       the string that the pointer returned by _s_t_r_e_r_r_o_r() 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.

RRAATTIIOONNAALLEE
       The _s_t_r_e_r_r_o_r___l() function is required to be thread-safe, thereby
       eliminating the need for an equivalent to the _s_t_r_e_r_r_o_r___r() function.

       Earlier versions of this standard did not explicitly require that the
       error message strings returned by _s_t_r_e_r_r_o_r() and _s_t_r_e_r_r_o_r___r() provide
       any information about the error. This version of the standard requires
       a meaningful message for any successful completion.

       Since no return value is reserved to indicate a _s_t_r_e_r_r_o_r() error, but
       all calls (whether successful or not) must return a pointer to a
       message string, on error _s_t_r_e_r_r_o_r() can return a pointer to an empty
       string or a pointer to a meaningful string that can be printed.

       Note that the [[EEIINNVVAALL]] error condition is a may fail error. If an
       invalid error number is supplied as the value of _e_r_r_n_u_m, applications
       should be prepared to handle any of the following:

        1. Error (with no meaningful message): _e_r_r_n_o is set to [[EEIINNVVAALL]], the
           return value is a pointer to an empty string.

        2. Successful completion: _e_r_r_n_o is unchanged and the return value
           points to a string like ""uunnkknnoowwnnerror" or ""eerrrroorrnumberxxxxxx"" (where
           _x_x_x is the value of _e_r_r_n_u_m).

        3. Combination of #1 and #2: _e_r_r_n_o is set to [[EEIINNVVAALL]] and the return
           value points to a string like ""uunnkknnoowwnnerror" or ""eerrrroorrnumberxxxxxx""
           (where _x_x_x is the value of _e_r_r_n_u_m).  Since applications frequently
           use the return value of _s_t_r_e_r_r_o_r() as an argument to functions like
           _f_p_r_i_n_t_f() (without checking the return value) and since
           applications have no way to parse an error message string to
           determine whether _e_r_r_n_u_m represents a valid error number,
           implementations are encouraged to implement #3. Similarly,
           implementations are encouraged to have _s_t_r_e_r_r_o_r___r() return [[EEIINNVVAALL]]
           and put a string like ""uunnkknnoowwnnerror" or ""eerrrroorrnumberxxxxxx"" in the
           buffer pointed to by _s_t_r_e_r_r_b_u_f when the value of _e_r_r_n_u_m is not a
           valid error number.

       Some applications rely on being able to set _e_r_r_n_o to 0 before calling a
       function with no reserved value to indicate an error, then call
       _s_t_r_e_r_r_o_r(_e_r_r_n_o) afterwards to detect whether an error occurred (because
       _e_r_r_n_o changed) or to indicate success (because _e_r_r_n_o remained zero).
       This usage pattern requires that _s_t_r_e_r_r_o_r(0) succeed with useful
       results. Previous versions of the standard did not specify the behavior
       when _e_r_r_n_u_m is zero.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _p_e_r_r_o_r()

       The Base Definitions volume of POSIX.1-2017, <<ssttrriinngg..hh>>

CCOOPPYYRRIIGGHHTT
       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 .

       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 .



IEEE/The Open Group                  2017                          STRERROR(3)
