1STRERROR(3P)               POSIX Programmer's Manual              STRERROR(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       strerror, strerror_l, strerror_r — get error message string
14

SYNOPSIS

16       #include <string.h>
17
18       char *strerror(int errnum);
19       char *strerror_l(int errnum, locale_t locale);
20       int strerror_r(int errnum, char *strerrbuf, size_t buflen);
21

DESCRIPTION

23       For strerror(): The functionality described on this reference  page  is
24       aligned  with the ISO C standard. Any conflict between the requirements
25       described here and the ISO C standard is unintentional. This volume  of
26       POSIX.1‐2008 defers to the ISO C standard.
27
28       The  strerror()  function  shall  map  the  error number in errnum to a
29       locale-dependent error message string and shall return a pointer to it.
30       Typically,  the values for errnum come from errno, but strerror() shall
31       map any value of type int to a message.
32
33       The application shall not modify the  string  returned.   The  returned
34       string  pointer  might  be  invalidated  or the string content might be
35       overwritten by a subsequent call to strerror(), or by a subsequent call
36       to strerror_l() in the same thread.
37
38       The  string  may be overwritten by a subsequent call to strerror_l() in
39       the same thread.
40
41       The contents of the error message strings returned by strerror() should
42       be determined by the setting of the LC_MESSAGES category in the current
43       locale.
44
45       The implementation shall behave as if no function defined in this  vol‐
46       ume of POSIX.1‐2008 calls strerror().
47
48       The  strerror() and strerror_l() functions shall not change the setting
49       of errno if successful.
50
51       Since no return value is reserved to indicate an error  of  strerror(),
52       an  application  wishing to check for error situations should set errno
53       to 0, then call strerror(), then check errno.   Similarly,  since  str‐
54       error_l()  is  required to return a string for some errors, an applica‐
55       tion wishing to check for all error situations should set errno  to  0,
56       then call strerror_l(), then check errno.
57
58       The strerror() function need not be thread-safe.
59
60       The  strerror_l()  function  shall  map the error number in errnum to a
61       locale-dependent error message string  in  the  locale  represented  by
62       locale and shall return a pointer to it.
63
64       The  strerror_r()  function  shall  map the error number in errnum to a
65       locale-dependent error message string and shall return  the  string  in
66       the buffer pointed to by strerrbuf, with length buflen.
67
68       If  the  value  of  errnum  is a valid error number, the message string
69       shall indicate what error occurred; if the value of errnum is zero, the
70       message  string  shall  either  be  an empty string or indicate that no
71       error occurred; otherwise, if these  functions  complete  successfully,
72       the message string shall indicate that an unknown error occurred.
73
74       The behavior is undefined if the locale argument to strerror_l() is the
75       special locale object LC_GLOBAL_LOCALE or is not a valid locale  object
76       handle.
77

RETURN VALUE

79       Upon  completion,  whether successful or not, strerror() shall return a
80       pointer to the generated message string.  On error errno  may  be  set,
81       but no return value is reserved to indicate an error.
82
83       Upon  successful completion, strerror_l() shall return a pointer to the
84       generated message string. If errnum is not a valid error number,  errno
85       may  be  set to [EINVAL], but a pointer to a message string shall still
86       be returned. If any other error occurs, errno shall be set to  indicate
87       the error and a null pointer shall be returned.
88
89       Upon  successful completion, strerror_r() shall return 0. Otherwise, an
90       error number shall be returned to indicate the error.
91

ERRORS

93       These functions may fail if:
94
95       EINVAL The value of errnum is neither a valid error number nor zero.
96
97       The strerror_r() function may fail if:
98
99       ERANGE Insufficient storage was supplied via strerrbuf  and  buflen  to
100              contain the generated message string.
101
102       The following sections are informative.
103

EXAMPLES

105       None.
106

APPLICATION USAGE

108       Historically in some implementations, calls to perror() would overwrite
109       the string that the pointer returned  by  strerror()  points  to.  Such
110       implementations  did not conform to the ISO C standard; however, appli‐
111       cation developers should be aware of this behavior if they  wish  their
112       applications to be portable to such implementations.
113

RATIONALE

115       The strerror_l() function is required to be thread-safe, thereby elimi‐
116       nating the need for an equivalent to the strerror_r() function.
117
118       Earlier versions of this standard did not explicitly require  that  the
119       error  message  strings returned by strerror() and strerror_r() provide
120       any information about the error. This version of the standard  requires
121       a meaningful message for any successful completion.
122
123       Since  no  return value is reserved to indicate a strerror() error, but
124       all calls (whether successful or not) must return a pointer to  a  mes‐
125       sage  string,  on  error  strerror()  can  return a pointer to an empty
126       string or a pointer to a meaningful string that can be printed.
127
128       Note that the [EINVAL] error condition is  a  may  fail  error.  If  an
129       invalid  error  number is supplied as the value of errnum, applications
130       should be prepared to handle any of the following:
131
132        1. Error (with no meaningful message): errno is set to  [EINVAL],  the
133           return value is a pointer to an empty string.
134
135        2. Successful  completion:  errno  is  unchanged  and the return value
136           points to a string like "unknownerror" or  "errornumberxxx"  (where
137           xxx is the value of errnum).
138
139        3. Combination  of  #1 and #2: errno is set to [EINVAL] and the return
140           value points to a string like  "unknownerror"  or  "errornumberxxx"
141           (where  xxx is the value of errnum).  Since applications frequently
142           use the return value of strerror() as an argument to functions like
143           fprintf()  (without  checking  the return value) and since applica‐
144           tions have no way to parse an error  message  string  to  determine
145           whether errnum represents a valid error number, implementations are
146           encouraged to implement #3. Similarly, implementations are  encour‐
147           aged  to  have  strerror_r()  return [EINVAL] and put a string like
148           "unknownerror" or "errornumberxxx" in the buffer pointed to by str‐
149           errbuf when the value of errnum is not a valid error number.
150
151       Some applications rely on being able to set errno to 0 before calling a
152       function with no reserved value to indicate an error,  then  call  str‐
153       error(errno)  afterwards  to  detect whether an error occurred (because
154       errno changed) or to indicate success (because  errno  remained  zero).
155       This  usage  pattern  requires  that  strerror(0)  succeed  with useful
156       results. Previous versions of the standard did not specify the behavior
157       when errnum is zero.
158

FUTURE DIRECTIONS

160       None.
161

SEE ALSO

163       perror()
164
165       The Base Definitions volume of POSIX.1‐2008, <string.h>
166
168       Portions  of  this text are reprinted and reproduced in electronic form
169       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
170       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
171       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
172       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
173       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
174       event of any discrepancy between this version and the original IEEE and
175       The Open Group Standard, the original IEEE and The Open Group  Standard
176       is  the  referee document. The original Standard can be obtained online
177       at http://www.unix.org/online.html .
178
179       Any typographical or formatting errors that appear  in  this  page  are
180       most likely to have been introduced during the conversion of the source
181       files to man page format. To report such errors,  see  https://www.ker
182       nel.org/doc/man-pages/reporting_bugs.html .
183
184
185
186IEEE/The Open Group                  2013                         STRERROR(3P)
Impressum