(Error Codes): Say that ENOTCONN is instead EDESTADDRREQ for connectionless
[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 @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 Operation not permitted; only the owner of the file (or other resource)
123 or processes with special privileges can perform the operation.
124 @end deftypevr
125
126 @comment errno.h
127 @comment POSIX.1: No such file or directory
128 @deftypevr Macro int ENOENT
129 No such file or directory.  This is a ``file doesn't exist'' error
130 for ordinary files that are referenced in contexts where they are
131 expected to already exist.
132 @end deftypevr
133
134 @comment errno.h
135 @comment POSIX.1: No such process
136 @deftypevr Macro int ESRCH
137 No process matches the specified process ID.
138 @end deftypevr
139
140 @comment errno.h
141 @comment POSIX.1: Interrupted system call
142 @deftypevr Macro int EINTR
143 Interrupted function call; an asynchronous signal occured and prevented
144 completion of the call.  When this happens, you should try the call
145 again.
146
147 You can choose to have functions resume after a signal that is handled,
148 rather than failing with @code{EINTR}; see @ref{Interrupted
149 Primitives}.
150 @end deftypevr
151
152 @comment errno.h
153 @comment POSIX.1: Input/output error
154 @deftypevr Macro int EIO
155 Input/output error; usually used for physical read or write errors.
156 @end deftypevr
157
158 @comment errno.h
159 @comment POSIX.1: Device not configured
160 @deftypevr Macro int ENXIO
161 No such device or address.  The system tried to use the device
162 represented by a file you specified, and it couldn't find the device.
163 This can mean that the device file was installed incorrectly, or that
164 the physical device is missing or not correctly attached to the
165 computer.
166 @end deftypevr
167
168 @comment errno.h
169 @comment POSIX.1: Argument list too long
170 @deftypevr Macro int E2BIG
171 Argument list too long; used when the arguments passed to a new program
172 being executed with one of the @code{exec} functions (@pxref{Executing a
173 File}) occupy too much memory space.  This condition never arises in the
174 GNU system.
175 @end deftypevr
176
177 @comment errno.h
178 @comment POSIX.1: Exec format error
179 @deftypevr Macro int ENOEXEC
180 Invalid executable file format.  This condition is detected by the
181 @code{exec} functions; see @ref{Executing a File}.
182 @end deftypevr
183
184 @comment errno.h
185 @comment POSIX.1: Bad file descriptor
186 @deftypevr Macro int EBADF
187 Bad file descriptor; for example, I/O on a descriptor that has been
188 closed or reading from a descriptor open only for writing (or vice
189 versa).
190 @end deftypevr
191
192 @comment errno.h
193 @comment POSIX.1: No child processes
194 @deftypevr Macro int ECHILD
195 There are no child processes.  This error happens on operations that are
196 supposed to manipulate child processes, when there aren't any processes
197 to manipulate.
198 @end deftypevr
199
200 @comment errno.h
201 @comment POSIX.1: Resource deadlock avoided
202 @deftypevr Macro int EDEADLK
203 Deadlock avoided; allocating a system resource would have resulted in a
204 deadlock situation.  The system does not guarantee that it will notice
205 all such situations.  This error means you got lucky and the system
206 noticed; it might just hang.  @xref{File Locks}, for an example.
207 @end deftypevr
208
209 @comment errno.h
210 @comment POSIX.1: Cannot allocate memory
211 @deftypevr Macro int ENOMEM
212 No memory available.  The system cannot allocate more virtual memory
213 because its capacity is full.
214 @end deftypevr
215
216 @comment errno.h
217 @comment POSIX.1: Permission denied
218 @deftypevr Macro int EACCES
219 Permission denied; the file permissions do not allow the attempted operation.
220 @end deftypevr
221
222 @comment errno.h
223 @comment POSIX.1: Bad address
224 @deftypevr Macro int EFAULT
225 Bad address; an invalid pointer was detected.
226 @end deftypevr
227
228 @comment errno.h
229 @comment BSD: Block device required
230 @deftypevr Macro int ENOTBLK
231 A file that isn't a block special file was given in a situation that
232 requires one.  For example, trying to mount an ordinary file as a file
233 system in Unix gives this error.
234 @end deftypevr
235
236 @comment errno.h
237 @comment POSIX.1: Device busy
238 @deftypevr Macro int EBUSY
239 Resource busy; a system resource that can't be shared is already in use.
240 For example, if you try to delete a file that is the root of a currently
241 mounted filesystem, you get this error.
242 @end deftypevr
243
244 @comment errno.h
245 @comment POSIX.1: File exists
246 @deftypevr Macro int EEXIST
247 File exists; an existing file was specified in a context where it only
248 makes sense to specify a new file.
249 @end deftypevr
250
251 @comment errno.h
252 @comment POSIX.1: Invalid cross-device link
253 @deftypevr Macro int EXDEV
254 An attempt to make an improper link across file systems was detected.
255 This happens not only when you use @code{link} (@pxref{Hard Links}) but
256 also when you rename a file with @code{rename} (@pxref{Renaming Files}).
257 @end deftypevr
258
259 @comment errno.h
260 @comment POSIX.1: Operation not supported by device
261 @deftypevr Macro int ENODEV
262 The wrong type of device was given to a function that expects a
263 particular sort of device.
264 @end deftypevr
265
266 @comment errno.h
267 @comment POSIX.1: Not a directory
268 @deftypevr Macro int ENOTDIR
269 A file that isn't a directory was specified when a directory is required.
270 @end deftypevr
271
272 @comment errno.h
273 @comment POSIX.1: Is a directory
274 @deftypevr Macro int EISDIR
275 File is a directory; attempting to open a directory for writing gives
276 this error.
277 @end deftypevr
278
279 @comment errno.h
280 @comment POSIX.1: Invalid argument
281 @deftypevr Macro int EINVAL
282 Invalid argument.  This is used to indicate various kinds of problems
283 with passing the wrong argument to a library function.
284 @end deftypevr
285
286 @comment errno.h
287 @comment POSIX.1: Too many open files
288 @deftypevr Macro int EMFILE
289 The current process has too many files open and can't open any more.
290 Duplicate descriptors do count toward this limit.
291 @c !!! In 4.4BSD and GNU, the number of open files is a resource limit
292 @c set with setrlimit.
293 @end deftypevr
294
295 @comment errno.h
296 @comment POSIX.1: Too many open files in system
297 @deftypevr Macro int ENFILE
298 There are too many distinct file openings in the entire system.  Note
299 that any number of linked channels count as just one file opening; see
300 @ref{Linked Channels}.  This error never occurs in the GNU system.
301 @end deftypevr
302
303 @comment errno.h
304 @comment POSIX.1: Inappropriate ioctl for device
305 @deftypevr Macro int ENOTTY
306 Inappropriate I/O control operation, such as trying to set terminal
307 modes on an ordinary file.
308 @end deftypevr
309
310 @comment errno.h
311 @comment BSD: Text file busy
312 @deftypevr Macro int ETXTBSY
313 An attempt to execute a file that is currently open for writing, or
314 write to a file that is currently being executed.  (The name stands
315 for ``text file busy''.)  This is not an error in the GNU system; the
316 text is copied as necessary.
317 @end deftypevr
318
319 @comment errno.h
320 @comment POSIX.1: File too large
321 @deftypevr Macro int EFBIG
322 File too big; the size of a file would be larger than allowed by the system.
323 @end deftypevr
324
325 @comment errno.h
326 @comment POSIX.1: No space left on device
327 @deftypevr Macro int ENOSPC
328 No space left on device; write operation on a file failed because the
329 disk is full.
330 @end deftypevr
331
332 @comment errno.h
333 @comment POSIX.1: Illegal seek
334 @deftypevr Macro int ESPIPE
335 Invalid seek operation (such as on a pipe).
336 @end deftypevr
337
338 @comment errno.h
339 @comment POSIX.1: Read-only file system
340 @deftypevr Macro int EROFS
341 An attempt was made to modify something on a read-only file system.
342 @end deftypevr
343
344 @comment errno.h
345 @comment POSIX.1: Too many links
346 @deftypevr Macro int EMLINK
347 Too many links; the link count of a single file is too large.
348 @code{rename} can cause this error if the file being renamed already has
349 as many links as it can take (@pxref{Renaming Files}).
350 @end deftypevr
351
352 @comment errno.h
353 @comment POSIX.1: Broken pipe
354 @deftypevr Macro int EPIPE
355 Broken pipe; there is no process reading from the other end of a pipe.
356 Every library function that returns this error code also generates a
357 @code{SIGPIPE} signal; this signal terminates the program if not handled
358 or blocked.  Thus, your program will never actually see @code{EPIPE}
359 unless it has handled or blocked @code{SIGPIPE}.
360 @end deftypevr
361
362 @comment errno.h
363 @comment ANSI: Numerical argument out of domain
364 @deftypevr Macro int EDOM
365 Domain error; used by mathematical functions when an argument value does
366 not fall into the domain over which the function is defined.
367 @end deftypevr
368
369 @comment errno.h
370 @comment ANSI: Numerical result out of range
371 @deftypevr Macro int ERANGE
372 Range error; used by mathematical functions when the result value is
373 not representable because of overflow or underflow.
374 @end deftypevr
375
376 @comment errno.h
377 @comment POSIX.1: Resource temporarily unavailable
378 @deftypevr Macro int EAGAIN
379 Resource temporarily unavailable; the call might work if you try again
380 later.  Only @code{fork} returns error code @code{EAGAIN} for such a
381 reason.
382 @c !!! sysv uses it somehow?  Don't say "only fork" when ==EWOULDBLOCK.
383 @end deftypevr
384
385 @comment errno.h
386 @comment BSD: Operation would block
387 @deftypevr Macro int EWOULDBLOCK
388 An operation that would block was attempted on an object that has
389 non-blocking mode selected.
390
391 @strong{Portability Note:} In 4.4BSD and GNU, @code{EWOULDBLOCK} and
392 @code{EAGAIN} are the same.  Earlier versions of BSD (@pxref{Berkeley
393 Unix}) have two distinct codes, and use @code{EWOULDBLOCK} to indicate
394 an I/O operation that would block on an object with non-blocking mode
395 set, and @code{EAGAIN} for other kinds of errors.@refill
396 @end deftypevr
397
398 @comment errno.h
399 @comment BSD: Operation now in progress
400 @deftypevr Macro int EINPROGRESS
401 An operation that cannot complete immediately was initiated on an object
402 that has non-blocking mode selected.  Some functions that must always
403 block (such as @code{connect}; @pxref{Connecting}) never return
404 @code{EWOULDBLOCK}.
405 @c !!! EAGAIN?
406 Instead, they return @code{EINPROGRESS} to indicate that the operation
407 has begun and will take some time.  Attempts to manipulate the object
408 before the call completes return @code{EALREADY}.
409 @end deftypevr
410
411 @comment errno.h
412 @comment BSD: Operation already in progress
413 @deftypevr Macro int EALREADY
414 An operation is already in progress on an object that has non-blocking
415 mode selected.
416 @end deftypevr
417
418 @comment errno.h
419 @comment BSD: Socket operation on non-socket
420 @deftypevr Macro int ENOTSOCK
421 A file that isn't a socket was specified when a socket is required.
422 @end deftypevr
423
424 @comment errno.h
425 @comment BSD: Message too long
426 @deftypevr Macro int EMSGSIZE
427 The size of a message sent on a socket was larger than the supported
428 maximum size.  
429 @end deftypevr
430
431 @comment errno.h
432 @comment BSD: Protocol wrong type for socket
433 @deftypevr Macro int EPROTOTYPE
434 The socket type does not support the requested communications protocol.
435 @end deftypevr
436
437 @comment errno.h
438 @comment BSD: Protocol not available
439 @deftypevr Macro int ENOPROTOOPT
440 You specified a socket option that doesn't make sense for the
441 particular protocol being used by the socket.  @xref{Socket Options}.
442 @end deftypevr
443
444 @comment errno.h
445 @comment BSD: Protocol not supported
446 @deftypevr Macro int EPROTONOSUPPORT
447 The socket domain does not support the requested communications protocol
448 (perhaps because the requested protocol is completely invalid.)
449 @xref{Creating a Socket}.
450 @end deftypevr
451
452 @comment errno.h
453 @comment BSD: Socket type not supported
454 @deftypevr Macro int ESOCKTNOSUPPORT
455 The socket type is not supported.
456 @end deftypevr
457
458 @comment errno.h
459 @comment BSD: Operation not supported
460 @deftypevr Macro int EOPNOTSUPP
461 The operation you requested is not supported.  Some socket functions
462 don't make sense for all types of sockets, and others may not be implemented
463 for all communications protocols.
464 @end deftypevr
465
466 @comment errno.h
467 @comment BSD: Protocol family not supported
468 @deftypevr Macro int EPFNOSUPPORT
469 The socket communications protocol family you requested is not supported.
470 @end deftypevr
471
472 @comment errno.h
473 @comment BSD: Address family not supported by protocol family
474 @deftypevr Macro int EAFNOSUPPORT
475 The address family specified for a socket is not supported; it is
476 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
477 @end deftypevr
478
479 @comment errno.h
480 @comment BSD: Address already in use
481 @deftypevr Macro int EADDRINUSE
482 The requested socket address is already in use.  @xref{Socket Addresses}.
483 @end deftypevr
484
485 @comment errno.h
486 @comment BSD: Can't assign requested address
487 @deftypevr Macro int EADDRNOTAVAIL
488 The requested socket address is not available; for example, you tried
489 to give a socket a name that doesn't match the local host name.
490 @xref{Socket Addresses}.
491 @end deftypevr
492
493 @comment errno.h
494 @comment BSD: Network is down
495 @deftypevr Macro int ENETDOWN
496 A socket operation failed because the network was down.
497 @end deftypevr
498
499 @comment errno.h
500 @comment BSD: Network is unreachable
501 @deftypevr Macro int ENETUNREACH
502 A socket operation failed because the subnet containing the remost host
503 was unreachable.
504 @end deftypevr
505
506 @comment errno.h
507 @comment BSD: Network dropped connection on reset
508 @deftypevr Macro int ENETRESET
509 A network connection was reset because the remote host crashed.
510 @end deftypevr
511
512 @comment errno.h
513 @comment BSD: Software caused connection abort
514 @deftypevr Macro int ECONNABORTED
515 A network connection was aborted locally.
516 @end deftypevr
517
518 @comment errno.h
519 @comment BSD: Connection reset by peer
520 @deftypevr Macro int ECONNRESET
521 A network connection was closed for reasons outside the control of the
522 local host, such as by the remote machine rebooting or an unrecoverable
523 protocol violation.
524 @end deftypevr
525
526 @comment errno.h
527 @comment BSD: No buffer space available
528 @deftypevr Macro int ENOBUFS
529 The kernel's buffers for I/O operations are all in use.  In GNU, this
530 error is always synonymous with @code{ENOMEM}; you may get one or the
531 other from network operations.
532 @end deftypevr
533
534 @comment errno.h
535 @comment BSD: Socket is already connected
536 @deftypevr Macro int EISCONN
537 You tried to connect a socket that is already connected.
538 @xref{Connecting}.
539 @end deftypevr
540
541 @comment errno.h
542 @comment BSD: Socket is not connected
543 @deftypevr Macro int ENOTCONN
544 The socket is not connected to anything.  You get this error when you
545 try to transmit data over a socket, without first specifying a
546 destination for the data.  For a connectionless socket (for datagram
547 protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
548 @end deftypevr
549
550 @comment errno.h
551 @comment BSD: Destination address required
552 @deftypevr Macro int EDESTADDRREQ
553 No destination address was supplied on a socket operation that needed one.
554 @end deftypevr
555
556 @comment errno.h
557 @comment BSD: Can't send after socket shutdown
558 @deftypevr Macro int ESHUTDOWN
559 The socket has already been shut down.
560 @end deftypevr
561
562 @comment errno.h
563 @comment BSD: Connection timed out
564 @deftypevr Macro int ETIMEDOUT
565 A socket operation with a specified timeout received no response during
566 the timeout period.
567 @end deftypevr
568
569 @comment errno.h
570 @comment BSD: Connection refused
571 @deftypevr Macro int ECONNREFUSED
572 A remote host refused to allow the network connection (typically because
573 it is not running the requested service).
574 @end deftypevr
575
576 @comment errno.h
577 @comment BSD: Too many levels of symbolic links
578 @deftypevr Macro int ELOOP
579 Too many levels of symbolic links were encountered in looking up a file name.
580 This often indicates a cycle of symbolic links.
581 @end deftypevr
582
583 @comment errno.h
584 @comment POSIX.1: File name too long
585 @deftypevr Macro int ENAMETOOLONG
586 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
587 Files}) or host name too long (in @code{gethostname} or
588 @code{sethostname}; @pxref{Host Identification}).
589 @end deftypevr
590
591 @comment errno.h
592 @comment BSD: Host is down
593 @deftypevr Macro int EHOSTDOWN
594 The remote host for a requested network connection is down.
595 @end deftypevr
596
597 @comment errno.h
598 @comment BSD: No route to host
599 @deftypevr Macro int EHOSTUNREACH
600 The remote host for a requested network connection is not reachable.
601 @end deftypevr
602
603 @comment errno.h
604 @comment POSIX.1: Directory not empty
605 @deftypevr Macro int ENOTEMPTY
606 Directory not empty, where an empty directory was expected.  Typically,
607 this error occurs when you are trying to delete a directory.
608 @end deftypevr
609
610 @comment errno.h
611 @comment BSD: Too many users
612 @deftypevr Macro int EUSERS
613 The file quota system is confused because there are too many users.
614 @c This can probably happen in a GNU system when using NFS.
615 @end deftypevr
616
617 @comment errno.h
618 @comment BSD: Disc quota exceeded
619 @deftypevr Macro int EDQUOT
620 The user's disk quota was exceeded.
621 @end deftypevr
622
623 @comment errno.h
624 @comment BSD: Stale NFS file handle
625 @deftypevr Macro int ESTALE
626 Stale NFS file handle.  This indicates an internal confusion in the NFS
627 system which is due to file system rearrangements on the server host.
628 Repairing this condition usually requires unmounting and remounting
629 the NFS file system on the local host.
630 @end deftypevr
631
632 @comment errno.h
633 @comment BSD: Too many levels of remote in path
634 @deftypevr Macro int EREMOTE
635 An attempt was made to NFS-mount a remote file system with a file name that
636 already specifies an NFS-mounted file.
637 (This is an error on some operating systems, but we expect it to work
638 properly on the GNU system, making this error code impossible.)
639 @end deftypevr
640
641 @comment errno.h
642 @comment POSIX.1: No locks available
643 @deftypevr Macro int ENOLCK
644 No locks available.  This is used by the file locking facilities;
645 see @ref{File Locks}.
646 This error never occurs in the GNU system.
647 @end deftypevr
648
649 @comment errno.h
650 @comment POSIX.1: Function not implemented
651 @deftypevr Macro int ENOSYS
652 Function not implemented.  Some functions have commands or options defined
653 that might not be supported in all implementations, and this is the kind
654 of error you get if you request them and they are not supported.
655 @end deftypevr
656
657 @comment errno.h
658 @comment GNU: Inappropriate operation for background process
659 @deftypevr Macro int EBACKGROUND
660 In the GNU system, servers supporting the @code{term} protocol return
661 this error for certain operations when the caller is not in the
662 foreground process group of the terminal.  Users do not usually see this
663 error because functions such as @code{read} and @code{write} translate
664 it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
665 for information on process groups and these signals.
666 @end deftypevr
667
668 @comment errno.h
669 @comment GNU: Translator died
670 @deftypevr Macro int EDIED
671 In the GNU system, opening a file returns this error when the file is
672 translated by a program and the translator program dies while starting
673 up, before it has connected to the file.
674 @end deftypevr
675
676 @comment errno.h
677 @comment GNU: ?
678 @deftypevr Macro int ED
679 The experienced user will know what is wrong.
680 @end deftypevr
681
682 @comment errno.h
683 @comment GNU: You really blew it this time
684 @deftypevr Macro int EGREGIOUS
685 You did @strong{what}?
686 @end deftypevr
687
688 @comment errno.h
689 @comment GNU: Computer bought the farm
690 @deftypevr Macro int EIEIO
691 Go home and have a glass of warm, dairy-fresh milk.
692 @end deftypevr
693
694 @comment errno.h
695 @comment GNU: Gratuitous error
696 @deftypevr Macro int EGRATUITOUS
697 This error code has no purpose.
698 @end deftypevr
699
700
701 @node Error Messages,  , Error Codes, Error Reporting
702 @section Error Messages
703
704 The library has functions and variables designed to make it easy for
705 your program to report informative error messages in the customary
706 format about the failure of a library call.  The functions
707 @code{strerror} and @code{perror} give you the standard error message
708 for a given error code; the variable
709 @code{program_invocation_short_name} gives you convenient access to the
710 name of the program that encountered the error.
711
712 @comment string.h
713 @comment ANSI
714 @deftypefun {char *} strerror (int @var{errnum})
715 The @code{strerror} function maps the error code (@pxref{Checking for
716 Errors}) specified by the @var{errnum} argument to a descriptive error
717 message string.  The return value is a pointer to this string.
718
719 The value @var{errnum} normally comes from the variable @code{errno}.
720
721 You should not modify the string returned by @code{strerror}.  Also, if
722 you make subsequent calls to @code{strerror}, the string might be
723 overwritten.  (But it's guaranteed that no library function ever calls
724 @code{strerror} behind your back.)
725
726 The function @code{strerror} is declared in @file{string.h}.
727 @end deftypefun
728
729 @comment stdio.h
730 @comment ANSI
731 @deftypefun void perror (const char *@var{message})
732 This function prints an error message to the stream @code{stderr};
733 see @ref{Standard Streams}.
734
735 If you call @code{perror} with a @var{message} that is either a null
736 pointer or an empty string, @code{perror} just prints the error message 
737 corresponding to @code{errno}, adding a trailing newline.
738
739 If you supply a non-null @var{message} argument, then @code{perror}
740 prefixes its output with this string.  It adds a colon and a space 
741 character to separate the @var{message} from the error string corresponding
742 to @code{errno}.
743
744 The function @code{perror} is declared in @file{stdio.h}.
745 @end deftypefun
746
747 @code{strerror} and @code{perror} produce the exact same message for any
748 given error code; the precise text varies from system to system.  On the
749 GNU system, the messages are fairly short; there are no multi-line
750 messages or embedded newlines.  Each error message begins with a capital
751 letter and does not include any terminating punctuation.
752
753 @strong{Compatibility Note:}  The @code{strerror} function is a new
754 feature of ANSI C.  Many older C systems do not support this function
755 yet.
756
757 @cindex program name
758 @cindex name of running program
759 Many programs that don't read input from the terminal are designed to
760 exit if any system call fails.  By convention, the error message from
761 such a program should start with the program's name, sans directories.
762 You can find that name in the variable
763 @code{program_invocation_short_name}; the full file name is stored the
764 variable @code{program_invocation_name}:
765
766 @comment errno.h
767 @comment GNU
768 @deftypevar {char *} program_invocation_name 
769 This variable's value is the name that was used to invoke the program
770 running in the current process.  It is the same as @code{argv[0]}.  Note
771 that this is not necessarily a useful file name; often it contains no
772 directory names.  @xref{Program Arguments}.
773 @end deftypevar
774
775 @comment errno.h
776 @comment GNU
777 @deftypevar {char *} program_invocation_short_name 
778 This variable's value is the name that was used to invoke the program
779 running in the current process, with directory names removed.  (That is
780 to say, it is the same as @code{program_invocation_name} minus
781 everything up to the last slash, if any.)
782 @end deftypevar
783
784 The library initialization code sets up both of these variables before
785 calling @code{main}.
786
787 @strong{Portability Note:} These two variables are GNU extensions.  If
788 you want your program to work with non-GNU libraries, you must save the
789 value of @code{argv[0]} in @code{main}, and then strip off the directory
790 names yourself.  We added these extensions to make it possible to write
791 self-contained error-reporting subroutines that require no explicit
792 cooperation from @code{main}.
793
794 Here is an example showing how to handle failure to open a file
795 correctly.  The function @code{open_sesame} tries to open the named file
796 for reading and returns a stream if successful.  The @code{fopen}
797 library function returns a null pointer if it couldn't open the file for
798 some reason.  In that situation, @code{open_sesame} constructs an
799 appropriate error message using the @code{strerror} function, and
800 terminates the program.  If we were going to make some other library
801 calls before passing the error code to @code{strerror}, we'd have to
802 save it in a local variable instead, because those other library
803 functions might overwrite @code{errno} in the meantime.
804
805 @smallexample
806 #include <errno.h>
807 #include <stdio.h>
808 #include <stdlib.h>
809 #include <string.h>
810
811 FILE *
812 open_sesame (char *name)
813 @{ 
814   FILE *stream;
815
816   errno = 0;                     
817   stream = fopen (name, "r");
818   if (stream == NULL)
819     @{
820       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
821                program_invocation_short_name, name, strerror (errno));
822       exit (EXIT_FAILURE);
823     @}
824   else
825     return stream;
826 @}
827 @end smallexample
828