original/man3/errno.3

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