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 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)strerror.3  8.1 (Berkeley) 6/9/93
  33 .\" $FreeBSD: src/lib/libc/string/strerror.3,v 1.24 2007/01/09 00:28:12 imp Exp $
  34 .\" $DragonFly: src/lib/libc/string/strerror.3,v 1.2 2003/06/17 04:26:46 dillon Exp $
  35 .\"
  36 .Dd October 12, 2004
  37 .Dt STRERROR 3
  38 .Os
  39 .Sh NAME
  40 .Nm perror ,
  41 .Nm strerror ,
  42 .Nm strerror_r ,
  43 .Nm sys_errlist ,
  44 .Nm sys_nerr
  45 .Nd system error messages
  46 .Sh LIBRARY
  47 .Lb libc
  48 .Sh SYNOPSIS
  49 .In stdio.h
  50 .Ft void
  51 .Fn perror "const char *string"
  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 error message string corresponding to an
  66 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 null 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 return an error message
 103 string containing
 104 .Dq Li "Unknown error:\ "
 105 followed by the error number in decimal.
 106 The
 107 .Fn strerror
 108 and
 109 .Fn strerror_r
 110 functions return
 111 .Er EINVAL
 112 as a warning.
 113 Error numbers recognized by this implementation fall in
 114 the range 0 <
 115 .Fa errnum
 116 <
 117 .Fa sys_nerr .
 118 .Pp
 119 If insufficient storage is provided in
 120 .Fa strerrbuf
 121 (as specified in
 122 .Fa buflen )
 123 to contain the error string,
 124 .Fn strerror_r
 125 returns
 126 .Er ERANGE
 127 and
 128 .Fa strerrbuf
 129 will contain an error message that has been truncated and
 130 .Dv NUL
 131 terminated to fit the length specified by
 132 .Fa buflen .
 133 .Pp
 134 The message strings can be accessed directly using the external
 135 array
 136 .Va sys_errlist .
 137 The external value
 138 .Va sys_nerr
 139 contains a count of the messages in
 140 .Va sys_errlist .
 141 The use of these variables is deprecated;
 142 .Fn strerror
 143 or
 144 .Fn strerror_r
 145 should be used instead.
 146 .Sh SEE ALSO
 147 .Xr intro 2 ,
 148 .Xr psignal 3
 149 .Sh STANDARDS
 150 The
 151 .Fn perror
 152 and
 153 .Fn strerror
 154 functions conform to
 155 .St -isoC-99 .
 156 The
 157 .Fn strerror_r
 158 function conforms to
 159 .St -p1003.1-2001 .
 160 .Sh HISTORY
 161 The
 162 .Fn strerror
 163 and
 164 .Fn perror
 165 functions first appeared in
 166 .Bx 4.4 .
 167 The
 168 .Fn strerror_r
 169 function was implemented in
 170 .Fx 4.4
 171 by
 172 .An Wes Peters Aq wes@FreeBSD.org .
 173 .Sh BUGS
 174 For unknown error numbers, the
 175 .Fn strerror
 176 function will return its result in a static buffer which
 177 may be overwritten by subsequent calls.
 178 .Pp
 179 The return type for
 180 .Fn strerror
 181 is missing a type-qualifier; it should actually be
 182 .Vt const char * .
 183 .Pp
 184 Programs that use the deprecated
 185 .Va sys_errlist
 186 variable often fail to compile because they declare it
 187 inconsistently.