man3/errno.3

   1 .\" Copyright (c) 1996 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" The GNU General Public License's references to "object code"
   9 .\" and "executables" are to be interpreted as the output of any
  10 .\" document formatting or typesetting system, including
  11 .\" intermediate and printed output.
  12 .\"
  13 .\" This manual is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, write to the Free
  20 .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111,
  21 .\" USA.
  22 .\"
  23 .\" 5 Oct 2002, Modified by Michael Kerrisk <mtk-manpages@gmx.net>
  24 .\"     Updated for POSIX 1003.1 2001
  25 .\" 2004-12-17 Martin Schulze <joey@infodrom.org>, mtk
  26 .\"     Removed errno declaration prototype, added notes
  27 .\"
  28 .TH ERRNO 3 2004-12-17 "" "Library functions"
  29 .SH NAME
  30 errno \- number of last error
  31 .SH SYNOPSIS
  32 .B #include <errno.h>
  33 .\".sp
  34 .\".BI "extern int " errno ;
  35 .SH DESCRIPTION
  36 The
  37 .I <errno.h>
  38 header file defines the integer variable
  39 .BR errno ,
  40 which is set by system calls and some library functions in the event
  41 of an error to indicate what went wrong.
  42 Its value is significant only when the call
  43 returned an error (usually \-1), and a function that does succeed
  44 is allowed to change
  45 .BR errno .
  46
  47 Sometimes, when \-1 is also a valid successful return value
  48 one has to zero
  49 .B errno
  50 before the call in order to detect possible errors.
  51
  52 \fBerrno\fR is defined by the ISO C standard to be a modifiable lvalue
  53 of type \fBint\fR, and must not be explicitly declared; \fBerrno\fR
  54 may be a macro.  \fBerrno\fR is thread-local; setting it in one thread
  55 does not affect its value in any other thread.
  56
  57 Valid error numbers are all non-zero; \fBerrno\fR is never set to zero
  58 by any library function.  All the error names specified by POSIX.1
  59 must have distinct values, with the exception of
  60 .B EAGAIN
  61 and
  62 .BR EWOULDBLOCK ,
  63 which may be the same.
  64
  65 .\" FIXME EILSEQ is in C99.
  66 POSIX.1 (2001 edition) lists the following symbolic error names.  Of
  67 these, \fBEDOM\fR and \fBERANGE\fR are in the ISO C standard.  ISO C
  68 Amendment 1 defines the additional error number \fBEILSEQ\fR for
  69 coding errors in multibyte or wide characters.
  70
  71 .\" FIXME The following list is far from complete
  72 .TP
  73 .B E2BIG
  74 Arg list too long
  75 .TP
  76 .B EACCES
  77 Permission denied
  78 .TP
  79 .B EADDRINUSE
  80 Address in use
  81 .TP
  82 .B EADDRNOTAVAIL
  83 Address not available
  84 .TP
  85 .B EAFNOSUPPORT
  86 Address family not supported
  87 .TP
  88 .B EAGAIN
  89 Resource temporarily unavailable
  90 .TP
  91 .B EALREADY
  92 Connection already in progress
  93 .TP
  94 .B EBADF
  95 Bad file descriptor
  96 .TP
  97 .B EBADMSG
  98 Bad message
  99 .TP
 100 .B EBUSY
 101 Resource busy
 102 .TP
 103 .B ECANCELED
 104 Operation canceled
 105 .TP
 106 .B ECHILD
 107 No child processes
 108 .TP
 109 .B ECONNABORTED
 110 Connection aborted
 111 .TP
 112 .B ECONNREFUSED
 113 Connection refused
 114 .TP
 115 .B ECONNRESET
 116 Connection reset
 117 .TP
 118 .B EDEADLK
 119 Resource deadlock avoided
 120 .TP
 121 .B EDESTADDRREQ
 122 Destination address required
 123 .TP
 124 .B EDOM
 125 Domain error
 126 .TP
 127 .B EDQUOT
 128 Reserved
 129 .TP
 130 .B EEXIST
 131 File exists
 132 .TP
 133 .B EFAULT
 134 Bad address
 135 .TP
 136 .B EFBIG
 137 File too large
 138 .TP
 139 .B EHOSTUNREACH
 140 Host is unreachable
 141 .TP
 142 .B EIDRM
 143 Identifier removed
 144 .TP
 145 .B EILSEQ
 146 Illegal byte sequence
 147 .TP
 148 .B EINPROGRESS
 149 Operation in progress
 150 .TP
 151 .B EINTR
 152 Interrupted function call
 153 .TP
 154 .B EINVAL
 155 Invalid argument
 156 .TP
 157 .B EIO
 158 Input/output error
 159 .TP
 160 .B EISCONN
 161 Socket is connected
 162 .TP
 163 .B EISDIR
 164 Is a directory
 165 .TP
 166 .B ELOOP
 167 Too many levels of symbolic links
 168 .TP
 169 .B EMFILE
 170 Too many open files
 171 .TP
 172 .B EMLINK
 173 Too many links
 174 .TP
 175 .B EMSGSIZE
 176 Inappropriate message buffer length
 177 .TP
 178 .B EMULTIHOP
 179 Reserved
 180 .TP
 181 .B ENAMETOOLONG
 182 Filename too long
 183 .TP
 184 .B ENETDOWN
 185 Network is down
 186 .TP
 187 .B ENETRESET
 188 Connection aborted by network
 189 .TP
 190 .B ENETUNREACH
 191 Network unreachable
 192 .TP
 193 .B ENFILE
 194 Too many open files in system
 195 .TP
 196 .B ENOBUFS
 197 No buffer space available
 198 .\" ENODATA is part of XSR option
 199 .TP
 200 .B ENODATA
 201 No message is available on the STREAM head read queue
 202 .TP
 203 .B ENODEV
 204 No such device
 205 .TP
 206 .B ENOENT
 207 No such file or directory
 208 .TP
 209 .B ENOEXEC
 210 Exec format error
 211 .TP
 212 .B ENOLCK
 213 No locks available
 214 .TP
 215 .B ENOLINK
 216 Reserved
 217 .TP
 218 .B ENOMEM
 219 Not enough space
 220 .TP
 221 .B ENOMSG
 222 No message of the desired type
 223 .TP
 224 .B ENOPROTOOPT
 225 Protocol not available
 226 .TP
 227 .B ENOSPC
 228 No space left on device
 229 .\" ENOSR is part of XSR option
 230 .TP
 231 .B ENOSR
 232 No STREAM resources
 233 .\" ENOSTR is part of XSR option
 234 .TP
 235 .B ENOSTR
 236 Not a STREAM
 237 .TP
 238 .B ENOSYS
 239 Function not implemented
 240 .TP
 241 .B ENOTCONN
 242 The socket is not connected
 243 .TP
 244 .B ENOTDIR
 245 Not a directory
 246 .TP
 247 .B ENOTEMPTY
 248 Directory not empty
 249 .TP
 250 .B ENOTSOCK
 251 Not a socket
 252 .TP
 253 .B ENOTSUP
 254 Not supported
 255 .TP
 256 .B ENOTTY
 257 Inappropriate I/O control operation
 258 .TP
 259 .B ENXIO
 260 No such device or address
 261 .TP
 262 .B EOPNOTSUPP
 263 Operation not supported on socket
 264 .TP
 265 .B EOVERFLOW
 266 Value too large to be stored in data type
 267 .TP
 268 .B EPERM
 269 Operation not permitted
 270 .TP
 271 .B EPIPE
 272 Broken pipe
 273 .TP
 274 .B EPROTO
 275 Protocol error
 276 .TP
 277 .B EPROTONOSUPPORT
 278 Protocol not supported
 279 .TP
 280 .B EPROTOTYPE
 281 Protocol wrong type for socket
 282 .TP
 283 .B ERANGE
 284 Result too large
 285 .TP
 286 .B EROFS
 287 Read-only file system
 288 .TP
 289 .B ESPIPE
 290 Invalid seek
 291 .TP
 292 .B ESRCH
 293 No such process
 294 .TP
 295 .B ESTALE
 296 Stale file handle
 297 .\" Can occur for NFS and for other file systems
 298 .\" ETIME is part of XSR option
 299 .TP
 300 .B ETIME
 301 STREAM
 302 .BR ioctl ()
 303 timeout
 304 .TP
 305 .B ETIMEDOUT
 306 Operation timed out
 307 .TP
 308 .B ETXTBSY
 309 Text file busy
 310 .TP
 311 .B EWOULDBLOCK
 312 Operation would block (may be same value as
 313 .BR EAGAIN )
 314 .TP
 315 .B EXDEV
 316 Improper link
 317 .SH NOTES
 318 A common mistake is to do
 319 .RS
 320 .nf
 321
 322 if (somecall() == \-1) {
 323     printf("somecall() failed\en");
 324     if (errno == ...) { ... }
 325 }
 326
 327 .fi
 328 .RE
 329 where
 330 .I errno
 331 no longer needs to have the value it had upon return from
 332 .IR somecall ()
 333 (i.e., it may have been changed by the
 334 .BR printf ()).
 335 If the value of
 336 .I errno
 337 should be preserved across a library call, it must be saved:
 338 .RS
 339 .nf
 340
 341 if (somecall() == \-1) {
 342     int errsv = errno;
 343     printf("somecall() failed\en");
 344     if (errsv == ...) { ... }
 345 }
 346 .fi
 347 .RE
 348 .PP
 349 It was common in traditional C to declare
 350 .I errno
 351 manually
 352 (i.e.,
 353 .IR "extern int errno" )
 354 instead of including
 355 .IR <errno.h> .
 356 .BR "Do not do this" .
 357 It will not work with modern versions of the C library.
 358 However, on (very) old Unix systems, there may be no
 359 .I <errno.h>
 360 and the declaration is needed.
 361 .SH "SEE ALSO"
 362 .BR perror (3),
 363 .BR strerror (3)