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