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