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
strerror
and perror
give you the standard error message
for a given error code; the variable
program_invocation_short_name
gives you convenient access to the
name of the program that encountered the error.
strerror
function maps the error code (see section Checking for Errors) specified by the errnum argument to a descriptive error
message string. The return value is a pointer to this string.
The value errnum normally comes from the variable errno
.
You should not modify the string returned by strerror
. Also, if
you make subsequent calls to strerror
, the string might be
overwritten. (But it's guaranteed that no library function ever calls
strerror
behind your back.)
The function strerror
is declared in `string.h'.
strerror_r
function works like strerror
but instead of
returning the error message in a statically allocated buffer shared by
all threads in the process, it returns a private copy for the
thread. This might be either some permanent global data or a message
string in the user supplied buffer starting at buf with the
length of n bytes.
At most n characters are written (including the NUL byte) so it is up to the user to select the buffer large enough.
This function should always be used in multi-threaded programs since
there is no way to guarantee the string returned by strerror
really belongs to the last call of the current thread.
This function strerror_r
is a GNU extension and it is declared in
`string.h'.
stderr
;
see section Standard Streams.
If you call perror
with a message that is either a null
pointer or an empty string, perror
just prints the error message
corresponding to errno
, adding a trailing newline.
If you supply a non-null message argument, then perror
prefixes its output with this string. It adds a colon and a space
character to separate the message from the error string corresponding
to errno
.
The function perror
is declared in `stdio.h'.
strerror
and 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.
Compatibility Note: The strerror
function is a new
feature of ISO C. Many older C systems do not support this function
yet.
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
program_invocation_short_name
; the full file name is stored the
variable program_invocation_name
.
argv[0]
. Note
that this is not necessarily a useful file name; often it contains no
directory names. See section Program Arguments.
program_invocation_name
minus
everything up to the last slash, if any.)
The library initialization code sets up both of these variables before
calling main
.
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 argv[0]
in 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 main
.
Here is an example showing how to handle failure to open a file
correctly. The function open_sesame
tries to open the named file
for reading and returns a stream if successful. The fopen
library function returns a null pointer if it couldn't open the file for
some reason. In that situation, open_sesame
constructs an
appropriate error message using the strerror
function, and
terminates the program. If we were going to make some other library
calls before passing the error code to strerror
, we'd have to
save it in a local variable instead, because those other library
functions might overwrite errno
in the meantime.
#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; }
Go to the first, previous, next, last section, table of contents.