762d4711863bd9208ff6133882a5155a9af30482
[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: Destination address required
426 @deftypevr Macro int EDESTADDRREQ
427 No destination address was supplied on a socket operation that needed one.
428 @end deftypevr
429
430 @comment errno.h
431 @comment BSD: Message too long
432 @deftypevr Macro int EMSGSIZE
433 The size of a message sent on a socket was larger than the supported
434 maximum size.  
435 @end deftypevr
436
437 @comment errno.h
438 @comment BSD: Protocol wrong type for socket
439 @deftypevr Macro int EPROTOTYPE
440 The socket type does not support the requested communications protocol.
441 @end deftypevr
442
443 @comment errno.h
444 @comment BSD: Protocol not available
445 @deftypevr Macro int ENOPROTOOPT
446 You specified a socket option that doesn't make sense for the
447 particular protocol being used by the socket.  @xref{Socket Options}.
448 @end deftypevr
449
450 @comment errno.h
451 @comment BSD: Protocol not supported
452 @deftypevr Macro int EPROTONOSUPPORT
453 The socket domain does not support the requested communications protocol
454 (perhaps because the requested protocol is completely invalid.)
455 @xref{Creating a Socket}.
456 @end deftypevr
457
458 @comment errno.h
459 @comment BSD: Socket type not supported
460 @deftypevr Macro int ESOCKTNOSUPPORT
461 The socket type is not supported.
462 @end deftypevr
463
464 @comment errno.h
465 @comment BSD: Operation not supported
466 @deftypevr Macro int EOPNOTSUPP
467 The operation you requested is not supported.  Some socket functions
468 don't make sense for all types of sockets, and others may not be implemented
469 for all communications protocols.
470 @end deftypevr
471
472 @comment errno.h
473 @comment BSD: Protocol family not supported
474 @deftypevr Macro int EPFNOSUPPORT
475 The socket communications protocol family you requested is not supported.
476 @end deftypevr
477
478 @comment errno.h
479 @comment BSD: Address family not supported by protocol family
480 @deftypevr Macro int EAFNOSUPPORT
481 The address family specified for a socket is not supported; it is
482 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
483 @end deftypevr
484
485 @comment errno.h
486 @comment BSD: Address already in use
487 @deftypevr Macro int EADDRINUSE
488 The requested socket address is already in use.  @xref{Socket Addresses}.
489 @end deftypevr
490
491 @comment errno.h
492 @comment BSD: Can't assign requested address
493 @deftypevr Macro int EADDRNOTAVAIL
494 The requested socket address is not available; for example, you tried
495 to give a socket a name that doesn't match the local host name.
496 @xref{Socket Addresses}.
497 @end deftypevr
498
499 @comment errno.h
500 @comment BSD: Network is down
501 @deftypevr Macro int ENETDOWN
502 A socket operation failed because the network was down.
503 @end deftypevr
504
505 @comment errno.h
506 @comment BSD: Network is unreachable
507 @deftypevr Macro int ENETUNREACH
508 A socket operation failed because the subnet containing the remost host
509 was unreachable.
510 @end deftypevr
511
512 @comment errno.h
513 @comment BSD: Network dropped connection on reset
514 @deftypevr Macro int ENETRESET
515 A network connection was reset because the remote host crashed.
516 @end deftypevr
517
518 @comment errno.h
519 @comment BSD: Software caused connection abort
520 @deftypevr Macro int ECONNABORTED
521 A network connection was aborted locally.
522 @end deftypevr
523
524 @comment errno.h
525 @comment BSD: Connection reset by peer
526 @deftypevr Macro int ECONNRESET
527 A network connection was closed for reasons outside the control of the
528 local host, such as by the remote machine rebooting or an unrecoverable
529 protocol violation.
530 @end deftypevr
531
532 @comment errno.h
533 @comment BSD: No buffer space available
534 @deftypevr Macro int ENOBUFS
535 The kernel's buffers for I/O operations are all in use.  In GNU, this
536 error is always synonymous with @code{ENOMEM}; you may get one or the
537 other from network operations.
538 @end deftypevr
539
540 @comment errno.h
541 @comment BSD: Socket is already connected
542 @deftypevr Macro int EISCONN
543 You tried to connect a socket that is already connected.
544 @xref{Connecting}.
545 @end deftypevr
546
547 @comment errno.h
548 @comment BSD: Socket is not connected
549 @deftypevr Macro int ENOTCONN
550 The socket is not connected to anything.  You get this error when you
551 try to transmit data over a socket, without first specifying a destination
552 for the data.
553 @end deftypevr
554
555 @comment errno.h
556 @comment BSD: Can't send after socket shutdown
557 @deftypevr Macro int ESHUTDOWN
558 The socket has already been shut down.
559 @end deftypevr
560
561 @comment errno.h
562 @comment BSD: Connection timed out
563 @deftypevr Macro int ETIMEDOUT
564 A socket operation with a specified timeout received no response during
565 the timeout period.
566 @end deftypevr
567
568 @comment errno.h
569 @comment BSD: Connection refused
570 @deftypevr Macro int ECONNREFUSED
571 A remote host refused to allow the network connection (typically because
572 it is not running the requested service).
573 @end deftypevr
574
575 @comment errno.h
576 @comment BSD: Too many levels of symbolic links
577 @deftypevr Macro int ELOOP
578 Too many levels of symbolic links were encountered in looking up a file name.
579 This often indicates a cycle of symbolic links.
580 @end deftypevr
581
582 @comment errno.h
583 @comment POSIX.1: File name too long
584 @deftypevr Macro int ENAMETOOLONG
585 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
586 Files}) or host name too long (in @code{gethostname} or
587 @code{sethostname}; @pxref{Host Identification}).
588 @end deftypevr
589
590 @comment errno.h
591 @comment BSD: Host is down
592 @deftypevr Macro int EHOSTDOWN
593 The remote host for a requested network connection is down.
594 @end deftypevr
595
596 @comment errno.h
597 @comment BSD: No route to host
598 @deftypevr Macro int EHOSTUNREACH
599 The remote host for a requested network connection is not reachable.
600 @end deftypevr
601
602 @comment errno.h
603 @comment POSIX.1: Directory not empty
604 @deftypevr Macro int ENOTEMPTY
605 Directory not empty, where an empty directory was expected.  Typically,
606 this error occurs when you are trying to delete a directory.
607 @end deftypevr
608
609 @comment errno.h
610 @comment BSD: Too many users
611 @deftypevr Macro int EUSERS
612 The file quota system is confused because there are too many users.
613 @c This can probably happen in a GNU system when using NFS.
614 @end deftypevr
615
616 @comment errno.h
617 @comment BSD: Disc quota exceeded
618 @deftypevr Macro int EDQUOT
619 The user's disk quota was exceeded.
620 @end deftypevr
621
622 @comment errno.h
623 @comment BSD: Stale NFS file handle
624 @deftypevr Macro int ESTALE
625 Stale NFS file handle.  This indicates an internal confusion in the NFS
626 system which is due to file system rearrangements on the server host.
627 Repairing this condition usually requires unmounting and remounting
628 the NFS file system on the local host.
629 @end deftypevr
630
631 @comment errno.h
632 @comment BSD: Too many levels of remote in path
633 @deftypevr Macro int EREMOTE
634 An attempt was made to NFS-mount a remote file system with a file name that
635 already specifies an NFS-mounted file.
636 (This is an error on some operating systems, but we expect it to work
637 properly on the GNU system, making this error code impossible.)
638 @end deftypevr
639
640 @comment errno.h
641 @comment POSIX.1: No locks available
642 @deftypevr Macro int ENOLCK
643 No locks available.  This is used by the file locking facilities;
644 see @ref{File Locks}.
645 This error never occurs in the GNU system.
646 @end deftypevr
647
648 @comment errno.h
649 @comment POSIX.1: Function not implemented
650 @deftypevr Macro int ENOSYS
651 Function not implemented.  Some functions have commands or options defined
652 that might not be supported in all implementations, and this is the kind
653 of error you get if you request them and they are not supported.
654 @end deftypevr
655
656 @comment errno.h
657 @comment GNU: Inappropriate operation for background process
658 @deftypevr Macro int EBACKGROUND
659 In the GNU system, servers supporting the @code{term} protocol return
660 this error for certain operations when the caller is not in the
661 foreground process group of the terminal.  Users do not usually see this
662 error because functions such as @code{read} and @code{write} translate
663 it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
664 for information on process groups and these signals.
665 @end deftypevr
666
667 @comment errno.h
668 @comment GNU: Translator died
669 @deftypevr Macro int EDIED
670 In the GNU system, opening a file returns this error when the file is
671 translated by a program and the translator program dies while starting
672 up, before it has connected to the file.
673 @end deftypevr
674
675 @comment errno.h
676 @comment GNU: ?
677 @deftypevr Macro int ED
678 The experienced user will know what is wrong.
679 @end deftypevr
680
681 @comment errno.h
682 @comment GNU: You really blew it this time
683 @deftypevr Macro int EGREGIOUS
684 You did @strong{what}?
685 @end deftypevr
686
687 @comment errno.h
688 @comment GNU: Computer bought the farm
689 @deftypevr Macro int EIEIO
690 Go home and have a glass of warm, dairy-fresh milk.
691 @end deftypevr
692
693 @comment errno.h
694 @comment GNU: Gratuitous error
695 @deftypevr Macro int EGRATUITOUS
696 This error code has no purpose.
697 @end deftypevr
698
699
700 @node Error Messages,  , Error Codes, Error Reporting
701 @section Error Messages
702
703 The library has functions and variables designed to make it easy for
704 your program to report informative error messages in the customary
705 format about the failure of a library call.  The functions
706 @code{strerror} and @code{perror} give you the standard error message
707 for a given error code; the variable
708 @code{program_invocation_short_name} gives you convenient access to the
709 name of the program that encountered the error.
710
711 @comment string.h
712 @comment ANSI
713 @deftypefun {char *} strerror (int @var{errnum})
714 The @code{strerror} function maps the error code (@pxref{Checking for
715 Errors}) specified by the @var{errnum} argument to a descriptive error
716 message string.  The return value is a pointer to this string.
717
718 The value @var{errnum} normally comes from the variable @code{errno}.
719
720 You should not modify the string returned by @code{strerror}.  Also, if
721 you make subsequent calls to @code{strerror}, the string might be
722 overwritten.  (But it's guaranteed that no library function ever calls
723 @code{strerror} behind your back.)
724
725 The function @code{strerror} is declared in @file{string.h}.
726 @end deftypefun
727
728 @comment stdio.h
729 @comment ANSI
730 @deftypefun void perror (const char *@var{message})
731 This function prints an error message to the stream @code{stderr};
732 see @ref{Standard Streams}.
733
734 If you call @code{perror} with a @var{message} that is either a null
735 pointer or an empty string, @code{perror} just prints the error message 
736 corresponding to @code{errno}, adding a trailing newline.
737
738 If you supply a non-null @var{message} argument, then @code{perror}
739 prefixes its output with this string.  It adds a colon and a space 
740 character to separate the @var{message} from the error string corresponding
741 to @code{errno}.
742
743 The function @code{perror} is declared in @file{stdio.h}.
744 @end deftypefun
745
746 @code{strerror} and @code{perror} produce the exact same message for any
747 given error code; the precise text varies from system to system.  On the
748 GNU system, the messages are fairly short; there are no multi-line
749 messages or embedded newlines.  Each error message begins with a capital
750 letter and does not include any terminating punctuation.
751
752 @strong{Compatibility Note:}  The @code{strerror} function is a new
753 feature of ANSI C.  Many older C systems do not support this function
754 yet.
755
756 @cindex program name
757 @cindex name of running program
758 Many programs that don't read input from the terminal are designed to
759 exit if any system call fails.  By convention, the error message from
760 such a program should start with the program's name, sans directories.
761 You can find that name in the variable
762 @code{program_invocation_short_name}; the full file name is stored the
763 variable @code{program_invocation_name}:
764
765 @comment errno.h
766 @comment GNU
767 @deftypevar {char *} program_invocation_name 
768 This variable's value is the name that was used to invoke the program
769 running in the current process.  It is the same as @code{argv[0]}.  Note
770 that this is not necessarily a useful file name; often it contains no
771 directory names.  @xref{Program Arguments}.
772 @end deftypevar
773
774 @comment errno.h
775 @comment GNU
776 @deftypevar {char *} program_invocation_short_name 
777 This variable's value is the name that was used to invoke the program
778 running in the current process, with directory names removed.  (That is
779 to say, it is the same as @code{program_invocation_name} minus
780 everything up to the last slash, if any.)
781 @end deftypevar
782
783 The library initialization code sets up both of these variables before
784 calling @code{main}.
785
786 @strong{Portability Note:} These two variables are GNU extensions.  If
787 you want your program to work with non-GNU libraries, you must save the
788 value of @code{argv[0]} in @code{main}, and then strip off the directory
789 names yourself.  We added these extensions to make it possible to write
790 self-contained error-reporting subroutines that require no explicit
791 cooperation from @code{main}.
792
793 Here is an example showing how to handle failure to open a file
794 correctly.  The function @code{open_sesame} tries to open the named file
795 for reading and returns a stream if successful.  The @code{fopen}
796 library function returns a null pointer if it couldn't open the file for
797 some reason.  In that situation, @code{open_sesame} constructs an
798 appropriate error message using the @code{strerror} function, and
799 terminates the program.  If we were going to make some other library
800 calls before passing the error code to @code{strerror}, we'd have to
801 save it in a local variable instead, because those other library
802 functions might overwrite @code{errno} in the meantime.
803
804 @smallexample
805 #include <errno.h>
806 #include <stdio.h>
807 #include <stdlib.h>
808 #include <string.h>
809
810 FILE *
811 open_sesame (char *name)
812 @{ 
813   FILE *stream;
814
815   errno = 0;                     
816   stream = fopen (name, "r");
817   if (stream == NULL)
818     @{
819       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
820                program_invocation_short_name, name, strerror (errno));
821       exit (EXIT_FAILURE);
822     @}
823   else
824     return stream;
825 @}
826 @end smallexample
827