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