man3/strerror.3

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