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