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