]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da | 2 | .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk) |
d2c55aa7 | 3 | .\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da MK |
6 | .\" |
7 | .\" References consulted: | |
8 | .\" Linux libc source code | |
9 | .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991) | |
10 | .\" 386BSD man pages | |
11 | .\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu> | |
12 | .\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl> | |
13 | .\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl> | |
14 | .\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk> | |
15 | .\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl> | |
16 | .\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl> | |
ed07f09a MK |
17 | .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description |
18 | .\" Addition of extra material on portability and standards. | |
fea681da | 19 | .\" |
4c1c5274 | 20 | .TH strerror 3 (date) "Linux man-pages (unreleased)" |
fea681da | 21 | .SH NAME |
15f0b7af AC |
22 | strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \- |
23 | return string describing error number | |
45d84983 AC |
24 | .SH LIBRARY |
25 | Standard C library | |
8fc3b2cf | 26 | .RI ( libc ", " \-lc ) |
fea681da MK |
27 | .SH SYNOPSIS |
28 | .nf | |
29 | .B #include <string.h> | |
68e4db0a | 30 | .PP |
fea681da | 31 | .BI "char *strerror(int " errnum ); |
d2c55aa7 MK |
32 | .BI "const char *strerrorname_np(int " errnum ); |
33 | .BI "const char *strerrordesc_np(int " errnum ); | |
68e4db0a | 34 | .PP |
1eed67e7 | 35 | .BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); |
f2667a72 | 36 | /* XSI-compliant */ |
68e4db0a | 37 | .PP |
1eed67e7 | 38 | .BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen ); |
f2667a72 | 39 | /* GNU-specific */ |
dbfe9c70 | 40 | .PP |
103357f7 | 41 | .BI "char *strerror_l(int " errnum ", locale_t " locale ); |
cc4615cc | 42 | .fi |
68e4db0a | 43 | .PP |
d39ad78f | 44 | .RS -4 |
cc4615cc MK |
45 | Feature Test Macro Requirements for glibc (see |
46 | .BR feature_test_macros (7)): | |
d39ad78f | 47 | .RE |
68e4db0a | 48 | .PP |
d2c55aa7 MK |
49 | .BR strerrorname_np (), |
50 | .BR strerrordesc_np (): | |
9d2adbae | 51 | .nf |
d2c55aa7 | 52 | _GNU_SOURCE |
9d2adbae | 53 | .fi |
d2c55aa7 | 54 | .PP |
103357f7 | 55 | .BR strerror_r (): |
9d2adbae MK |
56 | .nf |
57 | The XSI-compliant version is provided if: | |
5c10d2c5 | 58 | (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE |
9d2adbae MK |
59 | Otherwise, the GNU-specific version is provided. |
60 | .fi | |
fea681da | 61 | .SH DESCRIPTION |
60a90ecd MK |
62 | The |
63 | .BR strerror () | |
c9980d2e | 64 | function returns a pointer to a string that describes the error |
61d71e01 MK |
65 | code passed in the argument |
66 | .IR errnum , | |
67 | possibly using the | |
ec5a588f | 68 | .B LC_MESSAGES |
fea681da | 69 | part of the current locale to select the appropriate language. |
6fb29ca0 MK |
70 | (For example, if |
71 | .I errnum | |
72 | is | |
73 | .BR EINVAL , | |
926fc5d5 | 74 | the returned description will be "Invalid argument".) |
fea681da | 75 | This string must not be modified by the application, but may be |
60a90ecd | 76 | modified by a subsequent call to |
103357f7 MK |
77 | .BR strerror () |
78 | or | |
79 | .BR strerror_l (). | |
c99c1440 | 80 | No other library function, including |
8ca6ceb0 EB |
81 | .BR perror (3), |
82 | will modify this string. | |
d2c55aa7 MK |
83 | .PP |
84 | Like | |
85 | .BR strerror (), | |
86 | the | |
87 | .BR strerrordesc_np () | |
88 | function returns a pointer to a string that describes the error | |
89 | code passed in the argument | |
90 | .IR errnum , | |
91 | with the difference that the returned string is not translated | |
92 | according to the current locale. | |
93 | .PP | |
94 | The | |
95 | .BR strerrorname_np () | |
96 | function returns a pointer to a string containing the name of the error | |
97 | code passed in the argument | |
98 | .IR errnum . | |
99 | For example, given | |
1ae6b2c7 | 100 | .B EPERM |
d2c55aa7 | 101 | as an argument, this function returns a pointer to the string "EPERM". |
103357f7 | 102 | .\" |
5b436d02 | 103 | .SS strerror_r() |
60a90ecd MK |
104 | The |
105 | .BR strerror_r () | |
106 | function is similar to | |
107 | .BR strerror (), | |
108 | but is | |
c13182ef MK |
109 | thread safe. |
110 | This function is available in two versions: | |
cc4615cc | 111 | an XSI-compliant version specified in POSIX.1-2001 |
8ca6ceb0 | 112 | (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13), |
6e84dfa1 | 113 | and a GNU-specific version (available since glibc 2.0). |
cc4615cc MK |
114 | The XSI-compliant version is provided with the feature test macros |
115 | settings shown in the SYNOPSIS; | |
6e84dfa1 | 116 | otherwise the GNU-specific version is provided. |
cc4615cc MK |
117 | If no feature test macros are explicitly defined, |
118 | then (since glibc 2.4) | |
c4a256e2 | 119 | .B _POSIX_C_SOURCE |
cc4615cc MK |
120 | is defined by default with the value |
121 | 200112L, so that the XSI-compliant version of | |
122 | .BR strerror_r () | |
123 | is provided by default. | |
847e0d88 | 124 | .PP |
c13182ef MK |
125 | The XSI-compliant |
126 | .BR strerror_r () | |
6e84dfa1 MK |
127 | is preferred for portable applications. |
128 | It returns the error string in the user-supplied buffer | |
fea681da MK |
129 | .I buf |
130 | of length | |
6e84dfa1 | 131 | .IR buflen . |
847e0d88 | 132 | .PP |
c13182ef MK |
133 | The GNU-specific |
134 | .BR strerror_r () | |
6e84dfa1 MK |
135 | returns a pointer to a string containing the error message. |
136 | This may be either a pointer to a string that the function stores in | |
137 | .IR buf , | |
138 | or a pointer to some (immutable) static string | |
139 | (in which case | |
c13182ef | 140 | .I buf |
6e84dfa1 | 141 | is unused). |
c13182ef | 142 | If the function stores a string in |
6e84dfa1 MK |
143 | .IR buf , |
144 | then at most | |
145 | .I buflen | |
146 | bytes are stored (the string may be truncated if | |
147 | .I buflen | |
8ca6ceb0 EB |
148 | is too small and |
149 | .I errnum | |
150 | is unknown). | |
b957f81f | 151 | The string always includes a terminating null byte (\[aq]\e0\[aq]). |
103357f7 MK |
152 | .\" |
153 | .SS strerror_l() | |
154 | .BR strerror_l () | |
155 | is like | |
156 | .BR strerror (), | |
157 | but maps | |
158 | .I errnum | |
159 | to a locale-dependent error message in the locale specified by | |
160 | .IR locale . | |
161 | The behavior of | |
162 | .BR strerror_l () | |
163 | is undefined if | |
164 | .I locale | |
165 | is the special locale object | |
1ae6b2c7 | 166 | .B LC_GLOBAL_LOCALE |
103357f7 | 167 | or is not a valid locale object handle. |
47297adb | 168 | .SH RETURN VALUE |
60a90ecd | 169 | The |
103357f7 MK |
170 | .BR strerror (), |
171 | .BR strerror_l (), | |
2d50dd9e | 172 | and the GNU-specific |
60a90ecd MK |
173 | .BR strerror_r () |
174 | functions return | |
c13182ef | 175 | the appropriate error description string, |
6e84dfa1 | 176 | or an "Unknown error nnn" message if the error number is unknown. |
847e0d88 | 177 | .PP |
d2c55aa7 MK |
178 | On success, |
179 | .BR strerrorname_np () | |
180 | and | |
181 | .BR strerrordesc_np () | |
182 | return the appropriate error description string. | |
183 | If | |
184 | .I errnum | |
185 | is an invalid error number, these functions return NULL. | |
186 | .PP | |
103357f7 MK |
187 | The XSI-compliant |
188 | .BR strerror_r () | |
189 | function returns 0 on success. | |
190 | On error, | |
191 | a (positive) error number is returned (since glibc 2.13), | |
192 | or \-1 is returned and | |
193 | .I errno | |
b324e17d | 194 | is set to indicate the error (before glibc 2.13). |
847e0d88 | 195 | .PP |
f2682520 | 196 | POSIX.1-2001 and POSIX.1-2008 require that a successful call to |
563f4681 | 197 | .BR strerror () |
103357f7 MK |
198 | or |
199 | .BR strerror_l () | |
f2682520 MK |
200 | shall leave |
201 | .I errno | |
202 | unchanged, and note that, | |
203 | since no function return value is reserved to indicate an error, | |
204 | an application that wishes to check for errors should initialize | |
205 | .I errno | |
206 | to zero before the call, | |
207 | and then check | |
208 | .I errno | |
209 | after the call. | |
fea681da MK |
210 | .SH ERRORS |
211 | .TP | |
212 | .B EINVAL | |
213 | The value of | |
214 | .I errnum | |
215 | is not a valid error number. | |
216 | .TP | |
217 | .B ERANGE | |
218 | Insufficient storage was supplied to contain the error description string. | |
18b3fa61 | 219 | .SH ATTRIBUTES |
9cf2aed1 PH |
220 | For an explanation of the terms used in this section, see |
221 | .BR attributes (7). | |
222 | .TS | |
223 | allbox; | |
b32feea5 | 224 | lb lb lbx |
9cf2aed1 PH |
225 | l l l. |
226 | Interface Attribute Value | |
227 | T{ | |
9e54434e BR |
228 | .na |
229 | .nh | |
18b3fa61 | 230 | .BR strerror () |
b32feea5 | 231 | T} Thread safety T{ |
9e54434e BR |
232 | .na |
233 | .nh | |
b32feea5 MK |
234 | MT-Unsafe race:strerror |
235 | T} | |
9cf2aed1 | 236 | T{ |
9e54434e BR |
237 | .na |
238 | .nh | |
d2c55aa7 | 239 | .BR strerrorname_np (), |
73cf5b83 | 240 | .BR strerrordesc_np () |
d2c55aa7 MK |
241 | T} Thread safety MT-Safe |
242 | T{ | |
9e54434e BR |
243 | .na |
244 | .nh | |
9cf2aed1 PH |
245 | .BR strerror_r (), |
246 | .BR strerror_l () | |
247 | T} Thread safety MT-Safe | |
248 | .TE | |
c466875e | 249 | .sp 1 |
3113c7f3 | 250 | .SH STANDARDS |
4131356c | 251 | .TP |
60a90ecd | 252 | .BR strerror () |
4131356c AC |
253 | C11, POSIX.1-2008. |
254 | .TP | |
60a90ecd | 255 | .BR strerror_r () |
eaa8868c MK |
256 | .\" FIXME . for later review when Issue 8 is one day released... |
257 | .\" A future POSIX.1 may remove strerror_r() | |
258 | .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8 | |
259 | .\" http://austingroupbugs.net/view.php?id=508 | |
4131356c | 260 | .TQ |
103357f7 | 261 | .BR strerror_l () |
4131356c AC |
262 | POSIX.1-2008. |
263 | .TP | |
264 | .BR strerrorname_np () | |
265 | .TQ | |
d2c55aa7 | 266 | .BR strerrordesc_np () |
4131356c | 267 | GNU. |
847e0d88 | 268 | .PP |
68e1685c | 269 | POSIX.1-2001 permits |
6e84dfa1 | 270 | .BR strerror () |
c13182ef | 271 | to set |
6e84dfa1 | 272 | .I errno |
c13182ef | 273 | if the call encounters an error, but does not specify what |
6e84dfa1 MK |
274 | value should be returned as the function result in the event of an error. |
275 | On some systems, | |
276 | .\" e.g., Solaris 8, HP-UX 11 | |
277 | .BR strerror () | |
278 | returns NULL if the error number is unknown. | |
c13182ef | 279 | On other systems, |
6e84dfa1 MK |
280 | .\" e.g., FreeBSD 5.4, Tru64 5.1B |
281 | .BR strerror () | |
c13182ef | 282 | returns a string something like "Error nnn occurred" and sets |
6e84dfa1 | 283 | .I errno |
c13182ef | 284 | to |
6e84dfa1 MK |
285 | .B EINVAL |
286 | if the error number is unknown. | |
8ca6ceb0 | 287 | C99 and POSIX.1-2008 require the return value to be non-NULL. |
4131356c AC |
288 | .SH HISTORY |
289 | .TP | |
290 | .BR strerror () | |
291 | POSIX.1-2001, C89. | |
292 | .TP | |
293 | .BR strerror_r () | |
294 | POSIX.1-2001. | |
295 | .TP | |
296 | .BR strerror_l () | |
297 | glibc 2.6. | |
298 | POSIX.1-2008. | |
299 | .TP | |
300 | .BR strerrorname_np () | |
301 | .TQ | |
302 | .BR strerrordesc_np () | |
303 | glibc 2.32. | |
e9cf84ab | 304 | .SH NOTES |
5d048f53 | 305 | The GNU C Library uses a buffer of 1024 characters for |
e9cf84ab | 306 | .BR strerror (). |
154e01af | 307 | This buffer size therefore should be sufficient to avoid an |
e9cf84ab | 308 | .B ERANGE |
5d048f53 | 309 | error when calling |
9e6513b5 | 310 | .BR strerror_r (). |
d2c55aa7 MK |
311 | .PP |
312 | .BR strerrorname_np () | |
313 | and | |
314 | .BR strerrordesc_np () | |
315 | are thread-safe and async-signal-safe. | |
47297adb | 316 | .SH SEE ALSO |
d7871cf9 | 317 | .BR err (3), |
fea681da | 318 | .BR errno (3), |
37b6aec3 | 319 | .BR error (3), |
fea681da | 320 | .BR perror (3), |
103357f7 MK |
321 | .BR strsignal (3), |
322 | .BR locale (7) |