Debian Codegraph @

upstream/debian-unstable/man3/errno.3

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