man3/errno.3

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