]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
103357f7 | 2 | .\" and Copyright (C) 2005, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" References consulted: | |
27 | .\" Linux libc source code | |
28 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
29 | .\" 386BSD man pages | |
30 | .\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu> | |
31 | .\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl> | |
32 | .\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl> | |
33 | .\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk> | |
34 | .\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl> | |
35 | .\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl> | |
ed07f09a MK |
36 | .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description |
37 | .\" Addition of extra material on portability and standards. | |
fea681da | 38 | .\" |
52d06f48 | 39 | .TH STRERROR 3 2014-03-18 "" "Linux Programmer's Manual" |
fea681da | 40 | .SH NAME |
103357f7 | 41 | strerror, strerror_r, strerror_l \- return string describing error number |
fea681da MK |
42 | .SH SYNOPSIS |
43 | .nf | |
44 | .B #include <string.h> | |
45 | .sp | |
46 | .BI "char *strerror(int " errnum ); | |
b99cf1e0 | 47 | .sp |
2d50dd9e MK |
48 | .BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen ); |
49 | /* XSI-compliant */ | |
50 | .sp | |
6e84dfa1 | 51 | .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen ); |
2d50dd9e | 52 | /* GNU-specific */ |
103357f7 MK |
53 | |
54 | .BI "char *strerror_l(int " errnum ", locale_t " locale ); | |
cc4615cc | 55 | .fi |
6e84dfa1 | 56 | .sp |
cc4615cc MK |
57 | .in -4n |
58 | Feature Test Macro Requirements for glibc (see | |
59 | .BR feature_test_macros (7)): | |
60 | .in | |
103357f7 | 61 | .ad l |
b99cf1e0 | 62 | .sp |
103357f7 MK |
63 | .BR strerror_r (): |
64 | .RS 4 | |
65 | The XSI-compliant version is provided if: | |
cc4615cc | 66 | .br |
98dbe7af | 67 | (_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600) && !\ _GNU_SOURCE |
2d50dd9e MK |
68 | .br |
69 | Otherwise, the GNU-specific version is provided. | |
103357f7 MK |
70 | .RE |
71 | .ad | |
fea681da | 72 | .SH DESCRIPTION |
60a90ecd MK |
73 | The |
74 | .BR strerror () | |
c9980d2e | 75 | function returns a pointer to a string that describes the error |
61d71e01 MK |
76 | code passed in the argument |
77 | .IR errnum , | |
78 | possibly using the | |
ec5a588f | 79 | .B LC_MESSAGES |
fea681da | 80 | part of the current locale to select the appropriate language. |
6fb29ca0 MK |
81 | (For example, if |
82 | .I errnum | |
83 | is | |
84 | .BR EINVAL , | |
926fc5d5 | 85 | the returned description will be "Invalid argument".) |
fea681da | 86 | This string must not be modified by the application, but may be |
60a90ecd | 87 | modified by a subsequent call to |
103357f7 MK |
88 | .BR strerror () |
89 | or | |
90 | .BR strerror_l (). | |
c99c1440 | 91 | No other library function, including |
8ca6ceb0 EB |
92 | .BR perror (3), |
93 | will modify this string. | |
103357f7 | 94 | .\" |
5b436d02 | 95 | .SS strerror_r() |
60a90ecd MK |
96 | The |
97 | .BR strerror_r () | |
98 | function is similar to | |
99 | .BR strerror (), | |
100 | but is | |
c13182ef MK |
101 | thread safe. |
102 | This function is available in two versions: | |
cc4615cc | 103 | an XSI-compliant version specified in POSIX.1-2001 |
8ca6ceb0 | 104 | (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), |
6e84dfa1 | 105 | and a GNU-specific version (available since glibc 2.0). |
cc4615cc MK |
106 | The XSI-compliant version is provided with the feature test macros |
107 | settings shown in the SYNOPSIS; | |
6e84dfa1 | 108 | otherwise the GNU-specific version is provided. |
cc4615cc MK |
109 | If no feature test macros are explicitly defined, |
110 | then (since glibc 2.4) | |
0daa9e92 | 111 | .B _POSIX_SOURCE |
cc4615cc MK |
112 | is defined by default with the value |
113 | 200112L, so that the XSI-compliant version of | |
114 | .BR strerror_r () | |
115 | is provided by default. | |
6e84dfa1 | 116 | |
c13182ef MK |
117 | The XSI-compliant |
118 | .BR strerror_r () | |
6e84dfa1 MK |
119 | is preferred for portable applications. |
120 | It returns the error string in the user-supplied buffer | |
fea681da MK |
121 | .I buf |
122 | of length | |
6e84dfa1 MK |
123 | .IR buflen . |
124 | ||
c13182ef MK |
125 | The GNU-specific |
126 | .BR strerror_r () | |
6e84dfa1 MK |
127 | returns a pointer to a string containing the error message. |
128 | This may be either a pointer to a string that the function stores in | |
129 | .IR buf , | |
130 | or a pointer to some (immutable) static string | |
131 | (in which case | |
c13182ef | 132 | .I buf |
6e84dfa1 | 133 | is unused). |
c13182ef | 134 | If the function stores a string in |
6e84dfa1 MK |
135 | .IR buf , |
136 | then at most | |
137 | .I buflen | |
138 | bytes are stored (the string may be truncated if | |
139 | .I buflen | |
8ca6ceb0 EB |
140 | is too small and |
141 | .I errnum | |
142 | is unknown). | |
f24e3a3a | 143 | The string always includes a terminating null byte (\(aq\\0\(aq). |
103357f7 MK |
144 | .\" |
145 | .SS strerror_l() | |
146 | .BR strerror_l () | |
147 | is like | |
148 | .BR strerror (), | |
149 | but maps | |
150 | .I errnum | |
151 | to a locale-dependent error message in the locale specified by | |
152 | .IR locale . | |
153 | The behavior of | |
154 | .BR strerror_l () | |
155 | is undefined if | |
156 | .I locale | |
157 | is the special locale object | |
158 | .BR LC_GLOBAL_LOCALE | |
159 | or is not a valid locale object handle. | |
47297adb | 160 | .SH RETURN VALUE |
60a90ecd | 161 | The |
103357f7 MK |
162 | .BR strerror (), |
163 | .BR strerror_l (), | |
2d50dd9e | 164 | and the GNU-specific |
60a90ecd MK |
165 | .BR strerror_r () |
166 | functions return | |
c13182ef | 167 | the appropriate error description string, |
6e84dfa1 | 168 | or an "Unknown error nnn" message if the error number is unknown. |
6e84dfa1 | 169 | |
103357f7 MK |
170 | The XSI-compliant |
171 | .BR strerror_r () | |
172 | function returns 0 on success. | |
173 | On error, | |
174 | a (positive) error number is returned (since glibc 2.13), | |
175 | or \-1 is returned and | |
176 | .I errno | |
177 | is set to indicate the error (glibc versions before 2.13). | |
178 | ||
f2682520 | 179 | POSIX.1-2001 and POSIX.1-2008 require that a successful call to |
563f4681 | 180 | .BR strerror () |
103357f7 MK |
181 | or |
182 | .BR strerror_l () | |
f2682520 MK |
183 | shall leave |
184 | .I errno | |
185 | unchanged, and note that, | |
186 | since no function return value is reserved to indicate an error, | |
187 | an application that wishes to check for errors should initialize | |
188 | .I errno | |
189 | to zero before the call, | |
190 | and then check | |
191 | .I errno | |
192 | after the call. | |
fea681da MK |
193 | .SH ERRORS |
194 | .TP | |
195 | .B EINVAL | |
196 | The value of | |
197 | .I errnum | |
198 | is not a valid error number. | |
199 | .TP | |
200 | .B ERANGE | |
201 | Insufficient storage was supplied to contain the error description string. | |
18b3fa61 | 202 | .SH ATTRIBUTES |
9cf2aed1 PH |
203 | For an explanation of the terms used in this section, see |
204 | .BR attributes (7). | |
205 | .TS | |
206 | allbox; | |
207 | lbw26 lb lb | |
208 | l l l. | |
209 | Interface Attribute Value | |
210 | T{ | |
18b3fa61 | 211 | .BR strerror () |
a78cdad6 | 212 | T} Thread safety MT-Unsafe race:strerror |
9cf2aed1 PH |
213 | T{ |
214 | .BR strerror_r (), | |
215 | .BR strerror_l () | |
216 | T} Thread safety MT-Safe | |
217 | .TE | |
103357f7 MK |
218 | .SH VERSIONS |
219 | The | |
220 | .BR strerror_l () | |
221 | function first appeared in glibc 2.6. | |
47297adb | 222 | .SH CONFORMING TO |
60a90ecd | 223 | .BR strerror () |
b0bcb0ad | 224 | is specified by POSIX.1-2001, POSIX.1-2008, C89, and C99. |
60a90ecd | 225 | .BR strerror_r () |
b0bcb0ad | 226 | is specified by POSIX.1-2001 and POSIX.1-2008. |
6e84dfa1 | 227 | |
103357f7 MK |
228 | .BR strerror_l () |
229 | is specified in POSIX.1-2008. | |
230 | ||
c13182ef | 231 | The GNU-specific |
63aa9df0 | 232 | .BR strerror_r () |
c8f2dd47 | 233 | function is a nonstandard extension. |
6e84dfa1 | 234 | |
68e1685c | 235 | POSIX.1-2001 permits |
6e84dfa1 | 236 | .BR strerror () |
c13182ef | 237 | to set |
6e84dfa1 | 238 | .I errno |
c13182ef | 239 | if the call encounters an error, but does not specify what |
6e84dfa1 MK |
240 | value should be returned as the function result in the event of an error. |
241 | On some systems, | |
242 | .\" e.g., Solaris 8, HP-UX 11 | |
243 | .BR strerror () | |
244 | returns NULL if the error number is unknown. | |
c13182ef | 245 | On other systems, |
6e84dfa1 MK |
246 | .\" e.g., FreeBSD 5.4, Tru64 5.1B |
247 | .BR strerror () | |
c13182ef | 248 | returns a string something like "Error nnn occurred" and sets |
6e84dfa1 | 249 | .I errno |
c13182ef | 250 | to |
6e84dfa1 MK |
251 | .B EINVAL |
252 | if the error number is unknown. | |
8ca6ceb0 | 253 | C99 and POSIX.1-2008 require the return value to be non-NULL. |
47297adb | 254 | .SH SEE ALSO |
d7871cf9 | 255 | .BR err (3), |
fea681da | 256 | .BR errno (3), |
37b6aec3 | 257 | .BR error (3), |
fea681da | 258 | .BR perror (3), |
103357f7 MK |
259 | .BR strsignal (3), |
260 | .BR locale (7) |