usr/src/man/man3c/strerror.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
  45 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\" Copyright 2015, Joyent, Inc.
  47 .\" Copyright 2024 Oxide Computer Company
  48 .\"
  49 .Dd April 6, 2024
  50 .Dt STRERROR 3C
  51 .Os
  52 .Sh NAME
  53 .Nm strerror ,
  54 .Nm strerror_r ,
  55 .Nm strerror_l ,
  56 .Nm strerrordesc_np ,
  57 .Nm strerrorname_np
  58 .Nd get error message string
  59 .Sh LIBRARY
  60 .Lb libc
  61 .Sh SYNOPSIS
  62 .In string.h
  63 .Ft "char *"
  64 .Fo strerror
  65 .Fa "int errnum"
  66 .Fc
  67 .Ft int
  68 .Fo strerror_r
  69 .Fa "int errnum"
  70 .Fa "char *strerrbuf"
  71 .Fa "size_t buflen"
  72 .Fc
  73 .Ft "char *"
  74 .Fo strerror_l
  75 .Fa "int errnum"
  76 .Fa "locale_t loc"
  77 .Fc
  78 .Ft "const char *"
  79 .Fo strerrordesc_np
  80 .Fa "int errnum"
  81 .Fc
  82 .Ft "const char *"
  83 .Fo strerrorname_np
  84 .Fa "int errnum"
  85 .Fc
  86 .Sh DESCRIPTION
  87 The
  88 .Fn strerror
  89 function maps the error number in
  90 .Fa errnum
  91 to an error message string, and returns a pointer to that string.
  92 It uses the same set of error messages as
  93 .Xr perror 3C .
  94 The returned string should not be overwritten.
  95 The string will be translated based on the current locale.
  96 .Pp
  97 The
  98 .Fn strerror_r
  99 function maps the error number in
 100 .Fa errnum
 101 to an error message string and returns the string in the buffer pointed to by
 102 .Fa strerrbuf
 103 with length
 104 .Fa buflen .
 105 .Pp
 106 The
 107 .Fn strerror_l
 108 function maps the error number in
 109 .Fa \fIerrnum\fR
 110 to an error message string in the locale indicated by
 111 .Fa loc .
 112 The returned string should not be overwritten.
 113 If
 114 .Fa loc
 115 is passed the
 116 .Dv NULL
 117 pointer, then the locale of the calling thread's current locale will be used
 118 instead, like
 119 .Fn strerror .
 120 .Pp
 121 Because the
 122 .Fn strerror
 123 and
 124 .Fn strerror_l
 125 functions, return localized strings in the event of an unknown error, one must
 126 use the value of
 127 .Va errno
 128 to detect an error.
 129 Callers should first set
 130 .Va errno
 131 to
 132 .Sy 0
 133 before the call to either function and then check the value of
 134 .Va errno
 135 after the call.
 136 If the value of
 137 .Va errno
 138 is non-zero then an error has occurred.
 139 .Pp
 140 The
 141 .Fn strerrordesc_np
 142 function behaves the same as
 143 .Fn strerror ,
 144 but will always return the error message string in the C locale and will
 145 not provide a translate message.
 146 Unlike
 147 .Fn strerror ,
 148 unknown error messages will return a
 149 .Dv NULL
 150 pointer.
 151 Clearing
 152 .Va errno
 153 prior to calling
 154 .Fn strerrordesc_np
 155 is still advised, as with
 156 .Fn strerror .
 157 .Pp
 158 The
 159 .Fn strerrorname_np
 160 function translates
 161 .Fa errnum
 162 into the string name of the error constant.
 163 For example:
 164 .Dq Er EIO ,
 165 .Dq Er EINTR ,
 166 etc.
 167 When passed the value of 0, there is no traditional error string.
 168 To match originating implementations, the string
 169 .Dq 0
 170 is returned in that case.
 171 .Sh RETURN VALUES
 172 Upon successful completion,
 173 .Fn strerror
 174 and
 175 .Fn strerror_l
 176 return a pointer to the generated message string.
 177 Otherwise, they set
 178 .Va errno
 179 and returns a pointer to an error message string.
 180 They return the localized string
 181 .Dq Unknown error
 182 if
 183 .Fa errnum
 184 is not a valid error number.
 185 .Pp
 186 Upon successful completion,
 187 .Fn strerror_r
 188 returns
 189 .Sy 0 .
 190 Otherwise it sets
 191 .Va errno
 192 and returns the value of
 193 .Va errno
 194 to indicate the error.
 195 It returns the localized string
 196 .Dq Unknown error
 197 in the buffer pointed to by
 198 .Fa strerrbuf
 199 if
 200 .Fa errnum
 201 is not a valid error number.
 202 .Pp
 203 Upon successful completion, the
 204 .Fn strerrordesc_np
 205 function returns the C locale's generated message string.
 206 Otherwise,
 207 .Dv NULL
 208 is returned and
 209 .Va errno
 210 is set.
 211 Unlike
 212 .Fn strerror ,
 213 this occurs when a string's translation is not known.
 214 .Pp
 215 Upon successful completion, the
 216 .Fn strerrorname_np
 217 function returns the C language constant name of the error.
 218 Otherwise,
 219 .Dv NULL
 220 is returned and
 221 .Va errno
 222 is set.
 223 .Sh ERRORS
 224 These functions may fail if:
 225 .Bl -tag -width Er
 226 .It Er EINVAL
 227 The value of
 228 .Fa errnum
 229 is not a valid error number.
 230 .El
 231 .Pp
 232 The
 233 .Fn strerror_r
 234 function may fail if:
 235 .Bl -tag -width Er
 236 .It Er ERANGE
 237 The
 238 .Fa buflen
 239 argument specifies insufficient storage to contain the generated message string.
 240 .El
 241 .Sh USAGE
 242 Messages returned from these functions
 243 .Po
 244 other than
 245 .Fn strerrordesc_np
 246 and
 247 .Fn strerrorname_np
 248 .Pc
 249 are in the native language specified by the
 250 .Dv LC_MESSAGES
 251 locale category.
 252 See
 253 .Xr setlocale 3C
 254 and
 255 .Xr uselocale 3C .
 256 .Sh INTERFACE STABILITY
 257 .Sy Committed
 258 .Sh MT-LEVEL
 259 .Sy Safe
 260 .Sh SEE ALSO
 261 .Xr gettext 3C ,
 262 .Xr perror 3C ,
 263 .Xr setlocale 3C ,
 264 .Xr uselocale 3C ,
 265 .Xr attributes 7 ,
 266 .Xr standards 7