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