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