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 2015-12-28 "" "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 .B 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 Illegal byte sequence (POSIX.1, C99)
 211 .TP
 212 .B EINPROGRESS
 213 Operation in progress (POSIX.1)
 214 .TP
 215 .B EINTR
 216 Interrupted function call (POSIX.1); see
 217 .BR signal (7).
 218 .TP
 219 .B EINVAL
 220 Invalid argument (POSIX.1)
 221 .TP
 222 .B EIO
 223 Input/output error (POSIX.1)
 224 .TP
 225 .B EISCONN
 226 Socket is connected (POSIX.1)
 227 .TP
 228 .B EISDIR
 229 Is a directory (POSIX.1)
 230 .TP
 231 .B EISNAM
 232 Is a named type file
 233 .TP
 234 .B EKEYEXPIRED
 235 Key has expired
 236 .TP
 237 .B EKEYREJECTED
 238 Key was rejected by service
 239 .TP
 240 .B EKEYREVOKED
 241 Key has been revoked
 242 .TP
 243 .B EL2HLT
 244 Level 2 halted
 245 .TP
 246 .B EL2NSYNC
 247 Level 2 not synchronized
 248 .TP
 249 .B EL3HLT
 250 Level 3 halted
 251 .TP
 252 .B EL3RST
 253 Level 3 halted
 254 .TP
 255 .B ELIBACC
 256 Cannot access a needed shared library
 257 .TP
 258 .B ELIBBAD
 259 Accessing a corrupted shared library
 260 .TP
 261 .B ELIBMAX
 262 Attempting to link in too many shared libraries
 263 .TP
 264 .B ELIBSCN
 265 lib section in a.out corrupted
 266 .TP
 267 .B ELIBEXEC
 268 Cannot exec a shared library directly
 269 .TP
 270 .B ELOOP
 271 Too many levels of symbolic links (POSIX.1)
 272 .\" ELNRNG is defined but appears to be unused
 273 .TP
 274 .B EMEDIUMTYPE
 275 Wrong medium type
 276 .TP
 277 .B EMFILE
 278 Too many open files (POSIX.1);
 279 commonly caused by exceeding the
 280 .BR RLIMIT_NOFILE
 281 resource limit described in
 282 .BR getrlimit (2)
 283 .TP
 284 .B EMLINK
 285 Too many links (POSIX.1)
 286 .TP
 287 .B EMSGSIZE
 288 Message too long (POSIX.1)
 289 .TP
 290 .B EMULTIHOP
 291 .\" POSIX says "Reserved"
 292 Multihop attempted (POSIX.1)
 293 .TP
 294 .B ENAMETOOLONG
 295 Filename too long (POSIX.1)
 296 .\" ENAVAIL is defined, but appears not to be used
 297 .TP
 298 .B ENETDOWN
 299 Network is down (POSIX.1)
 300 .TP
 301 .B ENETRESET
 302 Connection aborted by network (POSIX.1)
 303 .TP
 304 .B ENETUNREACH
 305 Network unreachable (POSIX.1)
 306 .TP
 307 .B ENFILE
 308 Too many open files in system (POSIX.1);
 309 on Linux, this is probably a result of encountering the
 310 .IR /proc/sys/fs/file-max
 311 limit (see
 312 .BR proc (5)).
 313 .\" ENOANO is defined but appears to be unused.
 314 .TP
 315 .B ENOBUFS
 316 No buffer space available (POSIX.1 (XSI STREAMS option))
 317 .\" ENOCSI is defined but appears to be unused.
 318 .TP
 319 .B ENODATA
 320 No message is available on the STREAM head read queue (POSIX.1)
 321 .TP
 322 .B ENODEV
 323 No such device (POSIX.1)
 324 .TP
 325 .B ENOENT
 326 No such file or directory (POSIX.1)
 327
 328 Typically, this error results when a specified pathname does not exist,
 329 or one of the components in the directory prefix of a pathname does not exist,
 330 or the specified pathname is a dangling symbolic link.
 331 .TP
 332 .B ENOEXEC
 333 Exec format error (POSIX.1)
 334 .TP
 335 .B ENOKEY
 336 Required key not available
 337 .TP
 338 .B ENOLCK
 339 No locks available (POSIX.1)
 340 .TP
 341 .B ENOLINK
 342 .\" POSIX says "Reserved"
 343 Link has been severed (POSIX.1)
 344 .TP
 345 .B ENOMEDIUM
 346 No medium found
 347 .TP
 348 .B ENOMEM
 349 Not enough space (POSIX.1)
 350 .TP
 351 .B ENOMSG
 352 No message of the desired type (POSIX.1)
 353 .TP
 354 .B ENONET
 355 Machine is not on the network
 356 .TP
 357 .B ENOPKG
 358 Package not installed
 359 .TP
 360 .B ENOPROTOOPT
 361 Protocol not available (POSIX.1)
 362 .TP
 363 .B ENOSPC
 364 No space left on device (POSIX.1)
 365 .TP
 366 .B ENOSR
 367 No STREAM resources (POSIX.1 (XSI STREAMS option))
 368 .TP
 369 .B ENOSTR
 370 Not a STREAM (POSIX.1 (XSI STREAMS option))
 371 .TP
 372 .B ENOSYS
 373 Function not implemented (POSIX.1)
 374 .TP
 375 .B ENOTBLK
 376 Block device required
 377 .TP
 378 .B ENOTCONN
 379 The socket is not connected (POSIX.1)
 380 .TP
 381 .B ENOTDIR
 382 Not a directory (POSIX.1)
 383 .TP
 384 .B ENOTEMPTY
 385 Directory not empty (POSIX.1)
 386 .\" ENOTNAM is defined but appears to be unused.
 387 .TP
 388 .B ENOTSOCK
 389 Not a socket (POSIX.1)
 390 .TP
 391 .B ENOTSUP
 392 Operation not supported (POSIX.1)
 393 .TP
 394 .B ENOTTY
 395 Inappropriate I/O control operation (POSIX.1)
 396 .TP
 397 .B ENOTUNIQ
 398 Name not unique on network
 399 .TP
 400 .B ENXIO
 401 No such device or address (POSIX.1)
 402 .TP
 403 .B EOPNOTSUPP
 404 Operation not supported on socket (POSIX.1)
 405 .sp
 406 .RB ( ENOTSUP
 407 and
 408 .B EOPNOTSUPP
 409 have the same value on Linux, but
 410 according to POSIX.1 these error values should be distinct.)
 411 .TP
 412 .B EOVERFLOW
 413 Value too large to be stored in data type (POSIX.1)
 414 .TP
 415 .B EPERM
 416 Operation not permitted (POSIX.1)
 417 .TP
 418 .B EPFNOSUPPORT
 419 Protocol family not supported
 420 .TP
 421 .B EPIPE
 422 Broken pipe (POSIX.1)
 423 .TP
 424 .B EPROTO
 425 Protocol error (POSIX.1)
 426 .TP
 427 .B EPROTONOSUPPORT
 428 Protocol not supported (POSIX.1)
 429 .TP
 430 .B EPROTOTYPE
 431 Protocol wrong type for socket (POSIX.1)
 432 .TP
 433 .B ERANGE
 434 Result too large (POSIX.1, C99)
 435 .TP
 436 .B EREMCHG
 437 Remote address changed
 438 .TP
 439 .B EREMOTE
 440 Object is remote
 441 .TP
 442 .B EREMOTEIO
 443 Remote I/O error
 444 .TP
 445 .B ERESTART
 446 Interrupted system call should be restarted
 447 .TP
 448 .B EROFS
 449 Read-only filesystem (POSIX.1)
 450 .TP
 451 .B ESHUTDOWN
 452 Cannot send after transport endpoint shutdown
 453 .TP
 454 .B ESPIPE
 455 Invalid seek (POSIX.1)
 456 .TP
 457 .B ESOCKTNOSUPPORT
 458 Socket type not supported
 459 .TP
 460 .B ESRCH
 461 No such process (POSIX.1)
 462 .\" ESRMNT is defined but appears not to be used
 463 .TP
 464 .B ESTALE
 465 Stale file handle (POSIX.1)
 466 .sp
 467 This error can occur for NFS and for other filesystems
 468 .TP
 469 .B ESTRPIPE
 470 Streams pipe error
 471 .TP
 472 .B ETIME
 473 Timer expired
 474 (POSIX.1 (XSI STREAMS option))
 475 .sp
 476 (POSIX.1 says "STREAM
 477 .BR ioctl (2)
 478 timeout")
 479 .TP
 480 .B ETIMEDOUT
 481 Connection timed out (POSIX.1)
 482 .\" ETOOMANYREFS is defined, but appears not to be used.
 483 .TP
 484 .B ETXTBSY
 485 Text file busy (POSIX.1)
 486 .TP
 487 .B EUCLEAN
 488 Structure needs cleaning
 489 .TP
 490 .B EUNATCH
 491 Protocol driver not attached
 492 .TP
 493 .B EUSERS
 494 Too many users
 495 .TP
 496 .B EWOULDBLOCK
 497 Operation would block (may be same value as
 498 .BR EAGAIN )
 499 (POSIX.1)
 500 .TP
 501 .B EXDEV
 502 Improper link (POSIX.1)
 503 .TP
 504 .B EXFULL
 505 Exchange full
 506 .SH NOTES
 507 A common mistake is to do
 508 .in +4n
 509 .nf
 510
 511 if (somecall() == \-1) {
 512     printf("somecall() failed\en");
 513     if (errno == ...) { ... }
 514 }
 515
 516 .fi
 517 .in
 518 where
 519 .I errno
 520 no longer needs to have the value it had upon return from
 521 .IR somecall ()
 522 (i.e., it may have been changed by the
 523 .BR printf (3)).
 524 If the value of
 525 .I errno
 526 should be preserved across a library call, it must be saved:
 527 .in +4n
 528 .nf
 529
 530 if (somecall() == \-1) {
 531     int errsv = errno;
 532     printf("somecall() failed\en");
 533     if (errsv == ...) { ... }
 534 }
 535 .fi
 536 .in
 537 .PP
 538 It was common in traditional C to declare
 539 .I errno
 540 manually
 541 (i.e.,
 542 .IR "extern int errno" )
 543 instead of including
 544 .IR <errno.h> .
 545 .BR "Do not do this" .
 546 It will not work with modern versions of the C library.
 547 However, on (very) old UNIX systems, there may be no
 548 .I <errno.h>
 549 and the declaration is needed.
 550 .SH SEE ALSO
 551 .BR errno (1),  \" In the moreutils package
 552 .BR err (3),
 553 .BR error (3),
 554 .BR perror (3),
 555 .BR strerror (3)