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