Debian Codegraph @

upstream/debian-unstable/man3/strerror.3

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