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} when the
  63 function returns an error.
  64
  65 @strong{Portability Note:} ANSI C specifies @code{errno} as a
  66 ``modifiable lvalue'' rather than as a variable, permitting it to be
  67 implemented as a macro.  For example, its expansion might involve a
  68 function call, like @w{@code{*_errno ()}}.  In fact, that is what it is
  69 on the GNU system itself.  The GNU library, on non-GNU systems, does
  70 whatever is right for the particular system.
  71
  72 There are a few library functions, like @code{sqrt} and @code{atan},
  73 that return a perfectly legitimate value in case of an error, but also
  74 set @code{errno}.  For these functions, if you want to check to see
  75 whether an error occurred, the recommended method is to set @code{errno}
  76 to zero before calling the function, and then check its value afterward.
  77 @end deftypevr
  78
  79 @pindex errno.h
  80 All the error codes have symbolic names; they are macros defined in
  81 @file{errno.h}.  The names start with @samp{E} and an upper-case
  82 letter or digit; you should consider names of this form to be
  83 reserved names.  @xref{Reserved Names}.
  84
  85 The error code values are all positive integers and are all distinct,
  86 with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
  87 Since the values are distinct, you can use them as labels in a
  88 @code{switch} statement; just don't use both @code{EWOULDBLOCK} and
  89 @code{EAGAIN}.  Your program should not make any other assumptions about
  90 the specific values of these symbolic constants.
  91
  92 The value of @code{errno} doesn't necessarily have to correspond to any
  93 of these macros, since some library functions might return other error
  94 codes of their own for other situations.  The only values that are
  95 guaranteed to be meaningful for a particular library function are the
  96 ones that this manual lists for that function.
  97
  98 On non-GNU systems, almost any system call can return @code{EFAULT} if
  99 it is given an invalid pointer as an argument.  Since this could only
 100 happen as a result of a bug in your program, and since it will not
 101 happen on the GNU system, we have saved space by not mentioning
 102 @code{EFAULT} in the descriptions of individual functions.
 103
 104 In some Unix systems, many system calls can also return @code{EFAULT} if
 105 given as an argument a pointer into the stack, and the kernel for some
 106 obscure reason fails in its attempt to extend the stack.  If this ever
 107 happens, you should probably try using statically or dynamically
 108 allocated memory instead of stack memory on that system.
 109
 110 @node Error Codes, Error Messages, Checking for Errors, Error Reporting
 111 @section Error Codes
 112
 113 @pindex errno.h
 114 The error code macros are defined in the header file @file{errno.h}.
 115 All of them expand into integer constant values.  Some of these error
 116 codes can't occur on the GNU system, but they can occur using the GNU
 117 library on other systems.
 118
 119 @comment errno.h
 120 @comment POSIX.1: Operation not permitted
 121 @deftypevr Macro int EPERM
 122 @comment errno 1 @c DO NOT REMOVE
 123 Operation not permitted; only the owner of the file (or other resource)
 124 or processes with special privileges can perform the operation.
 125 @end deftypevr
 126
 127 @comment errno.h
 128 @comment POSIX.1: No such file or directory
 129 @deftypevr Macro int ENOENT
 130 @comment errno 2 @c DO NOT REMOVE
 131 No such file or directory.  This is a ``file doesn't exist'' error
 132 for ordinary files that are referenced in contexts where they are
 133 expected to already exist.
 134 @end deftypevr
 135
 136 @comment errno.h
 137 @comment POSIX.1: No such process
 138 @deftypevr Macro int ESRCH
 139 @comment errno 3 @c DO NOT REMOVE
 140 No process matches the specified process ID.
 141 @end deftypevr
 142
 143 @comment errno.h
 144 @comment POSIX.1: Interrupted system call
 145 @deftypevr Macro int EINTR
 146 @comment errno 4 @c DO NOT REMOVE
 147 Interrupted function call; an asynchronous signal occured and prevented
 148 completion of the call.  When this happens, you should try the call
 149 again.
 150
 151 You can choose to have functions resume after a signal that is handled,
 152 rather than failing with @code{EINTR}; see @ref{Interrupted
 153 Primitives}.
 154 @end deftypevr
 155
 156 @comment errno.h
 157 @comment POSIX.1: Input/output error
 158 @deftypevr Macro int EIO
 159 @comment errno 5 @c DO NOT REMOVE
 160 Input/output error; usually used for physical read or write errors.
 161 @end deftypevr
 162
 163 @comment errno.h
 164 @comment POSIX.1: Device not configured
 165 @deftypevr Macro int ENXIO
 166 @comment errno 6 @c DO NOT REMOVE
 167 No such device or address.  The system tried to use the device
 168 represented by a file you specified, and it couldn't find the device.
 169 This can mean that the device file was installed incorrectly, or that
 170 the physical device is missing or not correctly attached to the
 171 computer.
 172 @end deftypevr
 173
 174 @comment errno.h
 175 @comment POSIX.1: Argument list too long
 176 @deftypevr Macro int E2BIG
 177 @comment errno 7 @c DO NOT REMOVE
 178 Argument list too long; used when the arguments passed to a new program
 179 being executed with one of the @code{exec} functions (@pxref{Executing a
 180 File}) occupy too much memory space.  This condition never arises in the
 181 GNU system.
 182 @end deftypevr
 183
 184 @comment errno.h
 185 @comment POSIX.1: Exec format error
 186 @deftypevr Macro int ENOEXEC
 187 @comment errno 8 @c DO NOT REMOVE
 188 Invalid executable file format.  This condition is detected by the
 189 @code{exec} functions; see @ref{Executing a File}.
 190 @end deftypevr
 191
 192 @comment errno.h
 193 @comment POSIX.1: Bad file descriptor
 194 @deftypevr Macro int EBADF
 195 @comment errno 9 @c DO NOT REMOVE
 196 Bad file descriptor; for example, I/O on a descriptor that has been
 197 closed or reading from a descriptor open only for writing (or vice
 198 versa).
 199 @end deftypevr
 200
 201 @comment errno.h
 202 @comment POSIX.1: No child processes
 203 @deftypevr Macro int ECHILD
 204 @comment errno 10 @c DO NOT REMOVE
 205 There are no child processes.  This error happens on operations that are
 206 supposed to manipulate child processes, when there aren't any processes
 207 to manipulate.
 208 @end deftypevr
 209
 210 @comment errno.h
 211 @comment POSIX.1: Resource deadlock avoided
 212 @deftypevr Macro int EDEADLK
 213 @comment errno 11 @c DO NOT REMOVE
 214 Deadlock avoided; allocating a system resource would have resulted in a
 215 deadlock situation.  The system does not guarantee that it will notice
 216 all such situations.  This error means you got lucky and the system
 217 noticed; it might just hang.  @xref{File Locks}, for an example.
 218 @end deftypevr
 219
 220 @comment errno.h
 221 @comment POSIX.1: Cannot allocate memory
 222 @deftypevr Macro int ENOMEM
 223 @comment errno 12 @c DO NOT REMOVE
 224 No memory available.  The system cannot allocate more virtual memory
 225 because its capacity is full.
 226 @end deftypevr
 227
 228 @comment errno.h
 229 @comment POSIX.1: Permission denied
 230 @deftypevr Macro int EACCES
 231 @comment errno 13 @c DO NOT REMOVE
 232 Permission denied; the file permissions do not allow the attempted operation.
 233 @end deftypevr
 234
 235 @comment errno.h
 236 @comment POSIX.1: Bad address
 237 @deftypevr Macro int EFAULT
 238 @comment errno 14 @c DO NOT REMOVE
 239 Bad address; an invalid pointer was detected.
 240 In the GNU system, this error never happens; you get a signal instead.
 241 @end deftypevr
 242
 243 @comment errno.h
 244 @comment BSD: Block device required
 245 @deftypevr Macro int ENOTBLK
 246 @comment errno 15 @c DO NOT REMOVE
 247 A file that isn't a block special file was given in a situation that
 248 requires one.  For example, trying to mount an ordinary file as a file
 249 system in Unix gives this error.
 250 @end deftypevr
 251
 252 @comment errno.h
 253 @comment POSIX.1: Device or resource busy
 254 @deftypevr Macro int EBUSY
 255 @comment errno 16 @c DO NOT REMOVE
 256 Resource busy; a system resource that can't be shared is already in use.
 257 For example, if you try to delete a file that is the root of a currently
 258 mounted filesystem, you get this error.
 259 @end deftypevr
 260
 261 @comment errno.h
 262 @comment POSIX.1: File exists
 263 @deftypevr Macro int EEXIST
 264 @comment errno 17 @c DO NOT REMOVE
 265 File exists; an existing file was specified in a context where it only
 266 makes sense to specify a new file.
 267 @end deftypevr
 268
 269 @comment errno.h
 270 @comment POSIX.1: Invalid cross-device link
 271 @deftypevr Macro int EXDEV
 272 @comment errno 18 @c DO NOT REMOVE
 273 An attempt to make an improper link across file systems was detected.
 274 This happens not only when you use @code{link} (@pxref{Hard Links}) but
 275 also when you rename a file with @code{rename} (@pxref{Renaming Files}).
 276 @end deftypevr
 277
 278 @comment errno.h
 279 @comment POSIX.1: Operation not supported by device
 280 @deftypevr Macro int ENODEV
 281 @comment errno 19 @c DO NOT REMOVE
 282 The wrong type of device was given to a function that expects a
 283 particular sort of device.
 284 @end deftypevr
 285
 286 @comment errno.h
 287 @comment POSIX.1: Not a directory
 288 @deftypevr Macro int ENOTDIR
 289 @comment errno 20 @c DO NOT REMOVE
 290 A file that isn't a directory was specified when a directory is required.
 291 @end deftypevr
 292
 293 @comment errno.h
 294 @comment POSIX.1: Is a directory
 295 @deftypevr Macro int EISDIR
 296 @comment errno 21 @c DO NOT REMOVE
 297 File is a directory; you cannot open a directory for writing,
 298 or create or remove hard links to it.
 299 @end deftypevr
 300
 301 @comment errno.h
 302 @comment POSIX.1: Invalid argument
 303 @deftypevr Macro int EINVAL
 304 @comment errno 22 @c DO NOT REMOVE
 305 Invalid argument.  This is used to indicate various kinds of problems
 306 with passing the wrong argument to a library function.
 307 @end deftypevr
 308
 309 @comment errno.h
 310 @comment POSIX.1: Too many open files
 311 @deftypevr Macro int EMFILE
 312 @comment errno 24 @c DO NOT REMOVE
 313 The current process has too many files open and can't open any more.
 314 Duplicate descriptors do count toward this limit.
 315
 316 In BSD and GNU, the number of open files is controlled by a resource
 317 limit that can usually be increased.  If you get this error, you might
 318 want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited;
 319 @pxref{Limits on Resources}.
 320 @end deftypevr
 321
 322 @comment errno.h
 323 @comment POSIX.1: Too many open files in system
 324 @deftypevr Macro int ENFILE
 325 @comment errno 23 @c DO NOT REMOVE
 326 There are too many distinct file openings in the entire system.  Note
 327 that any number of linked channels count as just one file opening; see
 328 @ref{Linked Channels}.  This error never occurs in the GNU system.
 329 @end deftypevr
 330
 331 @comment errno.h
 332 @comment POSIX.1: Inappropriate ioctl for device
 333 @deftypevr Macro int ENOTTY
 334 @comment errno 25 @c DO NOT REMOVE
 335 Inappropriate I/O control operation, such as trying to set terminal
 336 modes on an ordinary file.
 337 @end deftypevr
 338
 339 @comment errno.h
 340 @comment BSD: Text file busy
 341 @deftypevr Macro int ETXTBSY
 342 @comment errno 26 @c DO NOT REMOVE
 343 An attempt to execute a file that is currently open for writing, or
 344 write to a file that is currently being executed.  Often using a
 345 debugger to run a program is considered having it open for writing and
 346 will cause this error.  (The name stands for ``text file busy''.)  This
 347 is not an error in the GNU system; the text is copied as necessary.
 348 @end deftypevr
 349
 350 @comment errno.h
 351 @comment POSIX.1: File too large
 352 @deftypevr Macro int EFBIG
 353 @comment errno 27 @c DO NOT REMOVE
 354 File too big; the size of a file would be larger than allowed by the system.
 355 @end deftypevr
 356
 357 @comment errno.h
 358 @comment POSIX.1: No space left on device
 359 @deftypevr Macro int ENOSPC
 360 @comment errno 28 @c DO NOT REMOVE
 361 No space left on device; write operation on a file failed because the
 362 disk is full.
 363 @end deftypevr
 364
 365 @comment errno.h
 366 @comment POSIX.1: Illegal seek
 367 @deftypevr Macro int ESPIPE
 368 @comment errno 29 @c DO NOT REMOVE
 369 Invalid seek operation (such as on a pipe).
 370 @end deftypevr
 371
 372 @comment errno.h
 373 @comment POSIX.1: Read-only file system
 374 @deftypevr Macro int EROFS
 375 @comment errno 30 @c DO NOT REMOVE
 376 An attempt was made to modify something on a read-only file system.
 377 @end deftypevr
 378
 379 @comment errno.h
 380 @comment POSIX.1: Too many links
 381 @deftypevr Macro int EMLINK
 382 @comment errno 31 @c DO NOT REMOVE
 383 Too many links; the link count of a single file would become too large.
 384 @code{rename} can cause this error if the file being renamed already has
 385 as many links as it can take (@pxref{Renaming Files}).
 386 @end deftypevr
 387
 388 @comment errno.h
 389 @comment POSIX.1: Broken pipe
 390 @deftypevr Macro int EPIPE
 391 @comment errno 32 @c DO NOT REMOVE
 392 Broken pipe; there is no process reading from the other end of a pipe.
 393 Every library function that returns this error code also generates a
 394 @code{SIGPIPE} signal; this signal terminates the program if not handled
 395 or blocked.  Thus, your program will never actually see @code{EPIPE}
 396 unless it has handled or blocked @code{SIGPIPE}.
 397 @end deftypevr
 398
 399 @comment errno.h
 400 @comment ANSI: Numerical argument out of domain
 401 @deftypevr Macro int EDOM
 402 @comment errno 33 @c DO NOT REMOVE
 403 Domain error; used by mathematical functions when an argument value does
 404 not fall into the domain over which the function is defined.
 405 @end deftypevr
 406
 407 @comment errno.h
 408 @comment ANSI: Numerical result out of range
 409 @deftypevr Macro int ERANGE
 410 @comment errno 34 @c DO NOT REMOVE
 411 Range error; used by mathematical functions when the result value is
 412 not representable because of overflow or underflow.
 413 @end deftypevr
 414
 415 @comment errno.h
 416 @comment POSIX.1: Resource temporarily unavailable
 417 @deftypevr Macro int EAGAIN
 418 @comment errno 35 @c DO NOT REMOVE
 419 Resource temporarily unavailable; the call might work if you try again
 420 later.  The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
 421 they are always the same in the GNU C library.
 422
 423 This error can happen in a few different situations:
 424
 425 @itemize @bullet
 426 @item
 427 An operation that would block was attempted on an object that has
 428 non-blocking mode selected.  Trying the same operation again will block
 429 until some external condition makes it possible to read, write, or
 430 connect (whatever the operation).  You can use @code{select} to find out
 431 when the operation will be possible; @pxref{Waiting for I/O}.
 432
 433 @strong{Portability Note:} In older Unix many systems, this condition
 434 was indicated by @code{EWOULDBLOCK}, which was a distinct error code
 435 different from @code{EAGAIN}.  To make your program portable, you should
 436 check for both codes and treat them the same.
 437
 438 @item
 439 A temporary resource shortage made an operation impossible.  @code{fork}
 440 can return this error.  It indicates that the shortage is expected to
 441 pass, so your program can try the call again later and it may succeed.
 442 It is probably a good idea to delay for a few seconds before trying it
 443 again, to allow time for other processes to release scarce resources.
 444 Such shortages are usually fairly serious and affect the whole system,
 445 so usually an interactive program should report the error to the user
 446 and return to its command loop.
 447 @end itemize
 448 @end deftypevr
 449
 450 @comment errno.h
 451 @comment BSD: Operation would block
 452 @deftypevr Macro int EWOULDBLOCK
 453 @comment errno EAGAIN @c DO NOT REMOVE
 454 In the GNU C library, this is another name for @code{EAGAIN} (above).
 455 The values are always the same, on every operating system.
 456
 457 C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
 458 separate error code.
 459 @end deftypevr
 460
 461 @comment errno.h
 462 @comment BSD: Operation now in progress
 463 @deftypevr Macro int EINPROGRESS
 464 @comment errno 36 @c DO NOT REMOVE
 465 An operation that cannot complete immediately was initiated on an object
 466 that has non-blocking mode selected.  Some functions that must always
 467 block (such as @code{connect}; @pxref{Connecting}) never return
 468 @code{EAGAIN}.  Instead, they return @code{EINPROGRESS} to indicate that
 469 the operation has begun and will take some time.  Attempts to manipulate
 470 the object before the call completes return @code{EALREADY}.  You can
 471 use the @code{select} function to find out when the pending operation
 472 has completed; @pxref{Waiting for I/O}.
 473 @end deftypevr
 474
 475 @comment errno.h
 476 @comment BSD: Operation already in progress
 477 @deftypevr Macro int EALREADY
 478 @comment errno 37 @c DO NOT REMOVE
 479 An operation is already in progress on an object that has non-blocking
 480 mode selected.
 481 @end deftypevr
 482
 483 @comment errno.h
 484 @comment BSD: Socket operation on non-socket
 485 @deftypevr Macro int ENOTSOCK
 486 @comment errno 38 @c DO NOT REMOVE
 487 A file that isn't a socket was specified when a socket is required.
 488 @end deftypevr
 489
 490 @comment errno.h
 491 @comment BSD: Message too long
 492 @deftypevr Macro int EMSGSIZE
 493 @comment errno 40 @c DO NOT REMOVE
 494 The size of a message sent on a socket was larger than the supported
 495 maximum size.
 496 @end deftypevr
 497
 498 @comment errno.h
 499 @comment BSD: Protocol wrong type for socket
 500 @deftypevr Macro int EPROTOTYPE
 501 @comment errno 41 @c DO NOT REMOVE
 502 The socket type does not support the requested communications protocol.
 503 @end deftypevr
 504
 505 @comment errno.h
 506 @comment BSD: Protocol not available
 507 @deftypevr Macro int ENOPROTOOPT
 508 @comment errno 42 @c DO NOT REMOVE
 509 You specified a socket option that doesn't make sense for the
 510 particular protocol being used by the socket.  @xref{Socket Options}.
 511 @end deftypevr
 512
 513 @comment errno.h
 514 @comment BSD: Protocol not supported
 515 @deftypevr Macro int EPROTONOSUPPORT
 516 @comment errno 43 @c DO NOT REMOVE
 517 The socket domain does not support the requested communications protocol
 518 (perhaps because the requested protocol is completely invalid.)
 519 @xref{Creating a Socket}.
 520 @end deftypevr
 521
 522 @comment errno.h
 523 @comment BSD: Socket type not supported
 524 @deftypevr Macro int ESOCKTNOSUPPORT
 525 @comment errno 44 @c DO NOT REMOVE
 526 The socket type is not supported.
 527 @end deftypevr
 528
 529 @comment errno.h
 530 @comment BSD: Operation not supported
 531 @deftypevr Macro int EOPNOTSUPP
 532 @comment errno 45 @c DO NOT REMOVE
 533 The operation you requested is not supported.  Some socket functions
 534 don't make sense for all types of sockets, and others may not be
 535 implemented for all communications protocols.  In the GNU system, this
 536 error can happen for many calls when the object does not support the
 537 particular operation; it is a generic indication that the server knows
 538 nothing to do for that call.
 539 @end deftypevr
 540
 541 @comment errno.h
 542 @comment BSD: Protocol family not supported
 543 @deftypevr Macro int EPFNOSUPPORT
 544 @comment errno 46 @c DO NOT REMOVE
 545 The socket communications protocol family you requested is not supported.
 546 @end deftypevr
 547
 548 @comment errno.h
 549 @comment BSD: Address family not supported by protocol
 550 @deftypevr Macro int EAFNOSUPPORT
 551 @comment errno 47 @c DO NOT REMOVE
 552 The address family specified for a socket is not supported; it is
 553 inconsistent with the protocol being used on the socket.  @xref{Sockets}.
 554 @end deftypevr
 555
 556 @comment errno.h
 557 @comment BSD: Address already in use
 558 @deftypevr Macro int EADDRINUSE
 559 @comment errno 48 @c DO NOT REMOVE
 560 The requested socket address is already in use.  @xref{Socket Addresses}.
 561 @end deftypevr
 562
 563 @comment errno.h
 564 @comment BSD: Cannot assign requested address
 565 @deftypevr Macro int EADDRNOTAVAIL
 566 @comment errno 49 @c DO NOT REMOVE
 567 The requested socket address is not available; for example, you tried
 568 to give a socket a name that doesn't match the local host name.
 569 @xref{Socket Addresses}.
 570 @end deftypevr
 571
 572 @comment errno.h
 573 @comment BSD: Network is down
 574 @deftypevr Macro int ENETDOWN
 575 @comment errno 50 @c DO NOT REMOVE
 576 A socket operation failed because the network was down.
 577 @end deftypevr
 578
 579 @comment errno.h
 580 @comment BSD: Network is unreachable
 581 @deftypevr Macro int ENETUNREACH
 582 @comment errno 51 @c DO NOT REMOVE
 583 A socket operation failed because the subnet containing the remote host
 584 was unreachable.
 585 @end deftypevr
 586
 587 @comment errno.h
 588 @comment BSD: Network dropped connection on reset
 589 @deftypevr Macro int ENETRESET
 590 @comment errno 52 @c DO NOT REMOVE
 591 A network connection was reset because the remote host crashed.
 592 @end deftypevr
 593
 594 @comment errno.h
 595 @comment BSD: Software caused connection abort
 596 @deftypevr Macro int ECONNABORTED
 597 @comment errno 53 @c DO NOT REMOVE
 598 A network connection was aborted locally.
 599 @end deftypevr
 600
 601 @comment errno.h
 602 @comment BSD: Connection reset by peer
 603 @deftypevr Macro int ECONNRESET
 604 @comment errno 54 @c DO NOT REMOVE
 605 A network connection was closed for reasons outside the control of the
 606 local host, such as by the remote machine rebooting or an unrecoverable
 607 protocol violation.
 608 @end deftypevr
 609
 610 @comment errno.h
 611 @comment BSD: No buffer space available
 612 @deftypevr Macro int ENOBUFS
 613 @comment errno 55 @c DO NOT REMOVE
 614 The kernel's buffers for I/O operations are all in use.  In GNU, this
 615 error is always synonymous with @code{ENOMEM}; you may get one or the
 616 other from network operations.
 617 @end deftypevr
 618
 619 @comment errno.h
 620 @comment BSD: Transport endpoint is already connected
 621 @deftypevr Macro int EISCONN
 622 @comment errno 56 @c DO NOT REMOVE
 623 You tried to connect a socket that is already connected.
 624 @xref{Connecting}.
 625 @end deftypevr
 626
 627 @comment errno.h
 628 @comment BSD: Transport endpoint is not connected
 629 @deftypevr Macro int ENOTCONN
 630 @comment errno 57 @c DO NOT REMOVE
 631 The socket is not connected to anything.  You get this error when you
 632 try to transmit data over a socket, without first specifying a
 633 destination for the data.  For a connectionless socket (for datagram
 634 protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
 635 @end deftypevr
 636
 637 @comment errno.h
 638 @comment BSD: Destination address required
 639 @deftypevr Macro int EDESTADDRREQ
 640 @comment errno 39 @c DO NOT REMOVE
 641 No default destination address was set for the socket.  You get this
 642 error when you try to transmit data over a connectionless socket,
 643 without first specifying a destination for the data with @code{connect}.
 644 @end deftypevr
 645
 646 @comment errno.h
 647 @comment BSD: Cannot send after transport endpoint shutdown
 648 @deftypevr Macro int ESHUTDOWN
 649 @comment errno 58 @c DO NOT REMOVE
 650 The socket has already been shut down.
 651 @end deftypevr
 652
 653 @comment errno.h
 654 @comment BSD: Too many references: cannot splice
 655 @deftypevr Macro int ETOOMANYREFS
 656 @comment errno 59 @c DO NOT REMOVE
 657 ???
 658 @end deftypevr
 659
 660 @comment errno.h
 661 @comment BSD: Connection timed out
 662 @deftypevr Macro int ETIMEDOUT
 663 @comment errno 60 @c DO NOT REMOVE
 664 A socket operation with a specified timeout received no response during
 665 the timeout period.
 666 @end deftypevr
 667
 668 @comment errno.h
 669 @comment BSD: Connection refused
 670 @deftypevr Macro int ECONNREFUSED
 671 @comment errno 61 @c DO NOT REMOVE
 672 A remote host refused to allow the network connection (typically because
 673 it is not running the requested service).
 674 @end deftypevr
 675
 676 @comment errno.h
 677 @comment BSD: Too many levels of symbolic links
 678 @deftypevr Macro int ELOOP
 679 @comment errno 62 @c DO NOT REMOVE
 680 Too many levels of symbolic links were encountered in looking up a file name.
 681 This often indicates a cycle of symbolic links.
 682 @end deftypevr
 683
 684 @comment errno.h
 685 @comment POSIX.1: File name too long
 686 @deftypevr Macro int ENAMETOOLONG
 687 @comment errno 63 @c DO NOT REMOVE
 688 Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
 689 Files}) or host name too long (in @code{gethostname} or
 690 @code{sethostname}; @pxref{Host Identification}).
 691 @end deftypevr
 692
 693 @comment errno.h
 694 @comment BSD: Host is down
 695 @deftypevr Macro int EHOSTDOWN
 696 @comment errno 64 @c DO NOT REMOVE
 697 The remote host for a requested network connection is down.
 698 @end deftypevr
 699
 700 @comment errno.h
 701 @comment BSD: No route to host
 702 @deftypevr Macro int EHOSTUNREACH
 703 @comment errno 65 @c DO NOT REMOVE
 704 The remote host for a requested network connection is not reachable.
 705 @end deftypevr
 706
 707 @comment errno.h
 708 @comment POSIX.1: Directory not empty
 709 @deftypevr Macro int ENOTEMPTY
 710 @comment errno 66 @c DO NOT REMOVE
 711 Directory not empty, where an empty directory was expected.  Typically,
 712 this error occurs when you are trying to delete a directory.
 713 @end deftypevr
 714
 715 @comment errno.h
 716 @comment BSD: Too many processes
 717 @deftypevr Macro int EPROCLIM
 718 @comment errno 67 @c DO NOT REMOVE
 719 This means that the per-user limit on new process would be exceeded by
 720 an attempted @code{fork}.  @xref{Limits on Resources}, for details on
 721 the @code{RLIMIT_NPROC} limit.
 722 @end deftypevr
 723
 724 @comment errno.h
 725 @comment BSD: Too many users
 726 @deftypevr Macro int EUSERS
 727 @comment errno 68 @c DO NOT REMOVE
 728 The file quota system is confused because there are too many users.
 729 @c This can probably happen in a GNU system when using NFS.
 730 @end deftypevr
 731
 732 @comment errno.h
 733 @comment BSD: Disc quota exceeded
 734 @deftypevr Macro int EDQUOT
 735 @comment errno 69 @c DO NOT REMOVE
 736 The user's disk quota was exceeded.
 737 @end deftypevr
 738
 739 @comment errno.h
 740 @comment BSD: Stale NFS file handle
 741 @deftypevr Macro int ESTALE
 742 @comment errno 70 @c DO NOT REMOVE
 743 Stale NFS file handle.  This indicates an internal confusion in the NFS
 744 system which is due to file system rearrangements on the server host.
 745 Repairing this condition usually requires unmounting and remounting
 746 the NFS file system on the local host.
 747 @end deftypevr
 748
 749 @comment errno.h
 750 @comment BSD: Object is remote
 751 @deftypevr Macro int EREMOTE
 752 @comment errno 71 @c DO NOT REMOVE
 753 An attempt was made to NFS-mount a remote file system with a file name that
 754 already specifies an NFS-mounted file.
 755 (This is an error on some operating systems, but we expect it to work
 756 properly on the GNU system, making this error code impossible.)
 757 @end deftypevr
 758
 759 @comment errno.h
 760 @comment BSD: RPC struct is bad
 761 @deftypevr Macro int EBADRPC
 762 @comment errno 72 @c DO NOT REMOVE
 763 ???
 764 @end deftypevr
 765
 766 @comment errno.h
 767 @comment BSD: RPC version wrong
 768 @deftypevr Macro int ERPCMISMATCH
 769 @comment errno 73 @c DO NOT REMOVE
 770 ???
 771 @end deftypevr
 772
 773 @comment errno.h
 774 @comment BSD: RPC program not available
 775 @deftypevr Macro int EPROGUNAVAIL
 776 @comment errno 74 @c DO NOT REMOVE
 777 ???
 778 @end deftypevr
 779
 780 @comment errno.h
 781 @comment BSD: RPC program version wrong
 782 @deftypevr Macro int EPROGMISMATCH
 783 @comment errno 75 @c DO NOT REMOVE
 784 ???
 785 @end deftypevr
 786
 787 @comment errno.h
 788 @comment BSD: RPC bad procedure for program
 789 @deftypevr Macro int EPROCUNAVAIL
 790 @comment errno 76 @c DO NOT REMOVE
 791 ???
 792 @end deftypevr
 793
 794 @comment errno.h
 795 @comment POSIX.1: No locks available
 796 @deftypevr Macro int ENOLCK
 797 @comment errno 77 @c DO NOT REMOVE
 798 No locks available.  This is used by the file locking facilities; see
 799 @ref{File Locks}.  This error is never generated by the GNU system, but
 800 it can result from an operation to an NFS server running another
 801 operating system.
 802 @end deftypevr
 803
 804 @comment errno.h
 805 @comment BSD: Inappropriate file type or format
 806 @deftypevr Macro int EFTYPE
 807 @comment errno 79 @c DO NOT REMOVE
 808 Inappropriate file type or format.  The file was the wrong type for the
 809 operation, or a data file had the wrong format.
 810
 811 On some systems @code{chmod} returns this error if you try to set the
 812 sticky bit on a non-directory file; @pxref{Setting Permissions}.
 813 @end deftypevr
 814
 815 @comment errno.h
 816 @comment BSD: Authentication error
 817 @deftypevr Macro int EAUTH
 818 @comment errno 80 @c DO NOT REMOVE
 819 ???
 820 @end deftypevr
 821
 822 @comment errno.h
 823 @comment BSD: Need authenticator
 824 @deftypevr Macro int ENEEDAUTH
 825 @comment errno 81 @c DO NOT REMOVE
 826 ???
 827 @end deftypevr
 828
 829 @comment errno.h
 830 @comment POSIX.1: Function not implemented
 831 @deftypevr Macro int ENOSYS
 832 @comment errno 78 @c DO NOT REMOVE
 833 Function not implemented.  Some functions have commands or options defined
 834 that might not be supported in all implementations, and this is the kind
 835 of error you get if you request them and they are not supported.
 836 @end deftypevr
 837
 838 @comment errno.h
 839 @comment ISO: Invalid or incomplete multibyte or wide character
 840 @deftypevr Macro int EILSEQ
 841 @comment errno 106 @c DO NOT REMOVE
 842 While decoding a multibyte character the function came along an invalid
 843 or an incomplete sequence of bytes or the given wide character is invalid.
 844 @end deftypevr
 845
 846 @comment errno.h
 847 @comment GNU: Inappropriate operation for background process
 848 @deftypevr Macro int EBACKGROUND
 849 @comment errno 100 @c DO NOT REMOVE
 850 In the GNU system, servers supporting the @code{term} protocol return
 851 this error for certain operations when the caller is not in the
 852 foreground process group of the terminal.  Users do not usually see this
 853 error because functions such as @code{read} and @code{write} translate
 854 it into a @code{SIGTTIN} or @code{SIGTTOU} signal.  @xref{Job Control},
 855 for information on process groups and these signals.
 856 @end deftypevr
 857
 858 @comment errno.h
 859 @comment GNU: Translator died
 860 @deftypevr Macro int EDIED
 861 @comment errno 101 @c DO NOT REMOVE
 862 In the GNU system, opening a file returns this error when the file is
 863 translated by a program and the translator program dies while starting
 864 up, before it has connected to the file.
 865 @end deftypevr
 866
 867 @comment errno.h
 868 @comment GNU: ?
 869 @deftypevr Macro int ED
 870 @comment errno 102 @c DO NOT REMOVE
 871 The experienced user will know what is wrong.
 872 @c This error code is a joke.  Its perror text is part of the joke.
 873 @c Don't change it.
 874 @end deftypevr
 875
 876 @comment errno.h
 877 @comment GNU: You really blew it this time
 878 @deftypevr Macro int EGREGIOUS
 879 @comment errno 103 @c DO NOT REMOVE
 880 You did @strong{what}?
 881 @end deftypevr
 882
 883 @comment errno.h
 884 @comment GNU: Computer bought the farm
 885 @deftypevr Macro int EIEIO
 886 @comment errno 104 @c DO NOT REMOVE
 887 Go home and have a glass of warm, dairy-fresh milk.
 888 @end deftypevr
 889
 890 @comment errno.h
 891 @comment GNU: Gratuitous error
 892 @deftypevr Macro int EGRATUITOUS
 893 @comment errno 105 @c DO NOT REMOVE
 894 This error code has no purpose.
 895 @end deftypevr
 896
 897 @emph{The following error codes are defined by the Linux/i386 kernel.
 898 They are not yet documented.}
 899
 900 @comment errno.h
 901 @comment Linux???: Interrupted system call should be restarted
 902 @deftypevr Macro int ERESTART
 903 @comment errno ???/85
 904 @end deftypevr
 905
 906 @comment errno.h
 907 @comment Linux???: No message of desired type
 908 @deftypevr Macro int ENOMSG
 909 @comment errno ???/42
 910 @end deftypevr
 911
 912 @comment errno.h
 913 @comment Linux???: Identifier removed
 914 @deftypevr Macro int EIDRM
 915 @comment errno ???/43
 916 @end deftypevr
 917
 918 @comment errno.h
 919 @comment Linux???: Channel number out of range
 920 @deftypevr Macro int ECHRNG
 921 @comment errno ???/44
 922 @end deftypevr
 923
 924 @comment errno.h
 925 @comment Linux???: Level 2 not synchronized
 926 @deftypevr Macro int EL2NSYNC
 927 @comment errno ???/45
 928 @end deftypevr
 929
 930 @comment errno.h
 931 @comment Linux???: Level 3 halted
 932 @deftypevr Macro int EL3HLT
 933 @comment errno ???/46
 934 @end deftypevr
 935
 936 @comment errno.h
 937 @comment Linux???: Level 3 reset
 938 @deftypevr Macro int EL3RST
 939 @comment errno ???/47
 940 @end deftypevr
 941
 942 @comment errno.h
 943 @comment Linux???: Link number out of range
 944 @deftypevr Macro int ELNRNG
 945 @comment errno ???/48
 946 @end deftypevr
 947
 948 @comment errno.h
 949 @comment Linux???: Protocol driver not attached
 950 @deftypevr Macro int EUNATCH
 951 @comment errno ???/49
 952 @end deftypevr
 953
 954 @comment errno.h
 955 @comment Linux???: No CSI structure available
 956 @deftypevr Macro int ENOCSI
 957 @comment errno ???/50
 958 @end deftypevr
 959
 960 @comment errno.h
 961 @comment Linux???: Level 2 halted
 962 @deftypevr Macro int EL2HLT
 963 @comment errno ???/51
 964 @end deftypevr
 965
 966 @comment errno.h
 967 @comment Linux???: Invalid exchange
 968 @deftypevr Macro int EBADE
 969 @comment errno ???/52
 970 @end deftypevr
 971
 972 @comment errno.h
 973 @comment Linux???: Invalid request descriptor
 974 @deftypevr Macro int EBADR
 975 @comment errno ???/53
 976 @end deftypevr
 977
 978 @comment errno.h
 979 @comment Linux???: Exchange full
 980 @deftypevr Macro int EXFULL
 981 @comment errno ???/54
 982 @end deftypevr
 983
 984 @comment errno.h
 985 @comment Linux???: No anode
 986 @deftypevr Macro int ENOANO
 987 @comment errno ???/55
 988 @end deftypevr
 989
 990 @comment errno.h
 991 @comment Linux???: Invalid request code
 992 @deftypevr Macro int EBADRQC
 993 @comment errno ???/56
 994 @end deftypevr
 995
 996 @comment errno.h
 997 @comment Linux???: Invalid slot
 998 @deftypevr Macro int EBADSLT
 999 @comment errno ???/57
1000 @end deftypevr
1001
1002 @comment errno.h
1003 @comment Linux???: File locking deadlock error
1004 @deftypevr Macro int EDEADLOCK
1005 @comment errno ???/58
1006 @end deftypevr
1007
1008 @comment errno.h
1009 @comment Linux???: Bad font file format
1010 @deftypevr Macro int EBFONT
1011 @comment errno ???/59
1012 @end deftypevr
1013
1014 @comment errno.h
1015 @comment Linux???: Device not a stream
1016 @deftypevr Macro int ENOSTR
1017 @comment errno ???/60
1018 @end deftypevr
1019
1020 @comment errno.h
1021 @comment Linux???: No data available
1022 @deftypevr Macro int ENODATA
1023 @comment errno ???/61
1024 @end deftypevr
1025
1026 @comment errno.h
1027 @comment Linux???: Timer expired
1028 @deftypevr Macro int ETIME
1029 @comment errno ???/62
1030 @end deftypevr
1031
1032 @comment errno.h
1033 @comment Linux???: Out of streams resources
1034 @deftypevr Macro int ENOSR
1035 @comment errno ???/63
1036 @end deftypevr
1037
1038 @comment errno.h
1039 @comment Linux???: Machine is not on the network
1040 @deftypevr Macro int ENONET
1041 @comment errno ???/64
1042 @end deftypevr
1043
1044 @comment errno.h
1045 @comment Linux???: Package not installed
1046 @deftypevr Macro int ENOPKG
1047 @comment errno ???/65
1048 @end deftypevr
1049
1050 @comment errno.h
1051 @comment Linux???: Link has been severed
1052 @deftypevr Macro int ENOLINK
1053 @comment errno ???/67
1054 @end deftypevr
1055
1056 @comment errno.h
1057 @comment Linux???: Advertise error
1058 @deftypevr Macro int EADV
1059 @comment errno ???/68
1060 @end deftypevr
1061
1062 @comment errno.h
1063 @comment Linux???: Srmount error
1064 @deftypevr Macro int ESRMNT
1065 @comment errno ???/69
1066 @end deftypevr
1067
1068 @comment errno.h
1069 @comment Linux???: Communication error on send
1070 @deftypevr Macro int ECOMM
1071 @comment errno ???/70
1072 @end deftypevr
1073
1074 @comment errno.h
1075 @comment Linux???: Protocol error
1076 @deftypevr Macro int EPROTO
1077 @comment errno ???/71
1078 @end deftypevr
1079
1080 @comment errno.h
1081 @comment Linux???: Multihop attempted
1082 @deftypevr Macro int EMULTIHOP
1083 @comment errno ???/72
1084 @end deftypevr
1085
1086 @comment errno.h
1087 @comment Linux???: RFS specific error
1088 @deftypevr Macro int EDOTDOT
1089 @comment errno ???/73
1090 @end deftypevr
1091
1092 @comment errno.h
1093 @comment Linux???: Not a data message
1094 @deftypevr Macro int EBADMSG
1095 @comment errno ???/74
1096 @end deftypevr
1097
1098 @comment errno.h
1099 @comment Linux???: Value too large for defined data type
1100 @deftypevr Macro int EOVERFLOW
1101 @comment errno ???/75
1102 @end deftypevr
1103
1104 @comment errno.h
1105 @comment Linux???: Name not unique on network
1106 @deftypevr Macro int ENOTUNIQ
1107 @comment errno ???/76
1108 @end deftypevr
1109
1110 @comment errno.h
1111 @comment Linux???: File descriptor in bad state
1112 @deftypevr Macro int EBADFD
1113 @comment errno ???/77
1114 @end deftypevr
1115
1116 @comment errno.h
1117 @comment Linux???: Remote address changed
1118 @deftypevr Macro int EREMCHG
1119 @comment errno ???/78
1120 @end deftypevr
1121
1122 @comment errno.h
1123 @comment Linux???: Can not access a needed shared library
1124 @deftypevr Macro int ELIBACC
1125 @comment errno ???/79
1126 @end deftypevr
1127
1128 @comment errno.h
1129 @comment Linux???: Accessing a corrupted shared library
1130 @deftypevr Macro int ELIBBAD
1131 @comment errno ???/80
1132 @end deftypevr
1133
1134 @comment errno.h
1135 @comment Linux???: .lib section in a.out corrupted
1136 @deftypevr Macro int ELIBSCN
1137 @comment errno ???/81
1138 @end deftypevr
1139
1140 @comment errno.h
1141 @comment Linux???: Attempting to link in too many shared libraries
1142 @deftypevr Macro int ELIBMAX
1143 @comment errno ???/82
1144 @end deftypevr
1145
1146 @comment errno.h
1147 @comment Linux???: Cannot exec a shared library directly
1148 @deftypevr Macro int ELIBEXEC
1149 @comment errno ???/83
1150 @end deftypevr
1151
1152 @comment errno.h
1153 @comment Linux???: Streams pipe error
1154 @deftypevr Macro int ESTRPIPE
1155 @comment errno ???/86
1156 @end deftypevr
1157
1158 @comment errno.h
1159 @comment Linux???: Structure needs cleaning
1160 @deftypevr Macro int EUCLEAN
1161 @comment errno ???/117
1162 @end deftypevr
1163
1164 @comment errno.h
1165 @comment Linux???: Not a XENIX named type file
1166 @deftypevr Macro int ENOTNAM
1167 @comment errno ???/118
1168 @end deftypevr
1169
1170 @comment errno.h
1171 @comment Linux???: No XENIX semaphores available
1172 @deftypevr Macro int ENAVAIL
1173 @comment errno ???/119
1174 @end deftypevr
1175
1176 @comment errno.h
1177 @comment Linux???: Is a named type file
1178 @deftypevr Macro int EISNAM
1179 @comment errno ???/120
1180 @end deftypevr
1181
1182 @comment errno.h
1183 @comment Linux???: Remote I/O error
1184 @deftypevr Macro int EREMOTEIO
1185 @comment errno ???/121
1186 @end deftypevr
1187
1188 @node Error Messages,  , Error Codes, Error Reporting
1189 @section Error Messages
1190
1191 The library has functions and variables designed to make it easy for
1192 your program to report informative error messages in the customary
1193 format about the failure of a library call.  The functions
1194 @code{strerror} and @code{perror} give you the standard error message
1195 for a given error code; the variable
1196 @w{@code{program_invocation_short_name}} gives you convenient access to the
1197 name of the program that encountered the error.
1198
1199 @comment string.h
1200 @comment ANSI
1201 @deftypefun {char *} strerror (int @var{errnum})
1202 The @code{strerror} function maps the error code (@pxref{Checking for
1203 Errors}) specified by the @var{errnum} argument to a descriptive error
1204 message string.  The return value is a pointer to this string.
1205
1206 The value @var{errnum} normally comes from the variable @code{errno}.
1207
1208 You should not modify the string returned by @code{strerror}.  Also, if
1209 you make subsequent calls to @code{strerror}, the string might be
1210 overwritten.  (But it's guaranteed that no library function ever calls
1211 @code{strerror} behind your back.)
1212
1213 The function @code{strerror} is declared in @file{string.h}.
1214 @end deftypefun
1215
1216 @comment stdio.h
1217 @comment ANSI
1218 @deftypefun void perror (const char *@var{message})
1219 This function prints an error message to the stream @code{stderr};
1220 see @ref{Standard Streams}.
1221
1222 If you call @code{perror} with a @var{message} that is either a null
1223 pointer or an empty string, @code{perror} just prints the error message
1224 corresponding to @code{errno}, adding a trailing newline.
1225
1226 If you supply a non-null @var{message} argument, then @code{perror}
1227 prefixes its output with this string.  It adds a colon and a space
1228 character to separate the @var{message} from the error string corresponding
1229 to @code{errno}.
1230
1231 The function @code{perror} is declared in @file{stdio.h}.
1232 @end deftypefun
1233
1234 @code{strerror} and @code{perror} produce the exact same message for any
1235 given error code; the precise text varies from system to system.  On the
1236 GNU system, the messages are fairly short; there are no multi-line
1237 messages or embedded newlines.  Each error message begins with a capital
1238 letter and does not include any terminating punctuation.
1239
1240 @strong{Compatibility Note:}  The @code{strerror} function is a new
1241 feature of ANSI C.  Many older C systems do not support this function
1242 yet.
1243
1244 @cindex program name
1245 @cindex name of running program
1246 Many programs that don't read input from the terminal are designed to
1247 exit if any system call fails.  By convention, the error message from
1248 such a program should start with the program's name, sans directories.
1249 You can find that name in the variable
1250 @code{program_invocation_short_name}; the full file name is stored the
1251 variable @code{program_invocation_name}:
1252
1253 @comment errno.h
1254 @comment GNU
1255 @deftypevar {char *} program_invocation_name
1256 This variable's value is the name that was used to invoke the program
1257 running in the current process.  It is the same as @code{argv[0]}.  Note
1258 that this is not necessarily a useful file name; often it contains no
1259 directory names.  @xref{Program Arguments}.
1260 @end deftypevar
1261
1262 @comment errno.h
1263 @comment GNU
1264 @deftypevar {char *} program_invocation_short_name
1265 This variable's value is the name that was used to invoke the program
1266 running in the current process, with directory names removed.  (That is
1267 to say, it is the same as @code{program_invocation_name} minus
1268 everything up to the last slash, if any.)
1269 @end deftypevar
1270
1271 The library initialization code sets up both of these variables before
1272 calling @code{main}.
1273
1274 @strong{Portability Note:} These two variables are GNU extensions.  If
1275 you want your program to work with non-GNU libraries, you must save the
1276 value of @code{argv[0]} in @code{main}, and then strip off the directory
1277 names yourself.  We added these extensions to make it possible to write
1278 self-contained error-reporting subroutines that require no explicit
1279 cooperation from @code{main}.
1280
1281 Here is an example showing how to handle failure to open a file
1282 correctly.  The function @code{open_sesame} tries to open the named file
1283 for reading and returns a stream if successful.  The @code{fopen}
1284 library function returns a null pointer if it couldn't open the file for
1285 some reason.  In that situation, @code{open_sesame} constructs an
1286 appropriate error message using the @code{strerror} function, and
1287 terminates the program.  If we were going to make some other library
1288 calls before passing the error code to @code{strerror}, we'd have to
1289 save it in a local variable instead, because those other library
1290 functions might overwrite @code{errno} in the meantime.
1291
1292 @smallexample
1293 #include <errno.h>
1294 #include <stdio.h>
1295 #include <stdlib.h>
1296 #include <string.h>
1297
1298 FILE *
1299 open_sesame (char *name)
1300 @{
1301   FILE *stream;
1302
1303   errno = 0;
1304   stream = fopen (name, "r");
1305   if (stream == NULL)
1306     @{
1307       fprintf (stderr, "%s: Couldn't open file %s; %s\n",
1308                program_invocation_short_name, name, strerror (errno));
1309       exit (EXIT_FAILURE);
1310     @}
1311   else
1312     return stream;
1313 @}
1314 @end smallexample