lib/libc/string/strerror.3

   1 .\" $NetBSD: strerror.3,v 1.17 2010/10/25 07:37:11 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)strerror.3  8.1 (Berkeley) 6/9/93
  35 .Dd October 24, 2010
  36 .Dt STRERROR 3
  37 .Os
  38 .Sh NAME
  39 .Nm perror ,
  40 .Nm strerror ,
  41 .Nm strerror_r ,
  42 .Nm sys_errlist ,
  43 .Nm sys_nerr
  44 .Nd system error messages
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In stdio.h
  49 .Ft void
  50 .Fn perror "const char *string"
  51 .In errno.h
  52 .Vt extern const char * const sys_errlist[] ;
  53 .Vt extern const int sys_nerr ;
  54 .In string.h
  55 .Ft "char *"
  56 .Fn strerror "int errnum"
  57 .Ft int
  58 .Fn strerror_r "int errnum" "char *strerrbuf" "size_t buflen"
  59 .Sh DESCRIPTION
  60 The
  61 .Fn strerror ,
  62 .Fn strerror_r ,
  63 and
  64 .Fn perror
  65 functions look up the language-dependent error message
  66 string corresponding to an error number.
  67 .Pp
  68 The
  69 .Fn strerror
  70 function accepts an error number argument
  71 .Fa errnum
  72 and returns a pointer to the corresponding
  73 message string.
  74 .Pp
  75 The
  76 .Fn strerror_r
  77 function renders the same result into
  78 .Fa strerrbuf
  79 for a maximum of
  80 .Fa buflen
  81 characters and returns 0 upon success.
  82 .Pp
  83 The
  84 .Fn perror
  85 function finds the error message corresponding to the current
  86 value of the global variable
  87 .Va errno
  88 .Pq Xr intro 2
  89 and writes it, followed by a newline, to the
  90 standard error file descriptor.
  91 If the argument
  92 .Fa string
  93 is
  94 .Pf non- Dv NULL
  95 and does not point to the nul character,
  96 this string is prepended to the message
  97 string and separated from it by
  98 a colon and space
  99 .Pq Dq Li ":\ " ;
 100 otherwise, only the error message string is printed.
 101 Note that in most cases the
 102 .Xr err 3
 103 and
 104 .Xr warn 3
 105 family of functions is preferable to
 106 .Fn perror ;
 107 they are more flexible and also print the program name.
 108 .Pp
 109 If the error number is not recognized, these functions pass an error message
 110 string containing
 111 .Dq Li "Unknown error:\ "
 112 followed by the error number in decimal.
 113 To warn about this,
 114 .Fn strerror
 115 sets
 116 .Dv errno
 117 to
 118 .Er EINVAL ,
 119 and
 120 .Fn strerror_r
 121 returns
 122 .Er EINVAL .
 123 Error numbers recognized by this implementation fall in
 124 the range 0 \*[Lt]
 125 .Fa errnum
 126 \*[Lt]
 127 .Fa sys_nerr .
 128 .Pp
 129 If insufficient storage is provided in
 130 .Fa strerrbuf
 131 (as specified in
 132 .Fa buflen )
 133 to contain the error string,
 134 .Fn strerror_r
 135 returns
 136 .Er ERANGE
 137 and
 138 .Fa strerrbuf
 139 will contain an error message that has been truncated and
 140 .Dv NUL
 141 terminated to fit the length specified by
 142 .Fa buflen .
 143 .Pp
 144 The message strings can be accessed directly using the external
 145 array
 146 .Va sys_errlist .
 147 The external value
 148 .Va sys_nerr
 149 contains a count of the messages in
 150 .Va sys_errlist .
 151 The use of these variables is deprecated;
 152 .Fn strerror
 153 or
 154 .Fn strerror_r
 155 should be used instead.
 156 .Sh SEE ALSO
 157 .Xr intro 2 ,
 158 .Xr err 3 ,
 159 .Xr psignal 3 ,
 160 .Xr warn 3
 161 .Sh STANDARDS
 162 The
 163 .Fn perror
 164 and
 165 .Fn strerror
 166 functions conform to
 167 .St -isoC-99 .
 168 The
 169 .Fn strerror_r
 170 function conforms to
 171 .St -p1003.1-2001 .
 172 .Sh HISTORY
 173 The
 174 .Fn strerror
 175 and
 176 .Fn perror
 177 functions first appeared in
 178 .Bx 4.4 .
 179 The
 180 .Fn strerror_r
 181 function first appeared in
 182 .Nx 4.0 .
 183 .Sh BUGS
 184 For unknown error numbers, the
 185 .Fn strerror
 186 function will return its result in a static buffer which
 187 may be overwritten by subsequent calls.
 188 .Pp
 189 The return type for
 190 .Fn strerror
 191 is missing a type-qualifier; it should actually be
 192 .Vt const char * .
 193 .Pp
 194 Programs that use the deprecated
 195 .Va sys_errlist
 196 variable often fail to compile because they declare it
 197 inconsistently.