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