Debian Codegraph @

upstream/debian-trixie/man3/errno.3

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