The GNU C Library - Error Messages

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 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.

Function char * strerror (int errnum)

The strerror function maps the error code (see 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'.

Function void perror (const char *message)

This function prints an error message to the stream stderr ; see 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 ANSI 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 :

Variable 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 argv[0] . Note that this is not necessarily a useful file name; often it contains no directory names. See Program Arguments.

Variable 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 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;
	}