1316 lines
41 KiB
Plaintext
1316 lines
41 KiB
Plaintext
@node Error Reporting, Memory Allocation, Introduction, Top
|
|
@chapter Error Reporting
|
|
@cindex error reporting
|
|
@cindex reporting errors
|
|
@cindex error codes
|
|
@cindex status codes
|
|
|
|
Many functions in the GNU C library detect and report error conditions,
|
|
and sometimes your programs need to check for these error conditions.
|
|
For example, when you open an input file, you should verify that the
|
|
file was actually opened correctly, and print an error message or take
|
|
other appropriate action if the call to the library function failed.
|
|
|
|
This chapter describes how the error reporting facility works. Your
|
|
program should include the header file @file{errno.h} to use this
|
|
facility.
|
|
@pindex errno.h
|
|
|
|
@menu
|
|
* Checking for Errors:: How errors are reported by library functions.
|
|
* Error Codes:: Error code macros; all of these expand
|
|
into integer constant values.
|
|
* Error Messages:: Mapping error codes onto error messages.
|
|
@end menu
|
|
|
|
@node Checking for Errors, Error Codes, , Error Reporting
|
|
@section Checking for Errors
|
|
|
|
Most library functions return a special value to indicate that they have
|
|
failed. The special value is typically @code{-1}, a null pointer, or a
|
|
constant such as @code{EOF} that is defined for that purpose. But this
|
|
return value tells you only that an error has occurred. To find out
|
|
what kind of error it was, you need to look at the error code stored in the
|
|
variable @code{errno}. This variable is declared in the header file
|
|
@file{errno.h}.
|
|
@pindex errno.h
|
|
|
|
@comment errno.h
|
|
@comment ANSI
|
|
@deftypevr {Variable} {volatile int} errno
|
|
The variable @code{errno} contains the system error number. You can
|
|
change the value of @code{errno}.
|
|
|
|
Since @code{errno} is declared @code{volatile}, it might be changed
|
|
asynchronously by a signal handler; see @ref{Defining Handlers}.
|
|
However, a properly written signal handler saves and restores the value
|
|
of @code{errno}, so you generally do not need to worry about this
|
|
possibility except when writing signal handlers.
|
|
|
|
The initial value of @code{errno} at program startup is zero. Many
|
|
library functions are guaranteed to set it to certain nonzero values
|
|
when they encounter certain kinds of errors. These error conditions are
|
|
listed for each function. These functions do not change @code{errno}
|
|
when they succeed; thus, the value of @code{errno} after a successful
|
|
call is not necessarily zero, and you should not use @code{errno} to
|
|
determine @emph{whether} a call failed. The proper way to do that is
|
|
documented for each function. @emph{If} the call the failed, you can
|
|
examine @code{errno}.
|
|
|
|
Many library functions can set @code{errno} to a nonzero value as a
|
|
result of calling other library functions which might fail. You should
|
|
assume that any library function might alter @code{errno} when the
|
|
function returns an error.
|
|
|
|
@strong{Portability Note:} ANSI C specifies @code{errno} as a
|
|
``modifiable lvalue'' rather than as a variable, permitting it to be
|
|
implemented as a macro. For example, its expansion might involve a
|
|
function call, like @w{@code{*_errno ()}}. In fact, that is what it is
|
|
on the GNU system itself. The GNU library, on non-GNU systems, does
|
|
whatever is right for the particular system.
|
|
|
|
There are a few library functions, like @code{sqrt} and @code{atan},
|
|
that return a perfectly legitimate value in case of an error, but also
|
|
set @code{errno}. For these functions, if you want to check to see
|
|
whether an error occurred, the recommended method is to set @code{errno}
|
|
to zero before calling the function, and then check its value afterward.
|
|
@end deftypevr
|
|
|
|
@pindex errno.h
|
|
All the error codes have symbolic names; they are macros defined in
|
|
@file{errno.h}. The names start with @samp{E} and an upper-case
|
|
letter or digit; you should consider names of this form to be
|
|
reserved names. @xref{Reserved Names}.
|
|
|
|
The error code values are all positive integers and are all distinct,
|
|
with one exception: @code{EWOULDBLOCK} and @code{EAGAIN} are the same.
|
|
Since the values are distinct, you can use them as labels in a
|
|
@code{switch} statement; just don't use both @code{EWOULDBLOCK} and
|
|
@code{EAGAIN}. Your program should not make any other assumptions about
|
|
the specific values of these symbolic constants.
|
|
|
|
The value of @code{errno} doesn't necessarily have to correspond to any
|
|
of these macros, since some library functions might return other error
|
|
codes of their own for other situations. The only values that are
|
|
guaranteed to be meaningful for a particular library function are the
|
|
ones that this manual lists for that function.
|
|
|
|
On non-GNU systems, almost any system call can return @code{EFAULT} if
|
|
it is given an invalid pointer as an argument. Since this could only
|
|
happen as a result of a bug in your program, and since it will not
|
|
happen on the GNU system, we have saved space by not mentioning
|
|
@code{EFAULT} in the descriptions of individual functions.
|
|
|
|
In some Unix systems, many system calls can also return @code{EFAULT} if
|
|
given as an argument a pointer into the stack, and the kernel for some
|
|
obscure reason fails in its attempt to extend the stack. If this ever
|
|
happens, you should probably try using statically or dynamically
|
|
allocated memory instead of stack memory on that system.
|
|
|
|
@node Error Codes, Error Messages, Checking for Errors, Error Reporting
|
|
@section Error Codes
|
|
|
|
@pindex errno.h
|
|
The error code macros are defined in the header file @file{errno.h}.
|
|
All of them expand into integer constant values. Some of these error
|
|
codes can't occur on the GNU system, but they can occur using the GNU
|
|
library on other systems.
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Operation not permitted
|
|
@deftypevr Macro int EPERM
|
|
@comment errno 1 @c DO NOT REMOVE
|
|
Operation not permitted; only the owner of the file (or other resource)
|
|
or processes with special privileges can perform the operation.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: No such file or directory
|
|
@deftypevr Macro int ENOENT
|
|
@comment errno 2 @c DO NOT REMOVE
|
|
No such file or directory. This is a ``file doesn't exist'' error
|
|
for ordinary files that are referenced in contexts where they are
|
|
expected to already exist.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: No such process
|
|
@deftypevr Macro int ESRCH
|
|
@comment errno 3 @c DO NOT REMOVE
|
|
No process matches the specified process ID.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Interrupted system call
|
|
@deftypevr Macro int EINTR
|
|
@comment errno 4 @c DO NOT REMOVE
|
|
Interrupted function call; an asynchronous signal occured and prevented
|
|
completion of the call. When this happens, you should try the call
|
|
again.
|
|
|
|
You can choose to have functions resume after a signal that is handled,
|
|
rather than failing with @code{EINTR}; see @ref{Interrupted
|
|
Primitives}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Input/output error
|
|
@deftypevr Macro int EIO
|
|
@comment errno 5 @c DO NOT REMOVE
|
|
Input/output error; usually used for physical read or write errors.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Device not configured
|
|
@deftypevr Macro int ENXIO
|
|
@comment errno 6 @c DO NOT REMOVE
|
|
No such device or address. The system tried to use the device
|
|
represented by a file you specified, and it couldn't find the device.
|
|
This can mean that the device file was installed incorrectly, or that
|
|
the physical device is missing or not correctly attached to the
|
|
computer.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Argument list too long
|
|
@deftypevr Macro int E2BIG
|
|
@comment errno 7 @c DO NOT REMOVE
|
|
Argument list too long; used when the arguments passed to a new program
|
|
being executed with one of the @code{exec} functions (@pxref{Executing a
|
|
File}) occupy too much memory space. This condition never arises in the
|
|
GNU system.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Exec format error
|
|
@deftypevr Macro int ENOEXEC
|
|
@comment errno 8 @c DO NOT REMOVE
|
|
Invalid executable file format. This condition is detected by the
|
|
@code{exec} functions; see @ref{Executing a File}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Bad file descriptor
|
|
@deftypevr Macro int EBADF
|
|
@comment errno 9 @c DO NOT REMOVE
|
|
Bad file descriptor; for example, I/O on a descriptor that has been
|
|
closed or reading from a descriptor open only for writing (or vice
|
|
versa).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: No child processes
|
|
@deftypevr Macro int ECHILD
|
|
@comment errno 10 @c DO NOT REMOVE
|
|
There are no child processes. This error happens on operations that are
|
|
supposed to manipulate child processes, when there aren't any processes
|
|
to manipulate.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Resource deadlock avoided
|
|
@deftypevr Macro int EDEADLK
|
|
@comment errno 11 @c DO NOT REMOVE
|
|
Deadlock avoided; allocating a system resource would have resulted in a
|
|
deadlock situation. The system does not guarantee that it will notice
|
|
all such situations. This error means you got lucky and the system
|
|
noticed; it might just hang. @xref{File Locks}, for an example.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Cannot allocate memory
|
|
@deftypevr Macro int ENOMEM
|
|
@comment errno 12 @c DO NOT REMOVE
|
|
No memory available. The system cannot allocate more virtual memory
|
|
because its capacity is full.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Permission denied
|
|
@deftypevr Macro int EACCES
|
|
@comment errno 13 @c DO NOT REMOVE
|
|
Permission denied; the file permissions do not allow the attempted operation.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Bad address
|
|
@deftypevr Macro int EFAULT
|
|
@comment errno 14 @c DO NOT REMOVE
|
|
Bad address; an invalid pointer was detected.
|
|
In the GNU system, this error never happens; you get a signal instead.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Block device required
|
|
@deftypevr Macro int ENOTBLK
|
|
@comment errno 15 @c DO NOT REMOVE
|
|
A file that isn't a block special file was given in a situation that
|
|
requires one. For example, trying to mount an ordinary file as a file
|
|
system in Unix gives this error.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Device or resource busy
|
|
@deftypevr Macro int EBUSY
|
|
@comment errno 16 @c DO NOT REMOVE
|
|
Resource busy; a system resource that can't be shared is already in use.
|
|
For example, if you try to delete a file that is the root of a currently
|
|
mounted filesystem, you get this error.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: File exists
|
|
@deftypevr Macro int EEXIST
|
|
@comment errno 17 @c DO NOT REMOVE
|
|
File exists; an existing file was specified in a context where it only
|
|
makes sense to specify a new file.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Invalid cross-device link
|
|
@deftypevr Macro int EXDEV
|
|
@comment errno 18 @c DO NOT REMOVE
|
|
An attempt to make an improper link across file systems was detected.
|
|
This happens not only when you use @code{link} (@pxref{Hard Links}) but
|
|
also when you rename a file with @code{rename} (@pxref{Renaming Files}).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Operation not supported by device
|
|
@deftypevr Macro int ENODEV
|
|
@comment errno 19 @c DO NOT REMOVE
|
|
The wrong type of device was given to a function that expects a
|
|
particular sort of device.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Not a directory
|
|
@deftypevr Macro int ENOTDIR
|
|
@comment errno 20 @c DO NOT REMOVE
|
|
A file that isn't a directory was specified when a directory is required.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Is a directory
|
|
@deftypevr Macro int EISDIR
|
|
@comment errno 21 @c DO NOT REMOVE
|
|
File is a directory; you cannot open a directory for writing,
|
|
or create or remove hard links to it.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Invalid argument
|
|
@deftypevr Macro int EINVAL
|
|
@comment errno 22 @c DO NOT REMOVE
|
|
Invalid argument. This is used to indicate various kinds of problems
|
|
with passing the wrong argument to a library function.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Too many open files
|
|
@deftypevr Macro int EMFILE
|
|
@comment errno 24 @c DO NOT REMOVE
|
|
The current process has too many files open and can't open any more.
|
|
Duplicate descriptors do count toward this limit.
|
|
|
|
In BSD and GNU, the number of open files is controlled by a resource
|
|
limit that can usually be increased. If you get this error, you might
|
|
want to increase the @code{RLIMIT_NOFILE} limit or make it unlimited;
|
|
@pxref{Limits on Resources}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Too many open files in system
|
|
@deftypevr Macro int ENFILE
|
|
@comment errno 23 @c DO NOT REMOVE
|
|
There are too many distinct file openings in the entire system. Note
|
|
that any number of linked channels count as just one file opening; see
|
|
@ref{Linked Channels}. This error never occurs in the GNU system.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Inappropriate ioctl for device
|
|
@deftypevr Macro int ENOTTY
|
|
@comment errno 25 @c DO NOT REMOVE
|
|
Inappropriate I/O control operation, such as trying to set terminal
|
|
modes on an ordinary file.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Text file busy
|
|
@deftypevr Macro int ETXTBSY
|
|
@comment errno 26 @c DO NOT REMOVE
|
|
An attempt to execute a file that is currently open for writing, or
|
|
write to a file that is currently being executed. Often using a
|
|
debugger to run a program is considered having it open for writing and
|
|
will cause this error. (The name stands for ``text file busy''.) This
|
|
is not an error in the GNU system; the text is copied as necessary.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: File too large
|
|
@deftypevr Macro int EFBIG
|
|
@comment errno 27 @c DO NOT REMOVE
|
|
File too big; the size of a file would be larger than allowed by the system.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: No space left on device
|
|
@deftypevr Macro int ENOSPC
|
|
@comment errno 28 @c DO NOT REMOVE
|
|
No space left on device; write operation on a file failed because the
|
|
disk is full.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Illegal seek
|
|
@deftypevr Macro int ESPIPE
|
|
@comment errno 29 @c DO NOT REMOVE
|
|
Invalid seek operation (such as on a pipe).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Read-only file system
|
|
@deftypevr Macro int EROFS
|
|
@comment errno 30 @c DO NOT REMOVE
|
|
An attempt was made to modify something on a read-only file system.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Too many links
|
|
@deftypevr Macro int EMLINK
|
|
@comment errno 31 @c DO NOT REMOVE
|
|
Too many links; the link count of a single file would become too large.
|
|
@code{rename} can cause this error if the file being renamed already has
|
|
as many links as it can take (@pxref{Renaming Files}).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Broken pipe
|
|
@deftypevr Macro int EPIPE
|
|
@comment errno 32 @c DO NOT REMOVE
|
|
Broken pipe; there is no process reading from the other end of a pipe.
|
|
Every library function that returns this error code also generates a
|
|
@code{SIGPIPE} signal; this signal terminates the program if not handled
|
|
or blocked. Thus, your program will never actually see @code{EPIPE}
|
|
unless it has handled or blocked @code{SIGPIPE}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment ANSI: Numerical argument out of domain
|
|
@deftypevr Macro int EDOM
|
|
@comment errno 33 @c DO NOT REMOVE
|
|
Domain error; used by mathematical functions when an argument value does
|
|
not fall into the domain over which the function is defined.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment ANSI: Numerical result out of range
|
|
@deftypevr Macro int ERANGE
|
|
@comment errno 34 @c DO NOT REMOVE
|
|
Range error; used by mathematical functions when the result value is
|
|
not representable because of overflow or underflow.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Resource temporarily unavailable
|
|
@deftypevr Macro int EAGAIN
|
|
@comment errno 35 @c DO NOT REMOVE
|
|
Resource temporarily unavailable; the call might work if you try again
|
|
later. The macro @code{EWOULDBLOCK} is another name for @code{EAGAIN};
|
|
they are always the same in the GNU C library.
|
|
|
|
This error can happen in a few different situations:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
An operation that would block was attempted on an object that has
|
|
non-blocking mode selected. Trying the same operation again will block
|
|
until some external condition makes it possible to read, write, or
|
|
connect (whatever the operation). You can use @code{select} to find out
|
|
when the operation will be possible; @pxref{Waiting for I/O}.
|
|
|
|
@strong{Portability Note:} In older Unix many systems, this condition
|
|
was indicated by @code{EWOULDBLOCK}, which was a distinct error code
|
|
different from @code{EAGAIN}. To make your program portable, you should
|
|
check for both codes and treat them the same.
|
|
|
|
@item
|
|
A temporary resource shortage made an operation impossible. @code{fork}
|
|
can return this error. It indicates that the shortage is expected to
|
|
pass, so your program can try the call again later and it may succeed.
|
|
It is probably a good idea to delay for a few seconds before trying it
|
|
again, to allow time for other processes to release scarce resources.
|
|
Such shortages are usually fairly serious and affect the whole system,
|
|
so usually an interactive program should report the error to the user
|
|
and return to its command loop.
|
|
@end itemize
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Operation would block
|
|
@deftypevr Macro int EWOULDBLOCK
|
|
@comment errno EAGAIN @c DO NOT REMOVE
|
|
In the GNU C library, this is another name for @code{EAGAIN} (above).
|
|
The values are always the same, on every operating system.
|
|
|
|
C libraries in many older Unix systems have @code{EWOULDBLOCK} as a
|
|
separate error code.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Operation now in progress
|
|
@deftypevr Macro int EINPROGRESS
|
|
@comment errno 36 @c DO NOT REMOVE
|
|
An operation that cannot complete immediately was initiated on an object
|
|
that has non-blocking mode selected. Some functions that must always
|
|
block (such as @code{connect}; @pxref{Connecting}) never return
|
|
@code{EAGAIN}. Instead, they return @code{EINPROGRESS} to indicate that
|
|
the operation has begun and will take some time. Attempts to manipulate
|
|
the object before the call completes return @code{EALREADY}. You can
|
|
use the @code{select} function to find out when the pending operation
|
|
has completed; @pxref{Waiting for I/O}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Operation already in progress
|
|
@deftypevr Macro int EALREADY
|
|
@comment errno 37 @c DO NOT REMOVE
|
|
An operation is already in progress on an object that has non-blocking
|
|
mode selected.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Socket operation on non-socket
|
|
@deftypevr Macro int ENOTSOCK
|
|
@comment errno 38 @c DO NOT REMOVE
|
|
A file that isn't a socket was specified when a socket is required.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Message too long
|
|
@deftypevr Macro int EMSGSIZE
|
|
@comment errno 40 @c DO NOT REMOVE
|
|
The size of a message sent on a socket was larger than the supported
|
|
maximum size.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Protocol wrong type for socket
|
|
@deftypevr Macro int EPROTOTYPE
|
|
@comment errno 41 @c DO NOT REMOVE
|
|
The socket type does not support the requested communications protocol.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Protocol not available
|
|
@deftypevr Macro int ENOPROTOOPT
|
|
@comment errno 42 @c DO NOT REMOVE
|
|
You specified a socket option that doesn't make sense for the
|
|
particular protocol being used by the socket. @xref{Socket Options}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Protocol not supported
|
|
@deftypevr Macro int EPROTONOSUPPORT
|
|
@comment errno 43 @c DO NOT REMOVE
|
|
The socket domain does not support the requested communications protocol
|
|
(perhaps because the requested protocol is completely invalid.)
|
|
@xref{Creating a Socket}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Socket type not supported
|
|
@deftypevr Macro int ESOCKTNOSUPPORT
|
|
@comment errno 44 @c DO NOT REMOVE
|
|
The socket type is not supported.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Operation not supported
|
|
@deftypevr Macro int EOPNOTSUPP
|
|
@comment errno 45 @c DO NOT REMOVE
|
|
The operation you requested is not supported. Some socket functions
|
|
don't make sense for all types of sockets, and others may not be
|
|
implemented for all communications protocols. In the GNU system, this
|
|
error can happen for many calls when the object does not support the
|
|
particular operation; it is a generic indication that the server knows
|
|
nothing to do for that call.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Protocol family not supported
|
|
@deftypevr Macro int EPFNOSUPPORT
|
|
@comment errno 46 @c DO NOT REMOVE
|
|
The socket communications protocol family you requested is not supported.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Address family not supported by protocol
|
|
@deftypevr Macro int EAFNOSUPPORT
|
|
@comment errno 47 @c DO NOT REMOVE
|
|
The address family specified for a socket is not supported; it is
|
|
inconsistent with the protocol being used on the socket. @xref{Sockets}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Address already in use
|
|
@deftypevr Macro int EADDRINUSE
|
|
@comment errno 48 @c DO NOT REMOVE
|
|
The requested socket address is already in use. @xref{Socket Addresses}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Cannot assign requested address
|
|
@deftypevr Macro int EADDRNOTAVAIL
|
|
@comment errno 49 @c DO NOT REMOVE
|
|
The requested socket address is not available; for example, you tried
|
|
to give a socket a name that doesn't match the local host name.
|
|
@xref{Socket Addresses}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Network is down
|
|
@deftypevr Macro int ENETDOWN
|
|
@comment errno 50 @c DO NOT REMOVE
|
|
A socket operation failed because the network was down.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Network is unreachable
|
|
@deftypevr Macro int ENETUNREACH
|
|
@comment errno 51 @c DO NOT REMOVE
|
|
A socket operation failed because the subnet containing the remote host
|
|
was unreachable.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Network dropped connection on reset
|
|
@deftypevr Macro int ENETRESET
|
|
@comment errno 52 @c DO NOT REMOVE
|
|
A network connection was reset because the remote host crashed.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Software caused connection abort
|
|
@deftypevr Macro int ECONNABORTED
|
|
@comment errno 53 @c DO NOT REMOVE
|
|
A network connection was aborted locally.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Connection reset by peer
|
|
@deftypevr Macro int ECONNRESET
|
|
@comment errno 54 @c DO NOT REMOVE
|
|
A network connection was closed for reasons outside the control of the
|
|
local host, such as by the remote machine rebooting or an unrecoverable
|
|
protocol violation.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: No buffer space available
|
|
@deftypevr Macro int ENOBUFS
|
|
@comment errno 55 @c DO NOT REMOVE
|
|
The kernel's buffers for I/O operations are all in use. In GNU, this
|
|
error is always synonymous with @code{ENOMEM}; you may get one or the
|
|
other from network operations.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Transport endpoint is already connected
|
|
@deftypevr Macro int EISCONN
|
|
@comment errno 56 @c DO NOT REMOVE
|
|
You tried to connect a socket that is already connected.
|
|
@xref{Connecting}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Transport endpoint is not connected
|
|
@deftypevr Macro int ENOTCONN
|
|
@comment errno 57 @c DO NOT REMOVE
|
|
The socket is not connected to anything. You get this error when you
|
|
try to transmit data over a socket, without first specifying a
|
|
destination for the data. For a connectionless socket (for datagram
|
|
protocols, such as UDP), you get @code{EDESTADDRREQ} instead.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Destination address required
|
|
@deftypevr Macro int EDESTADDRREQ
|
|
@comment errno 39 @c DO NOT REMOVE
|
|
No default destination address was set for the socket. You get this
|
|
error when you try to transmit data over a connectionless socket,
|
|
without first specifying a destination for the data with @code{connect}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Cannot send after transport endpoint shutdown
|
|
@deftypevr Macro int ESHUTDOWN
|
|
@comment errno 58 @c DO NOT REMOVE
|
|
The socket has already been shut down.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Too many references: cannot splice
|
|
@deftypevr Macro int ETOOMANYREFS
|
|
@comment errno 59 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Connection timed out
|
|
@deftypevr Macro int ETIMEDOUT
|
|
@comment errno 60 @c DO NOT REMOVE
|
|
A socket operation with a specified timeout received no response during
|
|
the timeout period.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Connection refused
|
|
@deftypevr Macro int ECONNREFUSED
|
|
@comment errno 61 @c DO NOT REMOVE
|
|
A remote host refused to allow the network connection (typically because
|
|
it is not running the requested service).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Too many levels of symbolic links
|
|
@deftypevr Macro int ELOOP
|
|
@comment errno 62 @c DO NOT REMOVE
|
|
Too many levels of symbolic links were encountered in looking up a file name.
|
|
This often indicates a cycle of symbolic links.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: File name too long
|
|
@deftypevr Macro int ENAMETOOLONG
|
|
@comment errno 63 @c DO NOT REMOVE
|
|
Filename too long (longer than @code{PATH_MAX}; @pxref{Limits for
|
|
Files}) or host name too long (in @code{gethostname} or
|
|
@code{sethostname}; @pxref{Host Identification}).
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Host is down
|
|
@deftypevr Macro int EHOSTDOWN
|
|
@comment errno 64 @c DO NOT REMOVE
|
|
The remote host for a requested network connection is down.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: No route to host
|
|
@deftypevr Macro int EHOSTUNREACH
|
|
@comment errno 65 @c DO NOT REMOVE
|
|
The remote host for a requested network connection is not reachable.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Directory not empty
|
|
@deftypevr Macro int ENOTEMPTY
|
|
@comment errno 66 @c DO NOT REMOVE
|
|
Directory not empty, where an empty directory was expected. Typically,
|
|
this error occurs when you are trying to delete a directory.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Too many processes
|
|
@deftypevr Macro int EPROCLIM
|
|
@comment errno 67 @c DO NOT REMOVE
|
|
This means that the per-user limit on new process would be exceeded by
|
|
an attempted @code{fork}. @xref{Limits on Resources}, for details on
|
|
the @code{RLIMIT_NPROC} limit.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Too many users
|
|
@deftypevr Macro int EUSERS
|
|
@comment errno 68 @c DO NOT REMOVE
|
|
The file quota system is confused because there are too many users.
|
|
@c This can probably happen in a GNU system when using NFS.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Disc quota exceeded
|
|
@deftypevr Macro int EDQUOT
|
|
@comment errno 69 @c DO NOT REMOVE
|
|
The user's disk quota was exceeded.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Stale NFS file handle
|
|
@deftypevr Macro int ESTALE
|
|
@comment errno 70 @c DO NOT REMOVE
|
|
Stale NFS file handle. This indicates an internal confusion in the NFS
|
|
system which is due to file system rearrangements on the server host.
|
|
Repairing this condition usually requires unmounting and remounting
|
|
the NFS file system on the local host.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Object is remote
|
|
@deftypevr Macro int EREMOTE
|
|
@comment errno 71 @c DO NOT REMOVE
|
|
An attempt was made to NFS-mount a remote file system with a file name that
|
|
already specifies an NFS-mounted file.
|
|
(This is an error on some operating systems, but we expect it to work
|
|
properly on the GNU system, making this error code impossible.)
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: RPC struct is bad
|
|
@deftypevr Macro int EBADRPC
|
|
@comment errno 72 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: RPC version wrong
|
|
@deftypevr Macro int ERPCMISMATCH
|
|
@comment errno 73 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: RPC program not available
|
|
@deftypevr Macro int EPROGUNAVAIL
|
|
@comment errno 74 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: RPC program version wrong
|
|
@deftypevr Macro int EPROGMISMATCH
|
|
@comment errno 75 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: RPC bad procedure for program
|
|
@deftypevr Macro int EPROCUNAVAIL
|
|
@comment errno 76 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: No locks available
|
|
@deftypevr Macro int ENOLCK
|
|
@comment errno 77 @c DO NOT REMOVE
|
|
No locks available. This is used by the file locking facilities; see
|
|
@ref{File Locks}. This error is never generated by the GNU system, but
|
|
it can result from an operation to an NFS server running another
|
|
operating system.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Inappropriate file type or format
|
|
@deftypevr Macro int EFTYPE
|
|
@comment errno 79 @c DO NOT REMOVE
|
|
Inappropriate file type or format. The file was the wrong type for the
|
|
operation, or a data file had the wrong format.
|
|
|
|
On some systems @code{chmod} returns this error if you try to set the
|
|
sticky bit on a non-directory file; @pxref{Setting Permissions}.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Authentication error
|
|
@deftypevr Macro int EAUTH
|
|
@comment errno 80 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment BSD: Need authenticator
|
|
@deftypevr Macro int ENEEDAUTH
|
|
@comment errno 81 @c DO NOT REMOVE
|
|
???
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment POSIX.1: Function not implemented
|
|
@deftypevr Macro int ENOSYS
|
|
@comment errno 78 @c DO NOT REMOVE
|
|
Function not implemented. Some functions have commands or options defined
|
|
that might not be supported in all implementations, and this is the kind
|
|
of error you get if you request them and they are not supported.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment ISO: Invalid or incomplete multibyte or wide character
|
|
@deftypevr Macro int EILSEQ
|
|
@comment errno 106 @c DO NOT REMOVE
|
|
While decoding a multibyte character the function came along an invalid
|
|
or an incomplete sequence of bytes or the given wide character is invalid.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: Inappropriate operation for background process
|
|
@deftypevr Macro int EBACKGROUND
|
|
@comment errno 100 @c DO NOT REMOVE
|
|
In the GNU system, servers supporting the @code{term} protocol return
|
|
this error for certain operations when the caller is not in the
|
|
foreground process group of the terminal. Users do not usually see this
|
|
error because functions such as @code{read} and @code{write} translate
|
|
it into a @code{SIGTTIN} or @code{SIGTTOU} signal. @xref{Job Control},
|
|
for information on process groups and these signals.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: Translator died
|
|
@deftypevr Macro int EDIED
|
|
@comment errno 101 @c DO NOT REMOVE
|
|
In the GNU system, opening a file returns this error when the file is
|
|
translated by a program and the translator program dies while starting
|
|
up, before it has connected to the file.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: ?
|
|
@deftypevr Macro int ED
|
|
@comment errno 102 @c DO NOT REMOVE
|
|
The experienced user will know what is wrong.
|
|
@c This error code is a joke. Its perror text is part of the joke.
|
|
@c Don't change it.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: You really blew it this time
|
|
@deftypevr Macro int EGREGIOUS
|
|
@comment errno 103 @c DO NOT REMOVE
|
|
You did @strong{what}?
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: Computer bought the farm
|
|
@deftypevr Macro int EIEIO
|
|
@comment errno 104 @c DO NOT REMOVE
|
|
Go home and have a glass of warm, dairy-fresh milk.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment GNU: Gratuitous error
|
|
@deftypevr Macro int EGRATUITOUS
|
|
@comment errno 105 @c DO NOT REMOVE
|
|
This error code has no purpose.
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Bad message
|
|
@deftypevr Macro int EBADMSG
|
|
@comment errno 107
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Identifier removed
|
|
@deftypevr Macro int EIDRM
|
|
@comment errno 108
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Multihop attempted
|
|
@deftypevr Macro int EMULTIHOP
|
|
@comment errno 109
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: No data available
|
|
@deftypevr Macro int ENODATA
|
|
@comment errno 110
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Link has been severed
|
|
@deftypevr Macro int ENOLINK
|
|
@comment errno 111
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: No message of desired type
|
|
@deftypevr Macro int ENOMSG
|
|
@comment errno 112
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Out of streams resources
|
|
@deftypevr Macro int ENOSR
|
|
@comment errno 113
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Device not a stream
|
|
@deftypevr Macro int ENOSTR
|
|
@comment errno 114
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Value too large for defined data type
|
|
@deftypevr Macro int EOVERFLOW
|
|
@comment errno 115
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Protocol error
|
|
@deftypevr Macro int EPROTO
|
|
@comment errno 116
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment XOPEN: Timer expired
|
|
@deftypevr Macro int ETIME
|
|
@comment errno 117
|
|
@end deftypevr
|
|
|
|
|
|
@emph{The following error codes are defined by the Linux/i386 kernel.
|
|
They are not yet documented.}
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Interrupted system call should be restarted
|
|
@deftypevr Macro int ERESTART
|
|
@comment errno ???/85
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Channel number out of range
|
|
@deftypevr Macro int ECHRNG
|
|
@comment errno ???/44
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Level 2 not synchronized
|
|
@deftypevr Macro int EL2NSYNC
|
|
@comment errno ???/45
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Level 3 halted
|
|
@deftypevr Macro int EL3HLT
|
|
@comment errno ???/46
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Level 3 reset
|
|
@deftypevr Macro int EL3RST
|
|
@comment errno ???/47
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Link number out of range
|
|
@deftypevr Macro int ELNRNG
|
|
@comment errno ???/48
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Protocol driver not attached
|
|
@deftypevr Macro int EUNATCH
|
|
@comment errno ???/49
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: No CSI structure available
|
|
@deftypevr Macro int ENOCSI
|
|
@comment errno ???/50
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Level 2 halted
|
|
@deftypevr Macro int EL2HLT
|
|
@comment errno ???/51
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Invalid exchange
|
|
@deftypevr Macro int EBADE
|
|
@comment errno ???/52
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Invalid request descriptor
|
|
@deftypevr Macro int EBADR
|
|
@comment errno ???/53
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Exchange full
|
|
@deftypevr Macro int EXFULL
|
|
@comment errno ???/54
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: No anode
|
|
@deftypevr Macro int ENOANO
|
|
@comment errno ???/55
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Invalid request code
|
|
@deftypevr Macro int EBADRQC
|
|
@comment errno ???/56
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Invalid slot
|
|
@deftypevr Macro int EBADSLT
|
|
@comment errno ???/57
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: File locking deadlock error
|
|
@deftypevr Macro int EDEADLOCK
|
|
@comment errno ???/58
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Bad font file format
|
|
@deftypevr Macro int EBFONT
|
|
@comment errno ???/59
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Machine is not on the network
|
|
@deftypevr Macro int ENONET
|
|
@comment errno ???/64
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Package not installed
|
|
@deftypevr Macro int ENOPKG
|
|
@comment errno ???/65
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Advertise error
|
|
@deftypevr Macro int EADV
|
|
@comment errno ???/68
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Srmount error
|
|
@deftypevr Macro int ESRMNT
|
|
@comment errno ???/69
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Communication error on send
|
|
@deftypevr Macro int ECOMM
|
|
@comment errno ???/70
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: RFS specific error
|
|
@deftypevr Macro int EDOTDOT
|
|
@comment errno ???/73
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Name not unique on network
|
|
@deftypevr Macro int ENOTUNIQ
|
|
@comment errno ???/76
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: File descriptor in bad state
|
|
@deftypevr Macro int EBADFD
|
|
@comment errno ???/77
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Remote address changed
|
|
@deftypevr Macro int EREMCHG
|
|
@comment errno ???/78
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Can not access a needed shared library
|
|
@deftypevr Macro int ELIBACC
|
|
@comment errno ???/79
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Accessing a corrupted shared library
|
|
@deftypevr Macro int ELIBBAD
|
|
@comment errno ???/80
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: .lib section in a.out corrupted
|
|
@deftypevr Macro int ELIBSCN
|
|
@comment errno ???/81
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Attempting to link in too many shared libraries
|
|
@deftypevr Macro int ELIBMAX
|
|
@comment errno ???/82
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Cannot exec a shared library directly
|
|
@deftypevr Macro int ELIBEXEC
|
|
@comment errno ???/83
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Streams pipe error
|
|
@deftypevr Macro int ESTRPIPE
|
|
@comment errno ???/86
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Structure needs cleaning
|
|
@deftypevr Macro int EUCLEAN
|
|
@comment errno ???/117
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Not a XENIX named type file
|
|
@deftypevr Macro int ENOTNAM
|
|
@comment errno ???/118
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: No XENIX semaphores available
|
|
@deftypevr Macro int ENAVAIL
|
|
@comment errno ???/119
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Is a named type file
|
|
@deftypevr Macro int EISNAM
|
|
@comment errno ???/120
|
|
@end deftypevr
|
|
|
|
@comment errno.h
|
|
@comment Linux???: Remote I/O error
|
|
@deftypevr Macro int EREMOTEIO
|
|
@comment errno ???/121
|
|
@end deftypevr
|
|
|
|
@node Error Messages, , Error Codes, Error Reporting
|
|
@section Error Messages
|
|
|
|
The library has functions and variables designed to make it easy for
|
|
your program to report informative error messages in the customary
|
|
format about the failure of a library call. The functions
|
|
@code{strerror} and @code{perror} give you the standard error message
|
|
for a given error code; the variable
|
|
@w{@code{program_invocation_short_name}} gives you convenient access to the
|
|
name of the program that encountered the error.
|
|
|
|
@comment string.h
|
|
@comment ANSI
|
|
@deftypefun {char *} strerror (int @var{errnum})
|
|
The @code{strerror} function maps the error code (@pxref{Checking for
|
|
Errors}) specified by the @var{errnum} argument to a descriptive error
|
|
message string. The return value is a pointer to this string.
|
|
|
|
The value @var{errnum} normally comes from the variable @code{errno}.
|
|
|
|
You should not modify the string returned by @code{strerror}. Also, if
|
|
you make subsequent calls to @code{strerror}, the string might be
|
|
overwritten. (But it's guaranteed that no library function ever calls
|
|
@code{strerror} behind your back.)
|
|
|
|
The function @code{strerror} is declared in @file{string.h}.
|
|
@end deftypefun
|
|
|
|
@comment stdio.h
|
|
@comment ANSI
|
|
@deftypefun void perror (const char *@var{message})
|
|
This function prints an error message to the stream @code{stderr};
|
|
see @ref{Standard Streams}.
|
|
|
|
If you call @code{perror} with a @var{message} that is either a null
|
|
pointer or an empty string, @code{perror} just prints the error message
|
|
corresponding to @code{errno}, adding a trailing newline.
|
|
|
|
If you supply a non-null @var{message} argument, then @code{perror}
|
|
prefixes its output with this string. It adds a colon and a space
|
|
character to separate the @var{message} from the error string corresponding
|
|
to @code{errno}.
|
|
|
|
The function @code{perror} is declared in @file{stdio.h}.
|
|
@end deftypefun
|
|
|
|
@code{strerror} and @code{perror} produce the exact same message for any
|
|
given error code; the precise text varies from system to system. On the
|
|
GNU system, the messages are fairly short; there are no multi-line
|
|
messages or embedded newlines. Each error message begins with a capital
|
|
letter and does not include any terminating punctuation.
|
|
|
|
@strong{Compatibility Note:} The @code{strerror} function is a new
|
|
feature of ANSI C. Many older C systems do not support this function
|
|
yet.
|
|
|
|
@cindex program name
|
|
@cindex name of running program
|
|
Many programs that don't read input from the terminal are designed to
|
|
exit if any system call fails. By convention, the error message from
|
|
such a program should start with the program's name, sans directories.
|
|
You can find that name in the variable
|
|
@code{program_invocation_short_name}; the full file name is stored the
|
|
variable @code{program_invocation_name}:
|
|
|
|
@comment errno.h
|
|
@comment GNU
|
|
@deftypevar {char *} program_invocation_name
|
|
This variable's value is the name that was used to invoke the program
|
|
running in the current process. It is the same as @code{argv[0]}. Note
|
|
that this is not necessarily a useful file name; often it contains no
|
|
directory names. @xref{Program Arguments}.
|
|
@end deftypevar
|
|
|
|
@comment errno.h
|
|
@comment GNU
|
|
@deftypevar {char *} program_invocation_short_name
|
|
This variable's value is the name that was used to invoke the program
|
|
running in the current process, with directory names removed. (That is
|
|
to say, it is the same as @code{program_invocation_name} minus
|
|
everything up to the last slash, if any.)
|
|
@end deftypevar
|
|
|
|
The library initialization code sets up both of these variables before
|
|
calling @code{main}.
|
|
|
|
@strong{Portability Note:} These two variables are GNU extensions. If
|
|
you want your program to work with non-GNU libraries, you must save the
|
|
value of @code{argv[0]} in @code{main}, and then strip off the directory
|
|
names yourself. We added these extensions to make it possible to write
|
|
self-contained error-reporting subroutines that require no explicit
|
|
cooperation from @code{main}.
|
|
|
|
Here is an example showing how to handle failure to open a file
|
|
correctly. The function @code{open_sesame} tries to open the named file
|
|
for reading and returns a stream if successful. The @code{fopen}
|
|
library function returns a null pointer if it couldn't open the file for
|
|
some reason. In that situation, @code{open_sesame} constructs an
|
|
appropriate error message using the @code{strerror} function, and
|
|
terminates the program. If we were going to make some other library
|
|
calls before passing the error code to @code{strerror}, we'd have to
|
|
save it in a local variable instead, because those other library
|
|
functions might overwrite @code{errno} in the meantime.
|
|
|
|
@smallexample
|
|
#include <errno.h>
|
|
#include <stdio.h>
|
|
#include <stdlib.h>
|
|
#include <string.h>
|
|
|
|
FILE *
|
|
open_sesame (char *name)
|
|
@{
|
|
FILE *stream;
|
|
|
|
errno = 0;
|
|
stream = fopen (name, "r");
|
|
if (stream == NULL)
|
|
@{
|
|
fprintf (stderr, "%s: Couldn't open file %s; %s\n",
|
|
program_invocation_short_name, name, strerror (errno));
|
|
exit (EXIT_FAILURE);
|
|
@}
|
|
else
|
|
return stream;
|
|
@}
|
|
@end smallexample
|