Formerly stdio/stdio.h.~43~
[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 (Since the values are distinct, you can use them as labels in a
86 @code{switch} statement, for example.)  Your program should not make any
87 other assumptions about the specific values of these symbolic constants.
88
89 The value of @code{errno} doesn't necessarily have to correspond to any
90 of these macros, since some library functions might return other error
91 codes of their own for other situations.  The only values that are
92 guaranteed to be meaningful for a particular library function are the
93 ones that this manual lists for that function.
94
95 On non-GNU systems, almost any system call can return @code{EFAULT} if
96 it is given an invalid pointer as an argument.  Since this could only
97 happen as a result of a bug in your program, and since it will not
98 happen on the GNU system, we have saved space by not mentioning
99 @code{EFAULT} in the descriptions of individual functions.
100
101 @c !!! In GNU, many functions can fail with ENOMEM.
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.  For an example, @xref{File Locks}.
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 in system
275 @deftypevr Macro int ENFILE
276 There are too many distinct file openings in the entire system.  Note
277 that any number of linked channels count as just one file opening; see
278 @ref{Linked Channels}.
279 @c !!! this will never happen in GNU; EMFILE or ENOMEM instead.
280 @c ??? I'm not sure it is a good thing to return ENOMEM
281 @c ??? in a case where programmers have been told to expect ENFILE--rms.
282 @end deftypevr
283
284 @comment errno.h
285 @comment POSIX.1: Too many open files
286 @deftypevr Macro int EMFILE
287 The current process has too many files open and can't open any more.
288 Duplicate descriptors do count toward this limit.
289 @c !!! In 4.4BSD and GNU, the number of open files is a resource limit
290 @c set with setrlimit.
291 @end deftypevr
292
293 @comment errno.h
294 @comment POSIX.1: Inappropriate ioctl for device
295 @deftypevr Macro int ENOTTY
296 Inappropriate I/O control operation, such as trying to set terminal
297 modes on an ordinary file.
298 @end deftypevr
299
300 @comment errno.h
301 @comment BSD: Text file busy
302 @deftypevr Macro int ETXTBSY
303 An attempt to execute a file that is currently open for writing, or
304 write to a file that is currently being executed.  (The name stands
305 for ``text file busy''.)  This is not an error in the GNU system; the
306 text is copied as necessary.
307 @end deftypevr
308
309 @comment errno.h
310 @comment POSIX.1: File too large
311 @deftypevr Macro int EFBIG
312 File too big; the size of a file would be larger than allowed by the system.
313 @end deftypevr
314
315 @comment errno.h
316 @comment POSIX.1: No space left on device
317 @deftypevr Macro int ENOSPC
318 No space left on device; write operation on a file failed because the
319 disk is full.
320 @end deftypevr
321
322 @comment errno.h
323 @comment POSIX.1: Illegal seek
324 @deftypevr Macro int ESPIPE
325 Invalid seek operation (such as on a pipe).
326 @end deftypevr
327
328 @comment errno.h
329 @comment POSIX.1: Read-only file system
330 @deftypevr Macro int EROFS
331 An attempt was made to modify a file on a read-only file system.
332 @end deftypevr
333
334 @comment errno.h
335 @comment POSIX.1: Too many links
336 @deftypevr Macro int EMLINK
337 Too many links; the link count of a single file is too large.
338 @end deftypevr
339
340 @comment errno.h
341 @comment POSIX.1: Broken pipe
342 @deftypevr Macro int EPIPE
343 Broken pipe; there is no process reading from the other end of a pipe.
344 Every library function that returns this error code also generates a
345 @code{SIGPIPE} signal; this signal terminates the program if not handled
346 or blocked.  Thus, your program will never actually see @code{EPIPE}
347 unless it has handled or blocked @code{SIGPIPE}.
348 @end deftypevr
349
350 @comment errno.h
351 @comment ANSI: Numerical argument out of domain
352 @deftypevr Macro int EDOM
353 Domain error; used by mathematical functions when an argument value does
354 not fall into the domain over which the function is defined.
355 @end deftypevr
356
357 @comment errno.h
358 @comment ANSI: Numerical result out of range
359 @deftypevr Macro int ERANGE
360 Range error; used by mathematical functions when the result value is
361 not representable because of overflow or underflow.
362 @end deftypevr
363
364 @comment errno.h
365 @comment POSIX.1: Resource temporarily unavailable
366 @deftypevr Macro int EAGAIN
367 Resource temporarily unavailable; the call might work if you try again
368 later.  Only @code{fork} returns error code @code{EAGAIN} for such a
369 reason.
370 @end deftypevr
371
372 @comment errno.h
373 @comment BSD: Operation would block
374 @deftypevr Macro int EWOULDBLOCK
375 An operation that would block was attempted on an object that has
376 non-blocking mode selected.
377
378 @strong{Portability Note:} In 4.4BSD and GNU, @code{EWOULDBLOCK} and
379 @code{EAGAIN} are the same.  Earlier versions of BSD (@pxref{Berkeley
380 Unix}) have two distinct codes, and use @code{EWOULDBLOCK} to indicate
381 an I/O operation that would block on an object with non-blocking mode
382 set, and @code{EAGAIN} for other kinds of errors.@refill
383 @end deftypevr
384
385 @comment errno.h
386 @comment BSD: Operation now in progress
387 @deftypevr Macro int EINPROGRESS
388 An operation that cannot complete immediately was initiated on an object
389 that has non-blocking mode selected.
390 @end deftypevr
391
392 @comment errno.h
393 @comment BSD: Operation already in progress
394 @deftypevr Macro int EALREADY
395 An operation is already in progress on an object that has non-blocking
396 mode selected.
397 @end deftypevr
398
399 @comment errno.h
400 @comment BSD: Socket operation on non-socket
401 @deftypevr Macro int ENOTSOCK
402 A file that isn't a socket was specified when a socket is required.
403 @end deftypevr
404
405 @comment errno.h
406 @comment BSD: Destination address required
407 @deftypevr Macro int EDESTADDRREQ
408 No destination address was supplied on a socket operation.
409 @end deftypevr
410
411 @comment errno.h
412 @comment BSD: Message too long
413 @deftypevr Macro int EMSGSIZE
414 The size of a message sent on a socket was larger than the supported
415 maximum size.  
416 @end deftypevr
417
418 @comment errno.h
419 @comment BSD: Protocol wrong type for socket
420 @deftypevr Macro int EPROTOTYPE
421 The socket type does not support the requested communications protocol.
422 @end deftypevr
423
424 @comment errno.h
425 @comment BSD: Protocol not available
426 @deftypevr Macro int ENOPROTOOPT
427 You specified a socket option that doesn't make sense for the
428 particular protocol being used by the socket.  @xref{Socket Options}.
429 @end deftypevr
430
431 @comment errno.h
432 @comment BSD: Protocol not supported
433 @deftypevr Macro int EPROTONOSUPPORT
434 The socket domain does not support the requested communications protocol.
435 @xref{Creating a Socket}.
436 @end deftypevr
437
438 @comment errno.h
439 @comment BSD: Socket type not supported
440 @deftypevr Macro int ESOCKTNOSUPPORT
441 The socket type is not supported.
442 @end deftypevr
443
444 @comment errno.h
445 @comment BSD: Operation not supported
446 @deftypevr Macro int EOPNOTSUPP
447 The operation you requested is not supported.  Some socket functions
448 don't make sense for all types of sockets, and others may not be implemented
449 for all communications protocols.
450 @end deftypevr
451
452 @comment errno.h
453 @comment BSD: Protocol family not supported
454 @deftypevr Macro int EPFNOSUPPORT
455 The socket communications protocol family you requested is not supported.
456 @end deftypevr
457
458 @comment errno.h
459 @comment BSD: Address family not supported by protocol family
460 @deftypevr Macro int EAFNOSUPPORT
461 The address family specified for a socket is not supported; it is
462 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
463 @end deftypevr
464
465 @comment errno.h
466 @comment BSD: Address already in use
467 @deftypevr Macro int EADDRINUSE
468 The requested socket address is already in use.  @xref{Socket Addresses}.
469 @end deftypevr
470
471 @comment errno.h
472 @comment BSD: Can't assign requested address
473 @deftypevr Macro int EADDRNOTAVAIL
474 The requested socket address is not available; for example, you tried
475 to give a socket a name that doesn't match the local host name.
476 @xref{Socket Addresses}.
477 @end deftypevr
478
479 @comment errno.h
480 @comment BSD: Network is down
481 @deftypevr Macro int ENETDOWN
482 A socket operation failed because the network was down.
483 @end deftypevr
484
485 @comment errno.h
486 @comment BSD: Network is unreachable
487 @deftypevr Macro int ENETUNREACH
488 A socket operation failed because the subnet containing the remost host
489 was unreachable.
490 @end deftypevr
491
492 @comment errno.h
493 @comment BSD: Network dropped connection on reset
494 @deftypevr Macro int ENETRESET
495 A network connection was reset because the remote host crashed.
496 @end deftypevr
497
498 @comment errno.h
499 @comment BSD: Software caused connection abort
500 @deftypevr Macro int ECONNABORTED
501 A network connection was aborted locally.
502 @end deftypevr
503
504 @comment errno.h
505 @comment BSD: Connection reset by peer
506 @deftypevr Macro int ECONNRESET
507 A network connection was closed for reasons outside the control of the
508 local host, such as by the remote machine rebooting.
509 @end deftypevr
510
511 @comment errno.h
512 @comment BSD: No buffer space available
513 @deftypevr Macro int ENOBUFS
514 The kernel's buffers for I/O operations are all in use.
515 @c !!! this will probably never happen in GNU (I'm presuming the
516 @c eventual implementation of the network won't want to use it); you get
517 @c ENOMEM instead.
518 @c ??? I think the network code should convert ENOMEM into ENOBUFS
519 @c ??? just to be compatible--rms.
520 @end deftypevr
521
522 @comment errno.h
523 @comment BSD: Socket is already connected
524 @deftypevr Macro int EISCONN
525 You tried to connect a socket that is already connected.
526 @xref{Connecting}.
527 @end deftypevr
528
529 @comment errno.h
530 @comment BSD: Socket is not connected
531 @deftypevr Macro int ENOTCONN
532 The socket is not connected to anything.  You get this error when you
533 try to transmit data over a socket, without first specifying a destination
534 for the data.
535 @end deftypevr
536
537 @comment errno.h
538 @comment BSD: Can't send after socket shutdown
539 @deftypevr Macro int ESHUTDOWN
540 The socket has already been shut down.
541 @end deftypevr
542
543 @comment errno.h
544 @comment BSD: Connection timed out
545 @deftypevr Macro int ETIMEDOUT
546 A socket operation with a specified timeout received no response during
547 the timeout period.
548 @end deftypevr
549
550 @comment errno.h
551 @comment BSD: Connection refused
552 @deftypevr Macro int ECONNREFUSED
553 A remote host refused to allow the network connection (typically because
554 it is not running the requested service).
555 @end deftypevr
556
557 @comment errno.h
558 @comment BSD: Too many levels of symbolic links
559 @deftypevr Macro int ELOOP
560 Too many levels of symbolic links were encountered in looking up a file name.
561 This often indicates a cycle of symbolic links.
562 @end deftypevr
563
564 @comment errno.h
565 @comment POSIX.1: File name too long
566 @deftypevr Macro int ENAMETOOLONG
567 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
568 Files}) or host name too long (in @code{gethostname} or
569 @code{sethostname}; @pxref{Host Identification}).
570 @end deftypevr
571
572 @comment errno.h
573 @comment BSD: Host is down
574 @deftypevr Macro int EHOSTDOWN
575 The remote host for a requested network connection is down.
576 @end deftypevr
577
578 @comment errno.h
579 @comment BSD: No route to host
580 @deftypevr Macro int EHOSTUNREACH
581 The remote host for a requested network connection is not reachable.
582 @end deftypevr
583
584 @comment errno.h
585 @comment POSIX.1: Directory not empty
586 @deftypevr Macro int ENOTEMPTY
587 Directory not empty, where an empty directory was expected.  Typically,
588 this error occurs when you are trying to delete a directory.
589 @end deftypevr
590
591 @comment errno.h
592 @comment BSD: Too many users
593 @deftypevr Macro int EUSERS
594 The file quota system is confused because there are too many users.
595 @c This can probably happen in a GNU system when using NFS.
596 @end deftypevr
597
598 @comment errno.h
599 @comment BSD: Disc quota exceeded
600 @deftypevr Macro int EDQUOT
601 The user's disk quota was exceeded.
602 @end deftypevr
603
604 @comment errno.h
605 @comment BSD: Stale NFS file handle
606 @deftypevr Macro int ESTALE
607 Stale NFS file handle.  This indicates an internal confusion in the NFS
608 system which is due to file system rearrangements on the server host.
609 Repairing this condition usually requires unmounting and remounting
610 the NFS file system on the local host.
611 @end deftypevr
612
613 @comment errno.h
614 @comment BSD: Too many levels of remote in path
615 @deftypevr Macro int EREMOTE
616 An attempt was made to NFS-mount a remote file system with a file name that
617 already specifies an NFS-mounted file.
618 (This is an error on some operating systems, but we expect it to work
619 properly on the GNU system, making this error code impossible.)
620 @end deftypevr
621
622 @comment errno.h
623 @comment POSIX.1: No locks available
624 @deftypevr Macro int ENOLCK
625 No locks available.  This is used by the file locking facilities;
626 see @ref{File Locks}.
627 @end deftypevr
628
629 @comment errno.h
630 @comment POSIX.1: Function not implemented
631 @deftypevr Macro int ENOSYS
632 Function not implemented.  Some functions have commands or options defined
633 that might not be supported in all implementations, and this is the kind
634 of error you get if you request them and they are not supported.
635 @end deftypevr
636
637 @comment errno.h
638 @comment GNU: ?
639 @deftypevr Macro int ED
640 The experienced user will know what is wrong.
641 @end deftypevr
642
643 @comment errno.h
644 @comment GNU: Gratuitous error
645 @deftypevr Macro int EGRATUITOUS
646 This error code has no purpose.
647 @end deftypevr
648
649
650 @node Error Messages,  , Error Codes, Error Reporting
651 @section Error Messages
652
653 The library has functions and variables designed to make it easy for
654 your program to report informative error messages in the customary
655 format about the failure of a library call.  The functions
656 @code{strerror} and @code{perror} give you the standard error message
657 for a given error code; the variable
658 @code{program_invocation_short_name} gives you convenient access to the
659 name of the program that encountered the error.
660
661 @comment string.h
662 @comment ANSI
663 @deftypefun {char *} strerror (int @var{errnum})
664 The @code{strerror} function maps the error code (@pxref{Checking for
665 Errors}) specified by the @var{errnum} argument to a descriptive error
666 message string.  The return value is a pointer to this string.
667
668 The value @var{errnum} normally comes from the variable @code{errno}.
669
670 You should not modify the string returned by @code{strerror}.  Also, if
671 you make subsequent calls to @code{strerror}, the string might be
672 overwritten.  (But it's guaranteed that no library function ever calls
673 @code{strerror} behind your back.)
674
675 The function @code{strerror} is declared in @file{string.h}.
676 @end deftypefun
677
678 @comment stdio.h
679 @comment ANSI
680 @deftypefun void perror (const char *@var{message})
681 This function prints an error message to the stream @code{stderr};
682 see @ref{Standard Streams}.
683
684 If you call @code{perror} with a @var{message} that is either a null
685 pointer or an empty string, @code{perror} just prints the error message 
686 corresponding to @code{errno}, adding a trailing newline.
687
688 If you supply a non-null @var{message} argument, then @code{perror}
689 prefixes its output with this string.  It adds a colon and a space 
690 character to separate the @var{message} from the error string corresponding
691 to @code{errno}.
692
693 The function @code{perror} is declared in @file{stdio.h}.
694 @end deftypefun
695
696 @code{strerror} and @code{perror} produce the exact same message for any
697 given error code; the precise text varies from system to system.  On the
698 GNU system, the messages are fairly short; there are no multi-line
699 messages or embedded newlines.  Each error message begins with a capital
700 letter and does not include any terminating punctuation.
701
702 @strong{Compatibility Note:}  The @code{strerror} function is a new
703 feature of ANSI C.  Many older C systems do not support this function
704 yet.
705
706 @cindex program name
707 @cindex name of running program
708 Many programs that don't read input from the terminal are designed to
709 exit if any system call fails.  By convention, the error message from
710 such a program should start with the program's name, sans directories.
711 You can find that name in the variable
712 @code{program_invocation_short_name}; the full file name is stored the
713 variable @code{program_invocation_name}:
714
715 @comment errno.h
716 @comment GNU
717 @deftypevar {char *} program_invocation_name 
718 This variable's value is the name that was used to invoke the program
719 running in the current process.  It is the same as @code{argv[0]}.
720 @end deftypevar
721
722 @comment errno.h
723 @comment GNU
724 @deftypevar {char *} program_invocation_short_name 
725 This variable's value is the name that was used to invoke the program
726 running in the current process, with directory names removed.  (That is
727 to say, it is the same as @code{program_invocation_name} minus
728 everything up to the last slash, if any.)
729 @end deftypevar
730
731 Both @code{program_invocation_name} and
732 @code{program_invocation_short_name} are set up by the system before
733 @code{main} is called.
734
735 @strong{Portability Note:} These two variables are GNU extensions.  If
736 you want your program to work with non-GNU libraries, you must save the
737 value of @code{argv[0]} in @code{main}, and then strip off the directory
738 names yourself.  We added these extensions to make it possible to write
739 self-contained error-reporting subroutines that require no explicit
740 cooperation from @code{main}.
741
742 Here is an example showing how to handle failure to open a file
743 correctly.  The function @code{open_sesame} tries to open the named file
744 for reading and returns a stream if successful.  The @code{fopen}
745 library function returns a null pointer if it couldn't open the file for
746 some reason.  In that situation, @code{open_sesame} constructs an
747 appropriate error message using the @code{strerror} function, and
748 terminates the program.  If we were going to make some other library
749 calls before passing the error code to @code{strerror}, we'd have to
750 save it in a local variable instead, because those other library
751 functions might overwrite @code{errno} in the meantime.
752
753 @example
754 #include <errno.h>
755 #include <stdio.h>
756 #include <stdlib.h>
757 #include <string.h>
758
759 FILE *
760 open_sesame (char *name)
761 @{ 
762   FILE *stream;
763
764   errno = 0;                     
765   stream = fopen (name, "r");
766   if (!stream) @{
767     fprintf (stderr, "%s: Couldn't open file %s; %s\n",
768              program_invocation_short_name, name, strerror (errno));
769     exit (EXIT_FAILURE);
770   @} else
771     return stream;
772 @}
773 @end example
774