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