lib/libc/string/strerror.3

   1 .\" $NetBSD: strerror.3,v 1.14 2006/05/22 21:55:01 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 May 22, 2006
  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 .Pp
 102 If the error number is not recognized, these functions pass an error message
 103 string containing
 104 .Dq Li "Unknown error:\ "
 105 followed by the error number in decimal.
 106 To warn about this,
 107 .Fn strerror
 108 sets
 109 .Dv errno
 110 to
 111 .Er EINVAL ,
 112 and
 113 .Fn strerror_r
 114 returns
 115 .Er EINVAL .
 116 Error numbers recognized by this implementation fall in
 117 the range 0 \*[Lt]
 118 .Fa errnum
 119 \*[Lt]
 120 .Fa sys_nerr .
 121 .Pp
 122 If insufficient storage is provided in
 123 .Fa strerrbuf
 124 (as specified in
 125 .Fa buflen )
 126 to contain the error string,
 127 .Fn strerror_r
 128 returns
 129 .Er ERANGE
 130 and
 131 .Fa strerrbuf
 132 will contain an error message that has been truncated and
 133 .Dv NUL
 134 terminated to fit the length specified by
 135 .Fa buflen .
 136 .Pp
 137 The message strings can be accessed directly using the external
 138 array
 139 .Va sys_errlist .
 140 The external value
 141 .Va sys_nerr
 142 contains a count of the messages in
 143 .Va sys_errlist .
 144 The use of these variables is deprecated;
 145 .Fn strerror
 146 or
 147 .Fn strerror_r
 148 should be used instead.
 149 .Sh SEE ALSO
 150 .Xr intro 2 ,
 151 .Xr psignal 3
 152 .Sh STANDARDS
 153 The
 154 .Fn perror
 155 and
 156 .Fn strerror
 157 functions conform to
 158 .St -isoC-99 .
 159 The
 160 .Fn strerror_r
 161 function conforms to
 162 .St -p1003.1-2001 .
 163 .Sh HISTORY
 164 The
 165 .Fn strerror
 166 and
 167 .Fn perror
 168 functions first appeared in
 169 .Bx 4.4 .
 170 The
 171 .Fn strerror_r
 172 function first appeared in
 173 .Nx 4.0 .
 174 .Sh BUGS
 175 For unknown error numbers, the
 176 .Fn strerror
 177 function will return its result in a static buffer which
 178 may be overwritten by subsequent calls.
 179 .Pp
 180 The return type for
 181 .Fn strerror
 182 is missing a type-qualifier; it should actually be
 183 .Vt const char * .
 184 .Pp
 185 Programs that use the deprecated
 186 .Va sys_errlist
 187 variable often fail to compile because they declare it
 188 inconsistently.