original/man3/strerror.3

   1 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (C) 2005, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" References consulted:
  27 .\"     Linux libc source code
  28 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  29 .\"     386BSD man pages
  30 .\" Modified Sat Jul 24 18:05:30 1993 by Rik Faith <faith@cs.unc.edu>
  31 .\" Modified Fri Feb 16 14:25:17 1996 by Andries Brouwer <aeb@cwi.nl>
  32 .\" Modified Sun Jul 21 20:55:44 1996 by Andries Brouwer <aeb@cwi.nl>
  33 .\" Modified Mon Oct 15 21:16:25 2001 by John Levon <moz@compsoc.man.ac.uk>
  34 .\" Modified Tue Oct 16 00:04:43 2001 by Andries Brouwer <aeb@cwi.nl>
  35 .\" Modified Fri Jun 20 03:04:30 2003 by Andries Brouwer <aeb@cwi.nl>
  36 .\" 2005-12-13, mtk, Substantial rewrite of strerror_r() description
  37 .\"         Addition of extra material on portability and standards.
  38 .\"
  39 .TH STRERROR 3  2014-03-18 "" "Linux Programmer's Manual"
  40 .SH NAME
  41 strerror, strerror_r, strerror_l \- return string describing error number
  42 .SH SYNOPSIS
  43 .nf
  44 .B #include <string.h>
  45 .sp
  46 .BI "char *strerror(int " errnum );
  47 .sp
  48 .BI "int strerror_r(int " errnum ", char *" buf ", size_t " buflen );
  49             /* XSI-compliant */
  50 .sp
  51 .BI "char *strerror_r(int " errnum ", char *" buf ", size_t " buflen );
  52             /* GNU-specific */
  53
  54 .BI "char *strerror_l(int " errnum ", locale_t " locale );
  55 .fi
  56 .sp
  57 .in -4n
  58 Feature Test Macro Requirements for glibc (see
  59 .BR feature_test_macros (7)):
  60 .in
  61 .ad l
  62 .sp
  63 .BR strerror_r ():
  64 .RS 4
  65 The XSI-compliant version is provided if:
  66 .br
  67 (_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600) && !\ _GNU_SOURCE
  68 .br
  69 Otherwise, the GNU-specific version is provided.
  70 .RE
  71 .ad
  72 .SH DESCRIPTION
  73 The
  74 .BR strerror ()
  75 function returns a pointer to a string that describes the error
  76 code passed in the argument
  77 .IR errnum ,
  78 possibly using the
  79 .B LC_MESSAGES
  80 part of the current locale to select the appropriate language.
  81 (For example, if
  82 .I errnum
  83 is
  84 .BR EINVAL ,
  85 the returned description will be "Invalid argument".)
  86 This string must not be modified by the application, but may be
  87 modified by a subsequent call to
  88 .BR strerror ()
  89 or
  90 .BR strerror_l ().
  91 No other library function, including
  92 .BR perror (3),
  93 will modify this string.
  94 .\"
  95 .SS strerror_r()
  96 The
  97 .BR strerror_r ()
  98 function is similar to
  99 .BR strerror (),
 100 but is
 101 thread safe.
 102 This function is available in two versions:
 103 an XSI-compliant version specified in POSIX.1-2001
 104 (available since glibc 2.3.4, but not POSIX-compliant until glibc 2.13),
 105 and a GNU-specific version (available since glibc 2.0).
 106 The XSI-compliant version is provided with the feature test macros
 107 settings shown in the SYNOPSIS;
 108 otherwise the GNU-specific version is provided.
 109 If no feature test macros are explicitly defined,
 110 then (since glibc 2.4)
 111 .B _POSIX_SOURCE
 112 is defined by default with the value
 113 200112L, so that the XSI-compliant version of
 114 .BR strerror_r ()
 115 is provided by default.
 116
 117 The XSI-compliant
 118 .BR strerror_r ()
 119 is preferred for portable applications.
 120 It returns the error string in the user-supplied buffer
 121 .I buf
 122 of length
 123 .IR buflen .
 124
 125 The GNU-specific
 126 .BR strerror_r ()
 127 returns a pointer to a string containing the error message.
 128 This may be either a pointer to a string that the function stores in
 129 .IR buf ,
 130 or a pointer to some (immutable) static string
 131 (in which case
 132 .I buf
 133 is unused).
 134 If the function stores a string in
 135 .IR buf ,
 136 then at most
 137 .I buflen
 138 bytes are stored (the string may be truncated if
 139 .I buflen
 140 is too small and
 141 .I errnum
 142 is unknown).
 143 The string always includes a terminating null byte (\(aq\\0\(aq).
 144 .\"
 145 .SS strerror_l()
 146 .BR strerror_l ()
 147 is like
 148 .BR strerror (),
 149 but maps
 150 .I errnum
 151 to a locale-dependent error message in the locale specified by
 152 .IR locale .
 153 The behavior of
 154 .BR strerror_l ()
 155 is undefined if
 156 .I locale
 157 is the special locale object
 158 .BR LC_GLOBAL_LOCALE
 159 or is not a valid locale object handle.
 160 .SH RETURN VALUE
 161 The
 162 .BR strerror (),
 163 .BR strerror_l (),
 164 and the GNU-specific
 165 .BR strerror_r ()
 166 functions return
 167 the appropriate error description string,
 168 or an "Unknown error nnn" message if the error number is unknown.
 169
 170 The XSI-compliant
 171 .BR strerror_r ()
 172 function returns 0 on success.
 173 On error,
 174 a (positive) error number is returned (since glibc 2.13),
 175 or \-1 is returned and
 176 .I errno
 177 is set to indicate the error (glibc versions before 2.13).
 178
 179 POSIX.1-2001 and POSIX.1-2008 require that a successful call to
 180 .BR strerror ()
 181 or
 182 .BR strerror_l ()
 183 shall leave
 184 .I errno
 185 unchanged, and note that,
 186 since no function return value is reserved to indicate an error,
 187 an application that wishes to check for errors should initialize
 188 .I errno
 189 to zero before the call,
 190 and then check
 191 .I errno
 192 after the call.
 193 .SH ERRORS
 194 .TP
 195 .B EINVAL
 196 The value of
 197 .I errnum
 198 is not a valid error number.
 199 .TP
 200 .B ERANGE
 201 Insufficient storage was supplied to contain the error description string.
 202 .SH ATTRIBUTES
 203 .SS Multithreading (see pthreads(7))
 204 The
 205 .BR strerror ()
 206 function is not thread-safe.
 207 .LP
 208 The
 209 .BR strerror_r ()
 210 function is thread-safe.
 211 .\" FIXME Need a thread-safety statement about strerror_l()
 212 .SH VERSIONS
 213 The
 214 .BR strerror_l ()
 215 function first appeared in glibc 2.6.
 216 .SH CONFORMING TO
 217 .BR strerror ()
 218 is specified by POSIX.1-2001, POSIX.1-2008, C89, and C99.
 219 .BR strerror_r ()
 220 is specified by POSIX.1-2001 and POSIX.1-2008.
 221
 222 .BR strerror_l ()
 223 is specified in POSIX.1-2008.
 224
 225 The GNU-specific
 226 .BR strerror_r ()
 227 function is a nonstandard extension.
 228
 229 POSIX.1-2001 permits
 230 .BR strerror ()
 231 to set
 232 .I errno
 233 if the call encounters an error, but does not specify what
 234 value should be returned as the function result in the event of an error.
 235 On some systems,
 236 .\" e.g., Solaris 8, HP-UX 11
 237 .BR strerror ()
 238 returns NULL if the error number is unknown.
 239 On other systems,
 240 .\" e.g., FreeBSD 5.4, Tru64 5.1B
 241 .BR strerror ()
 242 returns a string something like "Error nnn occurred" and sets
 243 .I errno
 244 to
 245 .B EINVAL
 246 if the error number is unknown.
 247 C99 and POSIX.1-2008 require the return value to be non-NULL.
 248 .SH SEE ALSO
 249 .BR err (3),
 250 .BR errno (3),
 251 .BR error (3),
 252 .BR perror (3),
 253 .BR strsignal (3),
 254 .BR locale (7)
 255 .SH COLOPHON
 256 This page is part of release 3.67 of the Linux
 257 .I man-pages
 258 project.
 259 A description of the project,
 260 information about reporting bugs,
 261 and the latest version of this page,
 262 can be found at
 263 \%http://www.kernel.org/doc/man\-pages/.