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