original/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@gmail.com>
  24 .\"     Updated for POSIX.1 2001
  25 .\" 2004-12-17 Martin Schulze <joey@infodrom.org>, mtk
  26 .\"     Removed errno declaration prototype, added notes
  27 .\" 2006-02-09 Kurt Wall, mtk
  28 .\"     Added non-POSIX errors
  29 .\"
  30 .TH ERRNO 3 2008-07-09 "" "Linux Programmer's Manual"
  31 .SH NAME
  32 errno \- number of last error
  33 .SH SYNOPSIS
  34 .B #include <errno.h>
  35 .\".sp
  36 .\".BI "extern int " errno ;
  37 .SH DESCRIPTION
  38 The
  39 .I <errno.h>
  40 header file defines the integer variable
  41 .IR errno ,
  42 which is set by system calls and some library functions in the event
  43 of an error to indicate what went wrong.
  44 Its value is significant only when the return value of
  45 the call indicated an error
  46 (i.e., \-1 from most system calls;
  47 \-1 or NULL from most library functions);
  48 a function that succeeds
  49 .I is
  50 allowed to change
  51 .IR errno .
  52
  53 Valid error numbers are all nonzero; \fIerrno\fP is never set to zero
  54 by any system call or library function.
  55
  56 For some system calls and library functions (e.g.,
  57 .BR getpriority (2)),
  58 \-1 is a valid return on success.
  59 In such cases, a successful return can be distinguished from an error
  60 return by setting
  61 .I errno
  62 to zero before the call, and then,
  63 if the call returns a status that indicates that an error
  64 may have occurred, checking to see if
  65 .I errno
  66 has a nonzero value.
  67
  68 \fIerrno\fP is defined by the ISO C standard to be a modifiable lvalue
  69 of type \fIint\fP, and must not be explicitly declared; \fIerrno\fP
  70 may be a macro.
  71 \fIerrno\fP is thread-local; setting it in one thread
  72 does not affect its value in any other thread.
  73
  74 All the error names specified by POSIX.1
  75 must have distinct values, with the exception of
  76 .B EAGAIN
  77 and
  78 .BR EWOULDBLOCK ,
  79 which may be the same.
  80
  81 .\" The following is now
  82 .\" POSIX.1 (2001 edition) lists the following symbolic error names.  Of
  83 .\" these, \fBEDOM\fP and \fBERANGE\fP are in the ISO C standard.  ISO C
  84 .\" Amendment 1 defines the additional error number \fBEILSEQ\fP for
  85 .\" coding errors in multibyte or wide characters.
  86 .\"
  87 Below is a list of the symbolic error names that are defined on Linux.
  88 Some of these are marked
  89 .IR POSIX.1 ,
  90 indicating that the name is defined by POSIX.1-2001, or
  91 .IR C99 ,
  92 indicating that the name is defined by C99.
  93 .TP 16
  94 .B E2BIG
  95 Argument list too long (POSIX.1)
  96 .TP
  97 .B EACCES
  98 Permission denied (POSIX.1)
  99 .TP
 100 .B EADDRINUSE
 101 Address already in use (POSIX.1)
 102 .TP
 103 .B EADDRNOTAVAIL
 104 Address not available (POSIX.1)
 105 .\" EADV is only an error on HURD(?)
 106 .TP
 107 .B EAFNOSUPPORT
 108 Address family not supported (POSIX.1)
 109 .TP
 110 .B EAGAIN
 111 Resource temporarily unavailable (may be the same value as
 112 .BR EWOULDBLOCK )
 113 (POSIX.1)
 114 .TP
 115 .B EALREADY
 116 Connection already in progress (POSIX.1)
 117 .TP
 118 .B EBADE
 119 Invalid exchange
 120 .TP
 121 .B EBADF
 122 Bad file descriptor (POSIX.1)
 123 .TP
 124 .B EBADFD
 125 File descriptor in bad state
 126 .TP
 127 .B EBADMSG
 128 Bad message (POSIX.1)
 129 .TP
 130 .B EBADR
 131 Invalid request descriptor
 132 .TP
 133 .B EBADRQC
 134 Invalid request code
 135 .TP
 136 .B EBADSLT
 137 Invalid slot
 138 .\" EBFONT is defined but appears not to be used by kernel or glibc.
 139 .TP
 140 .B EBUSY
 141 Device or resource busy (POSIX.1)
 142 .TP
 143 .B ECANCELED
 144 Operation canceled (POSIX.1)
 145 .TP
 146 .B ECHILD
 147 No child processes (POSIX.1)
 148 .TP
 149 .B ECHRNG
 150 Channel number out of range
 151 .TP
 152 .B ECOMM
 153 Communication error on send
 154 .TP
 155 .B ECONNABORTED
 156 Connection aborted (POSIX.1)
 157 .TP
 158 .B ECONNREFUSED
 159 Connection refused (POSIX.1)
 160 .TP
 161 .B ECONNRESET
 162 Connection reset (POSIX.1)
 163 .TP
 164 .B EDEADLK
 165 Resource deadlock avoided (POSIX.1)
 166 .TP
 167 .B EDEADLOCK
 168 Synonym for
 169 .B EDEADLK
 170 .TP
 171 .B EDESTADDRREQ
 172 Destination address required (POSIX.1)
 173 .TP
 174 .B EDOM
 175 Mathematics argument out of domain of function (POSIX.1, C99)
 176 .\" EDOTDOT is defined but appears to be unused
 177 .TP
 178 .B EDQUOT
 179 .\" POSIX just says "Reserved"
 180 Disk quota exceeded (POSIX.1)
 181 .TP
 182 .B EEXIST
 183 File exists (POSIX.1)
 184 .TP
 185 .B EFAULT
 186 Bad address (POSIX.1)
 187 .TP
 188 .B EFBIG
 189 File too large (POSIX.1)
 190 .TP
 191 .B EHOSTDOWN
 192 Host is down
 193 .TP
 194 .B EHOSTUNREACH
 195 Host is unreachable (POSIX.1)
 196 .TP
 197 .B EIDRM
 198 Identifier removed (POSIX.1)
 199 .TP
 200 .B EILSEQ
 201 Illegal byte sequence (POSIX.1, C99)
 202 .TP
 203 .B EINPROGRESS
 204 Operation in progress (POSIX.1)
 205 .TP
 206 .B EINTR
 207 Interrupted function call (POSIX.1); see
 208 .BR signal (7).
 209 .TP
 210 .B EINVAL
 211 Invalid argument (POSIX.1)
 212 .TP
 213 .B EIO
 214 Input/output error (POSIX.1)
 215 .TP
 216 .B EISCONN
 217 Socket is connected (POSIX.1)
 218 .TP
 219 .B EISDIR
 220 Is a directory (POSIX.1)
 221 .TP
 222 .B EISNAM
 223 Is a named type file
 224 .TP
 225 .B EKEYEXPIRED
 226 Key has expired
 227 .TP
 228 .B EKEYREJECTED
 229 Key was rejected by service
 230 .TP
 231 .B EKEYREVOKED
 232 Key has been revoked
 233 .TP
 234 .B EL2HLT
 235 Level 2 halted
 236 .TP
 237 .B EL2NSYNC
 238 Level 2 not synchronized
 239 .TP
 240 .B EL3HLT
 241 Level 3 halted
 242 .TP
 243 .B EL3RST
 244 Level 3 halted
 245 .TP
 246 .B ELIBACC
 247 Cannot access a needed shared library
 248 .TP
 249 .B ELIBBAD
 250 Accessing a corrupted shared library
 251 .TP
 252 .B ELIBMAX
 253 Attempting to link in too many shared libraries
 254 .TP
 255 .B ELIBSCN
 256 lib section in a.out corrupted
 257 .TP
 258 .B ELIBEXEC
 259 Cannot exec a shared library directly
 260 .TP
 261 .B ELOOP
 262 Too many levels of symbolic links (POSIX.1)
 263 .\" ELNRNG is defined but appears to be unused
 264 .TP
 265 .B EMEDIUMTYPE
 266 Wrong medium type
 267 .TP
 268 .B EMFILE
 269 Too many open files (POSIX.1)
 270 .TP
 271 .B EMLINK
 272 Too many links (POSIX.1)
 273 .TP
 274 .B EMSGSIZE
 275 Message too long (POSIX.1)
 276 .TP
 277 .B EMULTIHOP
 278 .\" POSIX says "Reserved"
 279 Multihop attempted (POSIX.1)
 280 .TP
 281 .B ENAMETOOLONG
 282 Filename too long (POSIX.1)
 283 .\" ENAVAIL is defined, but appears not to be used
 284 .TP
 285 .B ENETDOWN
 286 Network is down (POSIX.1)
 287 .TP
 288 .B ENETRESET
 289 Connection aborted by network (POSIX.1)
 290 .TP
 291 .B ENETUNREACH
 292 Network unreachable (POSIX.1)
 293 .TP
 294 .B ENFILE
 295 Too many open files in system (POSIX.1)
 296 .\" ENOANO is defined but appears to be unused.
 297 .TP
 298 .B ENOBUFS
 299 No buffer space available (POSIX.1 (XSI STREAMS option))
 300 .\" ENOCSI is defined but appears to be unused.
 301 .TP
 302 .B ENODATA
 303 No message is available on the STREAM head read queue (POSIX.1)
 304 .TP
 305 .B ENODEV
 306 No such device (POSIX.1)
 307 .TP
 308 .B ENOENT
 309 No such file or directory (POSIX.1)
 310 .TP
 311 .B ENOEXEC
 312 Exec format error (POSIX.1)
 313 .TP
 314 .B ENOKEY
 315 Required key not available
 316 .TP
 317 .B ENOLCK
 318 No locks available (POSIX.1)
 319 .TP
 320 .B ENOLINK
 321 .\" POSIX says "Reserved"
 322 Link has been severed (POSIX.1)
 323 .TP
 324 .B ENOMEDIUM
 325 No medium found
 326 .TP
 327 .B ENOMEM
 328 Not enough space (POSIX.1)
 329 .TP
 330 .B ENOMSG
 331 No message of the desired type (POSIX.1)
 332 .TP
 333 .B ENONET
 334 Machine is not on the network
 335 .TP
 336 .B ENOPKG
 337 Package not installed
 338 .TP
 339 .B ENOPROTOOPT
 340 Protocol not available (POSIX.1)
 341 .TP
 342 .B ENOSPC
 343 No space left on device (POSIX.1)
 344 .TP
 345 .B ENOSR
 346 No STREAM resources (POSIX.1 (XSI STREAMS option))
 347 .TP
 348 .B ENOSTR
 349 Not a STREAM (POSIX.1 (XSI STREAMS option))
 350 .TP
 351 .B ENOSYS
 352 Function not implemented (POSIX.1)
 353 .TP
 354 .B ENOTBLK
 355 Block device required
 356 .TP
 357 .B ENOTCONN
 358 The socket is not connected (POSIX.1)
 359 .TP
 360 .B ENOTDIR
 361 Not a directory (POSIX.1)
 362 .TP
 363 .B ENOTEMPTY
 364 Directory not empty (POSIX.1)
 365 .\" ENOTNAM is defined but appears to be unused.
 366 .TP
 367 .B ENOTSOCK
 368 Not a socket (POSIX.1)
 369 .TP
 370 .B ENOTSUP
 371 Operation not supported (POSIX.1)
 372 .TP
 373 .B ENOTTY
 374 Inappropriate I/O control operation (POSIX.1)
 375 .TP
 376 .B ENOTUNIQ
 377 Name not unique on network
 378 .TP
 379 .B ENXIO
 380 No such device or address (POSIX.1)
 381 .TP
 382 .B EOPNOTSUPP
 383 Operation not supported on socket (POSIX.1)
 384 .sp
 385 .RB ( ENOTSUP
 386 and
 387 .B EOPNOTSUPP
 388 have the same value on Linux, but
 389 according to POSIX.1 these error values should be distinct.)
 390 .TP
 391 .B EOVERFLOW
 392 Value too large to be stored in data type (POSIX.1)
 393 .TP
 394 .B EPERM
 395 Operation not permitted (POSIX.1)
 396 .TP
 397 .B EPFNOSUPPORT
 398 Protocol family not supported
 399 .TP
 400 .B EPIPE
 401 Broken pipe (POSIX.1)
 402 .TP
 403 .B EPROTO
 404 Protocol error (POSIX.1)
 405 .TP
 406 .B EPROTONOSUPPORT
 407 Protocol not supported (POSIX.1)
 408 .TP
 409 .B EPROTOTYPE
 410 Protocol wrong type for socket (POSIX.1)
 411 .TP
 412 .B ERANGE
 413 Result too large (POSIX.1, C99)
 414 .TP
 415 .B EREMCHG
 416 Remote address changed
 417 .TP
 418 .B EREMOTE
 419 Object is remote
 420 .TP
 421 .B EREMOTEIO
 422 Remote I/O error
 423 .TP
 424 .B ERESTART
 425 Interrupted system call should be restarted
 426 .TP
 427 .B EROFS
 428 Read-only file system (POSIX.1)
 429 .TP
 430 .B ESHUTDOWN
 431 Cannot send after transport endpoint shutdown
 432 .TP
 433 .B ESPIPE
 434 Invalid seek (POSIX.1)
 435 .TP
 436 .B ESOCKTNOSUPPORT
 437 Socket type not supported
 438 .TP
 439 .B ESRCH
 440 No such process (POSIX.1)
 441 .\" ESRMNT is defined but appears not to be used
 442 .TP
 443 .B ESTALE
 444 Stale file handle (POSIX.1)
 445 .sp
 446 This error can occur for NFS and for other file systems
 447 .TP
 448 .B ESTRPIPE
 449 Streams pipe error
 450 .TP
 451 .B ETIME
 452 Timer expired
 453 (POSIX.1 (XSI STREAMS option))
 454 .sp
 455 (POSIX.1 says "STREAM
 456 .BR ioctl (2)
 457 timeout")
 458 .TP
 459 .B ETIMEDOUT
 460 Connection timed out (POSIX.1)
 461 .\" ETOOMANYREFS is defined, but appears not to be used.
 462 .TP
 463 .B ETXTBSY
 464 Text file busy (POSIX.1)
 465 .TP
 466 .B EUCLEAN
 467 Structure needs cleaning
 468 .TP
 469 .B EUNATCH
 470 Protocol driver not attached
 471 .TP
 472 .B EUSERS
 473 Too many users
 474 .TP
 475 .B EWOULDBLOCK
 476 Operation would block (may be same value as
 477 .BR EAGAIN )
 478 (POSIX.1)
 479 .TP
 480 .B EXDEV
 481 Improper link (POSIX.1)
 482 .TP
 483 .B EXFULL
 484 Exchange full
 485 .SH NOTES
 486 A common mistake is to do
 487 .in +4n
 488 .nf
 489
 490 if (somecall() == \-1) {
 491     printf("somecall() failed\en");
 492     if (errno == ...) { ... }
 493 }
 494
 495 .fi
 496 .in
 497 where
 498 .I errno
 499 no longer needs to have the value it had upon return from
 500 .IR somecall ()
 501 (i.e., it may have been changed by the
 502 .BR printf (3)).
 503 If the value of
 504 .I errno
 505 should be preserved across a library call, it must be saved:
 506 .in +4n
 507 .nf
 508
 509 if (somecall() == \-1) {
 510     int errsv = errno;
 511     printf("somecall() failed\en");
 512     if (errsv == ...) { ... }
 513 }
 514 .fi
 515 .in
 516 .PP
 517 It was common in traditional C to declare
 518 .I errno
 519 manually
 520 (i.e.,
 521 .IR "extern int errno" )
 522 instead of including
 523 .IR <errno.h> .
 524 .BR "Do not do this" .
 525 It will not work with modern versions of the C library.
 526 However, on (very) old UNIX systems, there may be no
 527 .I <errno.h>
 528 and the declaration is needed.
 529 .SH "SEE ALSO"
 530 .BR err (3),
 531 .BR error (3),
 532 .BR perror (3),
 533 .BR strerror (3)