2 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
3 .\" and Copyright (C) 2005, 2014, 2020 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\" References consulted:
8 .\" Linux libc source code
9 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
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>
17 .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
18 .\" Addition of extra material on portability and standards.
20 .TH strerror 3 (date) "Linux man-pages (unreleased)"
22 strerror, strerrorname_np, strerrordesc_np, strerror_r, strerror_l \-
23 return string describing error number
26 .RI ( libc ", " \-lc )
29 .B #include <string.h>
31 .BI "char *strerror(int " errnum );
32 .BI "const char *strerrorname_np(int " errnum );
33 .BI "const char *strerrordesc_np(int " errnum );
35 .BI "int strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen );
38 .BI "char *strerror_r(int " errnum ", char " buf [. buflen "], size_t " buflen );
41 .BI "char *strerror_l(int " errnum ", locale_t " locale );
45 Feature Test Macro Requirements for glibc (see
46 .BR feature_test_macros (7)):
49 .BR strerrorname_np (),
50 .BR strerrordesc_np ():
57 The XSI-compliant version is provided if:
58 (_POSIX_C_SOURCE >= 200112L) && ! _GNU_SOURCE
59 Otherwise, the GNU-specific version is provided.
64 function returns a pointer to a string that describes the error
65 code passed in the argument
69 part of the current locale to select the appropriate language.
74 the returned description will be "Invalid argument".)
75 This string must not be modified by the application, but may be
76 modified by a subsequent call to
80 No other library function, including
82 will modify this string.
87 .BR strerrordesc_np ()
88 function returns a pointer to a string that describes the error
89 code passed in the argument
91 with the difference that the returned string is not translated
92 according to the current locale.
95 .BR strerrorname_np ()
96 function returns a pointer to a string containing the name of the error
97 code passed in the argument
101 as an argument, this function returns a pointer to the string "EPERM".
106 function is similar to
110 This function is available in two versions:
111 an XSI-compliant version specified in POSIX.1-2001
112 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13),
113 and a GNU-specific version (available since glibc 2.0).
114 The XSI-compliant version is provided with the feature test macros
115 settings shown in the SYNOPSIS;
116 otherwise the GNU-specific version is provided.
117 If no feature test macros are explicitly defined,
118 then (since glibc 2.4)
120 is defined by default with the value
121 200112L, so that the XSI-compliant version of
123 is provided by default.
127 is preferred for portable applications.
128 It returns the error string in the user-supplied buffer
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
138 or a pointer to some (immutable) static string
142 If the function stores a string in
146 bytes are stored (the string may be truncated if
151 The string always includes a terminating null byte (\[aq]\e0\[aq]).
159 to a locale-dependent error message in the locale specified by
165 is the special locale object
167 or is not a valid locale object handle.
175 the appropriate error description string,
176 or an "Unknown error nnn" message if the error number is unknown.
179 .BR strerrorname_np ()
181 .BR strerrordesc_np ()
182 return the appropriate error description string.
185 is an invalid error number, these functions return NULL.
189 function returns 0 on success.
191 a (positive) error number is returned (since glibc 2.13),
192 or \-1 is returned and
194 is set to indicate the error (before glibc 2.13).
196 POSIX.1-2001 and POSIX.1-2008 require that a successful call to
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
206 to zero before the call,
215 is not a valid error number.
218 Insufficient storage was supplied to contain the error description string.
222 function first appeared in glibc 2.6.
225 .BR strerrorname_np ()
227 .BR strerrordesc_np ()
228 functions first appeared in glibc 2.32.
230 For an explanation of the terms used in this section, see
238 Interface Attribute Value
242 MT-Unsafe race:strerror
245 .BR strerrorname_np (),
246 .BR strerrordesc_np ()
247 T} Thread safety MT-Safe
251 T} Thread safety MT-Safe
258 is specified by POSIX.1-2001, POSIX.1-2008, and C99.
260 is specified by POSIX.1-2001 and POSIX.1-2008.
261 .\" FIXME . for later review when Issue 8 is one day released...
262 .\" A future POSIX.1 may remove strerror_r()
263 .\" http://austingroupbugs.net/tag_view_page.php?tag_id=8
264 .\" http://austingroupbugs.net/view.php?id=508
267 is specified in POSIX.1-2008.
269 The GNU-specific functions
271 .BR strerrorname_np (),
273 .BR strerrordesc_np ()
274 are nonstandard extensions.
280 if the call encounters an error, but does not specify what
281 value should be returned as the function result in the event of an error.
283 .\" e.g., Solaris 8, HP-UX 11
285 returns NULL if the error number is unknown.
287 .\" e.g., FreeBSD 5.4, Tru64 5.1B
289 returns a string something like "Error nnn occurred" and sets
293 if the error number is unknown.
294 C99 and POSIX.1-2008 require the return value to be non-NULL.
296 The GNU C Library uses a buffer of 1024 characters for
298 This buffer size therefore should be sufficient to avoid an
303 .BR strerrorname_np ()
305 .BR strerrordesc_np ()
306 are thread-safe and async-signal-safe.