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