Debian Codegraph @

upstream/debian-trixie/man3/strerror.3

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