Error Handlers

In addition to reporting errors the library also provides an optional error handler. The error handler is called by library functions when they report an error, just before they return to the caller. The purpose of the handler is to provide a function where a breakpoint can be set that will catch library errors when running under the debugger. It is not intended for use in production programs, which should handle any errors using the error return codes described above.

The default behavior of the error handler is to print a short message and call abort() whenever an error is reported by the library. If this default is not turned off then any program using the library will stop with a core-dump whenever a library routine reports an error. This is intended as a fail-safe default for programs which do not check the return status of library routines (we don't encourage you to write programs this way). If you turn off the default error handler it is your responsibility to check the return values of the GSL routines. You can customize the error behavior by providing a new error handler. For example, an alternative error handler could log all errors to a file, ignore certain error conditions (such as underflows), or start the debugger and attach it to the current process when an error occurs.

All GSL error handlers have the type gsl_error_handler_t, which is defined in `gsl_errno.h',

Data Type: gsl_error_handler_t

This is the type of GSL error handler functions. An error handler will be passed four arguments which specify the reason for the error (a string), the name of the source file in which it occurred (also a string), the line number in that file (an integer) and the error number (an integer). The source file and line number are set at compile time using the __FILE__ and __LINE__ directives in the preprocessor. An error handler function returns type void. Error handler functions should be defined like this,

void handler (const char * reason, 
              const char * file, 
              int line, 
              int gsl_errno)

To request the use of your own error handler you need to call the function gsl_set_error_handler which is also declared in `gsl_errno.h',

Function: gsl_error_handler_t gsl_set_error_handler (gsl_error_handler_t new_handler)

This functions sets a new error handler, new_handler, for the GSL library routines. The previous handler is returned (so that you can restore it later). Note that the pointer to a user defined error handler function is stored in a static variable, so there can only be one error handler per program. This function should be not be used in multi-threaded programs except to set up a program-wide error handler from a master thread. The following example shows how to set and restore a new error handler,

/* save original handler, install new handler */
old_handler = gsl_set_error_handler (&my_handler); 

/* code uses new handler */
.....     

/* restore original handler */
gsl_set_error_handler (old_handler); 

To use the default behavior (abort on error) set the error handler to NULL,

old_handler = gsl_set_error_handler (NULL); 

Function: gsl_error_handler_t gsl_set_error_handler_off ()

This function turns off the error handler by defining an error handler which does nothing. This will cause the program to continue after any error, so the return values from any library routines must be checked. This is the recommended behavior for production programs. The previous handler is returned (so that you can restore it later).

The error behavior can be changed for specific applications by recompiling the library with a customized definition of the GSL_ERROR macro in the file `gsl_errno.h'.