lib/libc/string/strerror.3

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