(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[kopensolaris-gnu/glibc.git] / manual / errno.texi
1 @node Error Reporting, Memory Allocation, Introduction, Top
2 @chapter Error Reporting
3 @cindex error reporting
4 @cindex reporting errors
5 @cindex error codes
6 @cindex status codes
7
8 Many functions in the GNU C library detect and report error conditions,
9 and sometimes your programs need to check for these error conditions.
10 For example, when you open an input file, you should verify that the
11 file was actually opened correctly, and print an error message or take
12 other appropriate action if the call to the library function failed.
13
14 This chapter describes how the error reporting facility works.  Your
15 program should include the header file @file{errno.h} to use this
16 facility.
17 @pindex errno.h
18
19 @menu
20 * Checking for Errors::         How errors are reported by library functions.
21 * Error Codes::                 Error code macros; all of these expand 
22                                  into integer constant values.
23 * Error Messages::              Mapping error codes onto error messages.
24 @end menu
25
26 @node Checking for Errors, Error Codes,  , Error Reporting
27 @section Checking for Errors
28
29 Most library functions return a special value to indicate that they have
30 failed.  The special value is typically @code{-1}, a null pointer, or a
31 constant such as @code{EOF} that is defined for that purpose.  But this
32 return value tells you only that an error has occurred.  To find out
33 what kind of error it was, you need to look at the error code stored in the
34 variable @code{errno}.  This variable is declared in the header file
35 @file{errno.h}.
36 @pindex errno.h
37
38 @comment errno.h
39 @comment ANSI
40 @deftypevr {Variable} {volatile int} errno
41 The variable @code{errno} contains the system error number.  You can
42 change the value of @code{errno}.
43
44 Since @code{errno} is declared @code{volatile}, it might be changed
45 asynchronously by a signal handler; see @ref{Defining Handlers}.
46 However, a properly written signal handler saves and restores the value
47 of @code{errno}, so you generally do not need to worry about this
48 possibility except when writing signal handlers.
49
50 The initial value of @code{errno} at program startup is zero.  Many
51 library functions are guaranteed to set it to certain nonzero values
52 when they encounter certain kinds of errors.  These error conditions are
53 listed for each function.  These functions do not change @code{errno}
54 when they succeed; thus, the value of @code{errno} after a successful
55 call is not necessarily zero, and you should not use @code{errno} to
56 determine @emph{whether} a call failed.  The proper way to do that is
57 documented for each function.  @emph{If} the call the failed, you can
58 examine @code{errno}.
59
60 Many library functions can set @code{errno} to a nonzero value as a
61 result of calling other library functions which might fail.  You should
62 assume that any library function might alter @code{errno} when the
63 function returns an error.
64
65 @strong{Portability Note:} ANSI C specifies @code{errno} as a
66 ``modifiable lvalue'' rather than as a variable, permitting it to be
67 implemented as a macro.  For example, its expansion might involve a
68 function call, like @w{@code{*_errno ()}}.  In fact, that is what it is
69 on the GNU system itself.  The GNU library, on non-GNU systems, does
70 whatever is right for the particular system.
71
72 There are a few library functions, like @code{sqrt} and @code{atan},
73 that return a perfectly legitimate value in case of an error, but also
74 set @code{errno}.  For these functions, if you want to check to see
75 whether an error occurred, the recommended method is to set @code{errno}
76 to zero before calling the function, and then check its value afterward.
77 @end deftypevr
78
79 @pindex errno.h
80 All the error codes have symbolic names; they are macros defined in
81 @file{errno.h}.  The names start with @samp{E} and an upper-case
82 letter or digit; you should consider names of this form to be
83 reserved names.  @xref{Reserved Names}.
84
85 The error code values are all positive integers and are all distinct,
86 with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
87 Since the values are distinct, you can use them as labels in a
88 @code{switch} statement; just don't use both @code{EWOULDBLOCK} and
89 @code{EAGAIN}.  Your program should not make any other assumptions about
90 the specific values of these symbolic constants.
91
92 The value of @code{errno} doesn't necessarily have to correspond to any
93 of these macros, since some library functions might return other error
94 codes of their own for other situations.  The only values that are
95 guaranteed to be meaningful for a particular library function are the
96 ones that this manual lists for that function.
97
98 On non-GNU systems, almost any system call can return @code{EFAULT} if
99 it is given an invalid pointer as an argument.  Since this could only
100 happen as a result of a bug in your program, and since it will not
101 happen on the GNU system, we have saved space by not mentioning
102 @code{EFAULT} in the descriptions of individual functions.
103
104 In some Unix systems, many system calls can also return @code{EFAULT} if
105 given as an argument a pointer into the stack, and the kernel for some
106 obscure reason fails in its attempt to extend the stack.  If this ever
107 happens, you should probably try using statically or dynamically
108 allocated memory instead of stack memory on that system.
109
110 @node Error Codes, Error Messages, Checking for Errors, Error Reporting
111 @section Error Codes
112
113 @pindex errno.h
114 The error code macros are defined in the header file @file{errno.h}.
115 All of them expand into integer constant values.  Some of these error
116 codes can't occur on the GNU system, but they can occur using the GNU
117 library on other systems.
118
119 @comment errno.h
120 @comment POSIX.1: Operation not permitted
121 @deftypevr Macro int EPERM
122 @comment errno 1 @c DO NOT REMOVE
123 Operation not permitted; only the owner of the file (or other resource)
124 or processes with special privileges can perform the operation.
125 @end deftypevr
126
127 @comment errno.h
128 @comment POSIX.1: No such file or directory
129 @deftypevr Macro int ENOENT
130 @comment errno 2 @c DO NOT REMOVE
131 No such file or directory.  This is a ``file doesn't exist'' error
132 for ordinary files that are referenced in contexts where they are
133 expected to already exist.
134 @end deftypevr
135
136 @comment errno.h
137 @comment POSIX.1: No such process
138 @deftypevr Macro int ESRCH
139 @comment errno 3 @c DO NOT REMOVE
140 No process matches the specified process ID.
141 @end deftypevr
142
143 @comment errno.h
144 @comment POSIX.1: Interrupted system call
145 @deftypevr Macro int EINTR
146 @comment errno 4 @c DO NOT REMOVE
147 Interrupted function call; an asynchronous signal occured and prevented
148 completion of the call.  When this happens, you should try the call
149 again.
150
151 You can choose to have functions resume after a signal that is handled,
152 rather than failing with @code{EINTR}; see @ref{Interrupted
153 Primitives}.
154 @end deftypevr
155
156 @comment errno.h
157 @comment POSIX.1: Input/output error
158 @deftypevr Macro int EIO
159 @comment errno 5 @c DO NOT REMOVE
160 Input/output error; usually used for physical read or write errors.
161 @end deftypevr
162
163 @comment errno.h
164 @comment POSIX.1: Device not configured
165 @deftypevr Macro int ENXIO
166 @comment errno 6 @c DO NOT REMOVE
167 No such device or address.  The system tried to use the device
168 represented by a file you specified, and it couldn't find the device.
169 This can mean that the device file was installed incorrectly, or that
170 the physical device is missing or not correctly attached to the
171 computer.
172 @end deftypevr
173
174 @comment errno.h
175 @comment POSIX.1: Argument list too long
176 @deftypevr Macro int E2BIG
177 @comment errno 7 @c DO NOT REMOVE
178 Argument list too long; used when the arguments passed to a new program
179 being executed with one of the @code{exec} functions (@pxref{Executing a
180 File}) occupy too much memory space.  This condition never arises in the
181 GNU system.
182 @end deftypevr
183
184 @comment errno.h
185 @comment POSIX.1: Exec format error
186 @deftypevr Macro int ENOEXEC
187 @comment errno 8 @c DO NOT REMOVE
188 Invalid executable file format.  This condition is detected by the
189 @code{exec} functions; see @ref{Executing a File}.
190 @end deftypevr
191
192 @comment errno.h
193 @comment POSIX.1: Bad file descriptor
194 @deftypevr Macro int EBADF
195 @comment errno 9 @c DO NOT REMOVE
196 Bad file descriptor; for example, I/O on a descriptor that has been
197 closed or reading from a descriptor open only for writing (or vice
198 versa).
199 @end deftypevr
200
201 @comment errno.h
202 @comment POSIX.1: No child processes
203 @deftypevr Macro int ECHILD
204 @comment errno 10 @c DO NOT REMOVE
205 There are no child processes.  This error happens on operations that are
206 supposed to manipulate child processes, when there aren't any processes
207 to manipulate.
208 @end deftypevr
209
210 @comment errno.h
211 @comment POSIX.1: Resource deadlock avoided
212 @deftypevr Macro int EDEADLK
213 @comment errno 11 @c DO NOT REMOVE
214 Deadlock avoided; allocating a system resource would have resulted in a
215 deadlock situation.  The system does not guarantee that it will notice
216 all such situations.  This error means you got lucky and the system
217 noticed; it might just hang.  @xref{File Locks}, for an example.
218 @end deftypevr
219
220 @comment errno.h
221 @comment POSIX.1: Cannot allocate memory
222 @deftypevr Macro int ENOMEM
223 @comment errno 12 @c DO NOT REMOVE
224 No memory available.  The system cannot allocate more virtual memory
225 because its capacity is full.
226 @end deftypevr
227
228 @comment errno.h
229 @comment POSIX.1: Permission denied
230 @deftypevr Macro int EACCES
231 @comment errno 13 @c DO NOT REMOVE
232 Permission denied; the file permissions do not allow the attempted operation.
233 @end deftypevr
234
235 @comment errno.h
236 @comment POSIX.1: Bad address
237 @deftypevr Macro int EFAULT
238 @comment errno 14 @c DO NOT REMOVE
239 Bad address; an invalid pointer was detected.
240 In the GNU system, this error never happens; you get a signal instead.
241 @end deftypevr
242
243 @comment errno.h
244 @comment BSD: Block device required
245 @deftypevr Macro int ENOTBLK
246 @comment errno 15 @c DO NOT REMOVE
247 A file that isn't a block special file was given in a situation that
248 requires one.  For example, trying to mount an ordinary file as a file
249 system in Unix gives this error.
250 @end deftypevr
251
252 @comment errno.h
253 @comment POSIX.1: Device busy
254 @deftypevr Macro int EBUSY
255 @comment errno 16 @c DO NOT REMOVE
256 Resource busy; a system resource that can't be shared is already in use.
257 For example, if you try to delete a file that is the root of a currently
258 mounted filesystem, you get this error.
259 @end deftypevr
260
261 @comment errno.h
262 @comment POSIX.1: File exists
263 @deftypevr Macro int EEXIST
264 @comment errno 17 @c DO NOT REMOVE
265 File exists; an existing file was specified in a context where it only
266 makes sense to specify a new file.
267 @end deftypevr
268
269 @comment errno.h
270 @comment POSIX.1: Invalid cross-device link
271 @deftypevr Macro int EXDEV
272 @comment errno 18 @c DO NOT REMOVE
273 An attempt to make an improper link across file systems was detected.
274 This happens not only when you use @code{link} (@pxref{Hard Links}) but
275 also when you rename a file with @code{rename} (@pxref{Renaming Files}).
276 @end deftypevr
277
278 @comment errno.h
279 @comment POSIX.1: Operation not supported by device
280 @deftypevr Macro int ENODEV
281 @comment errno 19 @c DO NOT REMOVE
282 The wrong type of device was given to a function that expects a
283 particular sort of device.
284 @end deftypevr
285
286 @comment errno.h
287 @comment POSIX.1: Not a directory
288 @deftypevr Macro int ENOTDIR
289 @comment errno 20 @c DO NOT REMOVE
290 A file that isn't a directory was specified when a directory is required.
291 @end deftypevr
292
293 @comment errno.h
294 @comment POSIX.1: Is a directory
295 @deftypevr Macro int EISDIR
296 @comment errno 21 @c DO NOT REMOVE
297 File is a directory; you cannot open a directory for writing,
298 or create or remove hard links to it.
299 @end deftypevr
300
301 @comment errno.h
302 @comment POSIX.1: Invalid argument
303 @deftypevr Macro int EINVAL
304 @comment errno 22 @c DO NOT REMOVE
305 Invalid argument.  This is used to indicate various kinds of problems
306 with passing the wrong argument to a library function.
307 @end deftypevr
308
309 @comment errno.h
310 @comment POSIX.1: Too many open files
311 @deftypevr Macro int EMFILE
312 @comment errno 24 @c DO NOT REMOVE
313 The current process has too many files open and can't open any more.
314 Duplicate descriptors do count toward this limit.
315
316 In BSD and GNU, the number of open files is controlled by a resource
317 limit that can usually be increased.  If you get this error, you might
318 want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited;
319 @pxref{Limits on Resources}.
320 @end deftypevr
321
322 @comment errno.h
323 @comment POSIX.1: Too many open files in system
324 @deftypevr Macro int ENFILE
325 @comment errno 23 @c DO NOT REMOVE
326 There are too many distinct file openings in the entire system.  Note
327 that any number of linked channels count as just one file opening; see
328 @ref{Linked Channels}.  This error never occurs in the GNU system.
329 @end deftypevr
330
331 @comment errno.h
332 @comment POSIX.1: Inappropriate ioctl for device
333 @deftypevr Macro int ENOTTY
334 @comment errno 25 @c DO NOT REMOVE
335 Inappropriate I/O control operation, such as trying to set terminal
336 modes on an ordinary file.
337 @end deftypevr
338
339 @comment errno.h
340 @comment BSD: Text file busy
341 @deftypevr Macro int ETXTBSY
342 @comment errno 26 @c DO NOT REMOVE
343 An attempt to execute a file that is currently open for writing, or
344 write to a file that is currently being executed.  Often using a
345 debugger to run a program is considered having it open for writing and
346 will cause this error.  (The name stands for ``text file busy''.)  This
347 is not an error in the GNU system; the text is copied as necessary.
348 @end deftypevr
349
350 @comment errno.h
351 @comment POSIX.1: File too large
352 @deftypevr Macro int EFBIG
353 @comment errno 27 @c DO NOT REMOVE
354 File too big; the size of a file would be larger than allowed by the system.
355 @end deftypevr
356
357 @comment errno.h
358 @comment POSIX.1: No space left on device
359 @deftypevr Macro int ENOSPC
360 @comment errno 28 @c DO NOT REMOVE
361 No space left on device; write operation on a file failed because the
362 disk is full.
363 @end deftypevr
364
365 @comment errno.h
366 @comment POSIX.1: Illegal seek
367 @deftypevr Macro int ESPIPE
368 @comment errno 29 @c DO NOT REMOVE
369 Invalid seek operation (such as on a pipe).
370 @end deftypevr
371
372 @comment errno.h
373 @comment POSIX.1: Read-only file system
374 @deftypevr Macro int EROFS
375 @comment errno 30 @c DO NOT REMOVE
376 An attempt was made to modify something on a read-only file system.
377 @end deftypevr
378
379 @comment errno.h
380 @comment POSIX.1: Too many links
381 @deftypevr Macro int EMLINK
382 @comment errno 31 @c DO NOT REMOVE
383 Too many links; the link count of a single file would become too large.
384 @code{rename} can cause this error if the file being renamed already has
385 as many links as it can take (@pxref{Renaming Files}).
386 @end deftypevr
387
388 @comment errno.h
389 @comment POSIX.1: Broken pipe
390 @deftypevr Macro int EPIPE
391 @comment errno 32 @c DO NOT REMOVE
392 Broken pipe; there is no process reading from the other end of a pipe.
393 Every library function that returns this error code also generates a
394 @code{SIGPIPE} signal; this signal terminates the program if not handled
395 or blocked.  Thus, your program will never actually see @code{EPIPE}
396 unless it has handled or blocked @code{SIGPIPE}.
397 @end deftypevr
398
399 @comment errno.h
400 @comment ANSI: Numerical argument out of domain
401 @deftypevr Macro int EDOM
402 @comment errno 33 @c DO NOT REMOVE
403 Domain error; used by mathematical functions when an argument value does
404 not fall into the domain over which the function is defined.
405 @end deftypevr
406
407 @comment errno.h
408 @comment ANSI: Numerical result out of range
409 @deftypevr Macro int ERANGE
410 @comment errno 34 @c DO NOT REMOVE
411 Range error; used by mathematical functions when the result value is
412 not representable because of overflow or underflow.
413 @end deftypevr
414
415 @comment errno.h
416 @comment POSIX.1: Resource temporarily unavailable
417 @deftypevr Macro int EAGAIN
418 @comment errno 35 @c DO NOT REMOVE
419 Resource temporarily unavailable; the call might work if you try again
420 later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
421 they are always the same in the GNU C library.
422
423 This error can happen in a few different situations:
424
425 @itemize @bullet
426 @item
427 An operation that would block was attempted on an object that has
428 non-blocking mode selected.  Trying the same operation again will block
429 until some external condition makes it possible to read, write, or
430 connect (whatever the operation).  You can use @code{select} to find out
431 when the operation will be possible; @pxref{Waiting for I/O}.
432
433 @strong{Portability Note:} In older Unix many systems, this condition
434 was indicated by @code{EWOULDBLOCK}, which was a distinct error code
435 different from @code{EAGAIN}.  To make your program portable, you should
436 check for both codes and treat them the same.
437
438 @item
439 A temporary resource shortage made an operation impossible.  @code{fork}
440 can return this error.  It indicates that the shortage is expected to
441 pass, so your program can try the call again later and it may succeed.
442 It is probably a good idea to delay for a few seconds before trying it
443 again, to allow time for other processes to release scarce resources.
444 Such shortages are usually fairly serious and affect the whole system,
445 so usually an interactive program should report the error to the user
446 and return to its command loop.
447 @end itemize
448 @end deftypevr
449
450 @comment errno.h
451 @comment BSD: Operation would block
452 @deftypevr Macro int EWOULDBLOCK
453 @comment errno EAGAIN @c DO NOT REMOVE
454 In the GNU C library, this is another name for @code{EAGAIN} (above).
455 The values are always the same, on every operating system.
456
457 C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
458 separate error code.
459 @end deftypevr
460
461 @comment errno.h
462 @comment BSD: Operation now in progress
463 @deftypevr Macro int EINPROGRESS
464 @comment errno 36 @c DO NOT REMOVE
465 An operation that cannot complete immediately was initiated on an object
466 that has non-blocking mode selected.  Some functions that must always
467 block (such as @code{connect}; @pxref{Connecting}) never return
468 @code{EAGAIN}.  Instead, they return @code{EINPROGRESS} to indicate that
469 the operation has begun and will take some time.  Attempts to manipulate
470 the object before the call completes return @code{EALREADY}.  You can
471 use the @code{select} function to find out when the pending operation
472 has completed; @pxref{Waiting for I/O}.
473 @end deftypevr
474
475 @comment errno.h
476 @comment BSD: Operation already in progress
477 @deftypevr Macro int EALREADY
478 @comment errno 37 @c DO NOT REMOVE
479 An operation is already in progress on an object that has non-blocking
480 mode selected.
481 @end deftypevr
482
483 @comment errno.h
484 @comment BSD: Socket operation on non-socket
485 @deftypevr Macro int ENOTSOCK
486 @comment errno 38 @c DO NOT REMOVE
487 A file that isn't a socket was specified when a socket is required.
488 @end deftypevr
489
490 @comment errno.h
491 @comment BSD: Message too long
492 @deftypevr Macro int EMSGSIZE
493 @comment errno 40 @c DO NOT REMOVE
494 The size of a message sent on a socket was larger than the supported
495 maximum size.  
496 @end deftypevr
497
498 @comment errno.h
499 @comment BSD: Protocol wrong type for socket
500 @deftypevr Macro int EPROTOTYPE
501 @comment errno 41 @c DO NOT REMOVE
502 The socket type does not support the requested communications protocol.
503 @end deftypevr
504
505 @comment errno.h
506 @comment BSD: Protocol not available
507 @deftypevr Macro int ENOPROTOOPT
508 @comment errno 42 @c DO NOT REMOVE
509 You specified a socket option that doesn't make sense for the
510 particular protocol being used by the socket.  @xref{Socket Options}.
511 @end deftypevr
512
513 @comment errno.h
514 @comment BSD: Protocol not supported
515 @deftypevr Macro int EPROTONOSUPPORT
516 @comment errno 43 @c DO NOT REMOVE
517 The socket domain does not support the requested communications protocol
518 (perhaps because the requested protocol is completely invalid.)
519 @xref{Creating a Socket}.
520 @end deftypevr
521
522 @comment errno.h
523 @comment BSD: Socket type not supported
524 @deftypevr Macro int ESOCKTNOSUPPORT
525 @comment errno 44 @c DO NOT REMOVE
526 The socket type is not supported.
527 @end deftypevr
528
529 @comment errno.h
530 @comment BSD: Operation not supported
531 @deftypevr Macro int EOPNOTSUPP
532 @comment errno 45 @c DO NOT REMOVE
533 The operation you requested is not supported.  Some socket functions
534 don't make sense for all types of sockets, and others may not be
535 implemented for all communications protocols.  In the GNU system, this
536 error can happen for many calls when the object does not support the
537 particular operation; it is a generic indication that the server knows
538 nothing to do for that call.
539 @end deftypevr
540
541 @comment errno.h
542 @comment BSD: Protocol family not supported
543 @deftypevr Macro int EPFNOSUPPORT
544 @comment errno 46 @c DO NOT REMOVE
545 The socket communications protocol family you requested is not supported.
546 @end deftypevr
547
548 @comment errno.h
549 @comment BSD: Address family not supported by protocol family
550 @deftypevr Macro int EAFNOSUPPORT
551 @comment errno 47 @c DO NOT REMOVE
552 The address family specified for a socket is not supported; it is
553 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
554 @end deftypevr
555
556 @comment errno.h
557 @comment BSD: Address already in use
558 @deftypevr Macro int EADDRINUSE
559 @comment errno 48 @c DO NOT REMOVE
560 The requested socket address is already in use.  @xref{Socket Addresses}.
561 @end deftypevr
562
563 @comment errno.h
564 @comment BSD: Can't assign requested address
565 @deftypevr Macro int EADDRNOTAVAIL
566 @comment errno 49 @c DO NOT REMOVE
567 The requested socket address is not available; for example, you tried
568 to give a socket a name that doesn't match the local host name.
569 @xref{Socket Addresses}.
570 @end deftypevr
571
572 @comment errno.h
573 @comment BSD: Network is down
574 @deftypevr Macro int ENETDOWN
575 @comment errno 50 @c DO NOT REMOVE
576 A socket operation failed because the network was down.
577 @end deftypevr
578
579 @comment errno.h
580 @comment BSD: Network is unreachable
581 @deftypevr Macro int ENETUNREACH
582 @comment errno 51 @c DO NOT REMOVE
583 A socket operation failed because the subnet containing the remote host
584 was unreachable.
585 @end deftypevr
586
587 @comment errno.h
588 @comment BSD: Network dropped connection on reset
589 @deftypevr Macro int ENETRESET
590 @comment errno 52 @c DO NOT REMOVE
591 A network connection was reset because the remote host crashed.
592 @end deftypevr
593
594 @comment errno.h
595 @comment BSD: Software caused connection abort
596 @deftypevr Macro int ECONNABORTED
597 @comment errno 53 @c DO NOT REMOVE
598 A network connection was aborted locally.
599 @end deftypevr
600
601 @comment errno.h
602 @comment BSD: Connection reset by peer
603 @deftypevr Macro int ECONNRESET
604 @comment errno 54 @c DO NOT REMOVE
605 A network connection was closed for reasons outside the control of the
606 local host, such as by the remote machine rebooting or an unrecoverable
607 protocol violation.
608 @end deftypevr
609
610 @comment errno.h
611 @comment BSD: No buffer space available
612 @deftypevr Macro int ENOBUFS
613 @comment errno 55 @c DO NOT REMOVE
614 The kernel's buffers for I/O operations are all in use.  In GNU, this
615 error is always synonymous with @code{ENOMEM}; you may get one or the
616 other from network operations.
617 @end deftypevr
618
619 @comment errno.h
620 @comment BSD: Socket is already connected
621 @deftypevr Macro int EISCONN
622 @comment errno 56 @c DO NOT REMOVE
623 You tried to connect a socket that is already connected.
624 @xref{Connecting}.
625 @end deftypevr
626
627 @comment errno.h
628 @comment BSD: Socket is not connected
629 @deftypevr Macro int ENOTCONN
630 @comment errno 57 @c DO NOT REMOVE
631 The socket is not connected to anything.  You get this error when you
632 try to transmit data over a socket, without first specifying a
633 destination for the data.  For a connectionless socket (for datagram
634 protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
635 @end deftypevr
636
637 @comment errno.h
638 @comment BSD: Destination address required
639 @deftypevr Macro int EDESTADDRREQ
640 @comment errno 39 @c DO NOT REMOVE
641 No default destination address was set for the socket.  You get this
642 error when you try to transmit data over a connectionless socket,
643 without first specifying a destination for the data with @code{connect}.
644 @end deftypevr
645
646 @comment errno.h
647 @comment BSD: Can't send after socket shutdown
648 @deftypevr Macro int ESHUTDOWN
649 @comment errno 58 @c DO NOT REMOVE
650 The socket has already been shut down.
651 @end deftypevr
652
653 @comment errno.h
654 @comment BSD: Too many references: can't splice
655 @deftypevr Macro int ETOOMANYREFS
656 @comment errno 59 @c DO NOT REMOVE
657 ???
658 @end deftypevr
659
660 @comment errno.h
661 @comment BSD: Connection timed out
662 @deftypevr Macro int ETIMEDOUT
663 @comment errno 60 @c DO NOT REMOVE
664 A socket operation with a specified timeout received no response during
665 the timeout period.
666 @end deftypevr
667
668 @comment errno.h
669 @comment BSD: Connection refused
670 @deftypevr Macro int ECONNREFUSED
671 @comment errno 61 @c DO NOT REMOVE
672 A remote host refused to allow the network connection (typically because
673 it is not running the requested service).
674 @end deftypevr
675
676 @comment errno.h
677 @comment BSD: Too many levels of symbolic links
678 @deftypevr Macro int ELOOP
679 @comment errno 62 @c DO NOT REMOVE
680 Too many levels of symbolic links were encountered in looking up a file name.
681 This often indicates a cycle of symbolic links.
682 @end deftypevr
683
684 @comment errno.h
685 @comment POSIX.1: File name too long
686 @deftypevr Macro int ENAMETOOLONG
687 @comment errno 63 @c DO NOT REMOVE
688 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
689 Files}) or host name too long (in @code{gethostname} or
690 @code{sethostname}; @pxref{Host Identification}).
691 @end deftypevr
692
693 @comment errno.h
694 @comment BSD: Host is down
695 @deftypevr Macro int EHOSTDOWN
696 @comment errno 64 @c DO NOT REMOVE
697 The remote host for a requested network connection is down.
698 @end deftypevr
699
700 @comment errno.h
701 @comment BSD: No route to host
702 @deftypevr Macro int EHOSTUNREACH
703 @comment errno 65 @c DO NOT REMOVE
704 The remote host for a requested network connection is not reachable.
705 @end deftypevr
706
707 @comment errno.h
708 @comment POSIX.1: Directory not empty
709 @deftypevr Macro int ENOTEMPTY
710 @comment errno 66 @c DO NOT REMOVE
711 Directory not empty, where an empty directory was expected.  Typically,
712 this error occurs when you are trying to delete a directory.
713 @end deftypevr
714
715 @comment errno.h
716 @comment BSD: Too many processes
717 @deftypevr Macro int EPROCLIM
718 @comment errno 67 @c DO NOT REMOVE
719 This means that the per-user limit on new process would be exceeded by
720 an attempted @code{fork}.  @xref{Limits on Resources}, for details on
721 the @code{RLIMIT_NPROC} limit.
722 @end deftypevr
723
724 @comment errno.h
725 @comment BSD: Too many users
726 @deftypevr Macro int EUSERS
727 @comment errno 68 @c DO NOT REMOVE
728 The file quota system is confused because there are too many users.
729 @c This can probably happen in a GNU system when using NFS.
730 @end deftypevr
731
732 @comment errno.h
733 @comment BSD: Disc quota exceeded
734 @deftypevr Macro int EDQUOT
735 @comment errno 69 @c DO NOT REMOVE
736 The user's disk quota was exceeded.
737 @end deftypevr
738
739 @comment errno.h
740 @comment BSD: Stale NFS file handle
741 @deftypevr Macro int ESTALE
742 @comment errno 70 @c DO NOT REMOVE
743 Stale NFS file handle.  This indicates an internal confusion in the NFS
744 system which is due to file system rearrangements on the server host.
745 Repairing this condition usually requires unmounting and remounting
746 the NFS file system on the local host.
747 @end deftypevr
748
749 @comment errno.h
750 @comment BSD: Too many levels of remote in path
751 @deftypevr Macro int EREMOTE
752 @comment errno 71 @c DO NOT REMOVE
753 An attempt was made to NFS-mount a remote file system with a file name that
754 already specifies an NFS-mounted file.
755 (This is an error on some operating systems, but we expect it to work
756 properly on the GNU system, making this error code impossible.)
757 @end deftypevr
758
759 @comment errno.h
760 @comment BSD: RPC struct is bad
761 @deftypevr Macro int EBADRPC
762 @comment errno 72 @c DO NOT REMOVE
763 ???
764 @end deftypevr
765
766 @comment errno.h
767 @comment BSD: RPC version wrong
768 @deftypevr Macro int ERPCMISMATCH
769 @comment errno 73 @c DO NOT REMOVE
770 ???
771 @end deftypevr
772
773 @comment errno.h
774 @comment BSD: RPC program not available
775 @deftypevr Macro int EPROGUNAVAIL
776 @comment errno 74 @c DO NOT REMOVE
777 ???
778 @end deftypevr
779
780 @comment errno.h
781 @comment BSD: RPC program version wrong
782 @deftypevr Macro int EPROGMISMATCH
783 @comment errno 75 @c DO NOT REMOVE
784 ???
785 @end deftypevr
786
787 @comment errno.h
788 @comment BSD: RPC bad procedure for program
789 @deftypevr Macro int EPROCUNAVAIL
790 @comment errno 76 @c DO NOT REMOVE
791 ???
792 @end deftypevr
793
794 @comment errno.h
795 @comment POSIX.1: No locks available
796 @deftypevr Macro int ENOLCK
797 @comment errno 77 @c DO NOT REMOVE
798 No locks available.  This is used by the file locking facilities; see
799 @ref{File Locks}.  This error is never generated by the GNU system, but
800 it can result from an operation to an NFS server running another
801 operating system.
802 @end deftypevr
803
804 @comment errno.h
805 @comment BSD: Inappropriate file type or format
806 @deftypevr Macro int EFTYPE
807 @comment errno 79 @c DO NOT REMOVE
808 Inappropriate file type or format.  The file was the wrong type for the
809 operation, or a data file had the wrong format.
810
811 On some systems @code{chmod} returns this error if you try to set the
812 sticky bit on a non-directory file; @pxref{Setting Permissions}.
813 @end deftypevr
814
815 @comment errno.h
816 @comment BSD: Authentication error
817 @deftypevr Macro int EAUTH
818 @comment errno 80 @c DO NOT REMOVE
819 ???
820 @end deftypevr
821
822 @comment errno.h
823 @comment BSD: Need authenticator
824 @deftypevr Macro int ENEEDAUTH
825 @comment errno 81 @c DO NOT REMOVE
826 ???
827 @end deftypevr
828
829 @comment errno.h
830 @comment POSIX.1: Function not implemented
831 @deftypevr Macro int ENOSYS
832 @comment errno 78 @c DO NOT REMOVE
833 Function not implemented.  Some functions have commands or options defined
834 that might not be supported in all implementations, and this is the kind
835 of error you get if you request them and they are not supported.
836 @end deftypevr
837
838 @comment errno.h
839 @comment GNU: Inappropriate operation for background process
840 @deftypevr Macro int EBACKGROUND
841 @comment errno 100 @c DO NOT REMOVE
842 In the GNU system, servers supporting the @code{term} protocol return
843 this error for certain operations when the caller is not in the
844 foreground process group of the terminal.  Users do not usually see this
845 error because functions such as @code{read} and @code{write} translate
846 it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
847 for information on process groups and these signals.
848 @end deftypevr
849
850 @comment errno.h
851 @comment GNU: Translator died
852 @deftypevr Macro int EDIED
853 @comment errno 101 @c DO NOT REMOVE
854 In the GNU system, opening a file returns this error when the file is
855 translated by a program and the translator program dies while starting
856 up, before it has connected to the file.
857 @end deftypevr
858
859 @comment errno.h
860 @comment GNU: ?
861 @deftypevr Macro int ED
862 @comment errno 102 @c DO NOT REMOVE
863 The experienced user will know what is wrong.
864 @end deftypevr
865
866 @comment errno.h
867 @comment GNU: You really blew it this time
868 @deftypevr Macro int EGREGIOUS
869 @comment errno 103 @c DO NOT REMOVE
870 You did @strong{what}?
871 @end deftypevr
872
873 @comment errno.h
874 @comment GNU: Computer bought the farm
875 @deftypevr Macro int EIEIO
876 @comment errno 104 @c DO NOT REMOVE
877 Go home and have a glass of warm, dairy-fresh milk.
878 @end deftypevr
879
880 @comment errno.h
881 @comment GNU: Gratuitous error
882 @deftypevr Macro int EGRATUITOUS
883 @comment errno 105 @c DO NOT REMOVE
884 This error code has no purpose.
885 @end deftypevr
886
887
888 @node Error Messages,  , Error Codes, Error Reporting
889 @section Error Messages
890
891 The library has functions and variables designed to make it easy for
892 your program to report informative error messages in the customary
893 format about the failure of a library call.  The functions
894 @code{strerror} and @code{perror} give you the standard error message
895 for a given error code; the variable
896 @w{@code{program_invocation_short_name}} gives you convenient access to the
897 name of the program that encountered the error.
898
899 @comment string.h
900 @comment ANSI
901 @deftypefun {char *} strerror (int @var{errnum})
902 The @code{strerror} function maps the error code (@pxref{Checking for
903 Errors}) specified by the @var{errnum} argument to a descriptive error
904 message string.  The return value is a pointer to this string.
905
906 The value @var{errnum} normally comes from the variable @code{errno}.
907
908 You should not modify the string returned by @code{strerror}.  Also, if
909 you make subsequent calls to @code{strerror}, the string might be
910 overwritten.  (But it's guaranteed that no library function ever calls
911 @code{strerror} behind your back.)
912
913 The function @code{strerror} is declared in @file{string.h}.
914 @end deftypefun
915
916 @comment stdio.h
917 @comment ANSI
918 @deftypefun void perror (const char *@var{message})
919 This function prints an error message to the stream @code{stderr};
920 see @ref{Standard Streams}.
921
922 If you call @code{perror} with a @var{message} that is either a null
923 pointer or an empty string, @code{perror} just prints the error message 
924 corresponding to @code{errno}, adding a trailing newline.
925
926 If you supply a non-null @var{message} argument, then @code{perror}
927 prefixes its output with this string.  It adds a colon and a space 
928 character to separate the @var{message} from the error string corresponding
929 to @code{errno}.
930
931 The function @code{perror} is declared in @file{stdio.h}.
932 @end deftypefun
933
934 @code{strerror} and @code{perror} produce the exact same message for any
935 given error code; the precise text varies from system to system.  On the
936 GNU system, the messages are fairly short; there are no multi-line
937 messages or embedded newlines.  Each error message begins with a capital
938 letter and does not include any terminating punctuation.
939
940 @strong{Compatibility Note:}  The @code{strerror} function is a new
941 feature of ANSI C.  Many older C systems do not support this function
942 yet.
943
944 @cindex program name
945 @cindex name of running program
946 Many programs that don't read input from the terminal are designed to
947 exit if any system call fails.  By convention, the error message from
948 such a program should start with the program's name, sans directories.
949 You can find that name in the variable
950 @code{program_invocation_short_name}; the full file name is stored the
951 variable @code{program_invocation_name}:
952
953 @comment errno.h
954 @comment GNU
955 @deftypevar {char *} program_invocation_name 
956 This variable's value is the name that was used to invoke the program
957 running in the current process.  It is the same as @code{argv[0]}.  Note
958 that this is not necessarily a useful file name; often it contains no
959 directory names.  @xref{Program Arguments}.
960 @end deftypevar
961
962 @comment errno.h
963 @comment GNU
964 @deftypevar {char *} program_invocation_short_name 
965 This variable's value is the name that was used to invoke the program
966 running in the current process, with directory names removed.  (That is
967 to say, it is the same as @code{program_invocation_name} minus
968 everything up to the last slash, if any.)
969 @end deftypevar
970
971 The library initialization code sets up both of these variables before
972 calling @code{main}.
973
974 @strong{Portability Note:} These two variables are GNU extensions.  If
975 you want your program to work with non-GNU libraries, you must save the
976 value of @code{argv[0]} in @code{main}, and then strip off the directory
977 names yourself.  We added these extensions to make it possible to write
978 self-contained error-reporting subroutines that require no explicit
979 cooperation from @code{main}.
980
981 Here is an example showing how to handle failure to open a file
982 correctly.  The function @code{open_sesame} tries to open the named file
983 for reading and returns a stream if successful.  The @code{fopen}
984 library function returns a null pointer if it couldn't open the file for
985 some reason.  In that situation, @code{open_sesame} constructs an
986 appropriate error message using the @code{strerror} function, and
987 terminates the program.  If we were going to make some other library
988 calls before passing the error code to @code{strerror}, we'd have to
989 save it in a local variable instead, because those other library
990 functions might overwrite @code{errno} in the meantime.
991
992 @smallexample
993 #include <errno.h>
994 #include <stdio.h>
995 #include <stdlib.h>
996 #include <string.h>
997
998 FILE *
999 open_sesame (char *name)
1000 @{ 
1001   FILE *stream;
1002
1003   errno = 0;                     
1004   stream = fopen (name, "r");
1005   if (stream == NULL)
1006     @{
1007       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
1008                program_invocation_short_name, name, strerror (errno));
1009       exit (EXIT_FAILURE);
1010     @}
1011   else
1012     return stream;
1013 @}
1014 @end smallexample
1015