diff options
Diffstat (limited to 'gsl-1.9/doc/err.texi')
-rw-r--r-- | gsl-1.9/doc/err.texi | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/gsl-1.9/doc/err.texi b/gsl-1.9/doc/err.texi new file mode 100644 index 0000000..a687120 --- /dev/null +++ b/gsl-1.9/doc/err.texi @@ -0,0 +1,306 @@ +@cindex error handling +This chapter describes the way that GSL functions report and handle +errors. By examining the status information returned by every function +you can determine whether it succeeded or failed, and if it failed you +can find out what the precise cause of failure was. You can also define +your own error handling functions to modify the default behavior of the +library. + +The functions described in this section are declared in the header file +@file{gsl_errno.h}. + +@menu +* Error Reporting:: +* Error Codes:: +* Error Handlers:: +* Using GSL error reporting in your own functions:: +* Error Reporting Examples:: +@end menu + +@node Error Reporting +@section Error Reporting + +The library follows the thread-safe error reporting conventions of the +@sc{posix} Threads library. Functions return a non-zero error code to +indicate an error and @code{0} to indicate success. + +@example +int status = gsl_function (...) + +if (status) @{ /* an error occurred */ + ..... + /* status value specifies the type of error */ +@} +@end example + +The routines report an error whenever they cannot perform the task +requested of them. For example, a root-finding function would return a +non-zero error code if could not converge to the requested accuracy, or +exceeded a limit on the number of iterations. Situations like this are +a normal occurrence when using any mathematical library and you should +check the return status of the functions that you call. + +Whenever a routine reports an error the return value specifies the type +of error. The return value is analogous to the value of the variable +@code{errno} in the C library. The caller can examine the return code +and decide what action to take, including ignoring the error if it is +not considered serious. + +In addition to reporting errors by return codes the library also has an +error handler function @code{gsl_error}. This function is called by +other library functions when they report an error, just before they +return to the caller. The default behavior of the error handler is to +print a message and abort the program, + +@example +gsl: file.c:67: ERROR: invalid argument supplied by user +Default GSL error handler invoked. +Aborted +@end example + +The purpose of the @code{gsl_error} 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 return codes. + +@node Error Codes +@section Error Codes +@cindex error codes, reserved +The error code numbers returned by library functions are defined in +the file @file{gsl_errno.h}. They all have the prefix @code{GSL_} and +expand to non-zero constant integer values. Error codes above 1024 are +reserved for applications, and are not used by the library. Many of +the error codes use the same base name as the corresponding error code +in the C library. Here are some of the most common error codes, + +@cindex error codes +@deftypefn {Macro} int GSL_EDOM +Domain error; used by mathematical functions when an argument value does +not fall into the domain over which the function is defined (like +EDOM in the C library) +@end deftypefn + +@deftypefn {Macro} int GSL_ERANGE +Range error; used by mathematical functions when the result value is not +representable because of overflow or underflow (like ERANGE in the C +library) +@end deftypefn + +@deftypefn {Macro} int GSL_ENOMEM +No memory available. The system cannot allocate more virtual memory +because its capacity is full (like ENOMEM in the C library). This error +is reported when a GSL routine encounters problems when trying to +allocate memory with @code{malloc}. +@end deftypefn + +@deftypefn {Macro} int GSL_EINVAL +Invalid argument. This is used to indicate various kinds of problems +with passing the wrong argument to a library function (like EINVAL in the C +library). +@end deftypefn + +The error codes can be converted into an error message using the +function @code{gsl_strerror}. + +@deftypefun {const char *} gsl_strerror (const int @var{gsl_errno}) +This function returns a pointer to a string describing the error code +@var{gsl_errno}. For example, + +@example +printf ("error: %s\n", gsl_strerror (status)); +@end example + +@noindent +would print an error message like @code{error: output range error} for a +status value of @code{GSL_ERANGE}. +@end deftypefun + +@node Error Handlers +@section Error Handlers +@cindex Error handlers + +The default behavior of the GSL error handler is to print a short +message and call @code{abort}. When this default is in use programs +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 routines and handle them yourself. You can +also 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 @code{gsl_error_handler_t}, which is +defined in @file{gsl_errno.h}, + +@deftp {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 @code{__FILE__} and @code{__LINE__} directives in the +preprocessor. An error handler function returns type @code{void}. +Error handler functions should be defined like this, + +@example +void handler (const char * reason, + const char * file, + int line, + int gsl_errno) +@end example +@end deftp +@comment + +@noindent +To request the use of your own error handler you need to call the +function @code{gsl_set_error_handler} which is also declared in +@file{gsl_errno.h}, + +@deftypefun {gsl_error_handler_t *} gsl_set_error_handler (gsl_error_handler_t @var{new_handler}) + +This function sets a new error handler, @var{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 be only +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, + +@example +/* 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); +@end example + +@noindent +To use the default behavior (@code{abort} on error) set the error +handler to @code{NULL}, + +@example +old_handler = gsl_set_error_handler (NULL); +@end example +@end deftypefun + +@deftypefun {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). +@end deftypefun + +The error behavior can be changed for specific applications by +recompiling the library with a customized definition of the +@code{GSL_ERROR} macro in the file @file{gsl_errno.h}. + +@node Using GSL error reporting in your own functions +@section Using GSL error reporting in your own functions +@cindex error handling macros +If you are writing numerical functions in a program which also uses GSL +code you may find it convenient to adopt the same error reporting +conventions as in the library. + +To report an error you need to call the function @code{gsl_error} with a +string describing the error and then return an appropriate error code +from @code{gsl_errno.h}, or a special value, such as @code{NaN}. For +convenience the file @file{gsl_errno.h} defines two macros which carry +out these steps: + +@deffn {Macro} GSL_ERROR (@var{reason}, @var{gsl_errno}) + +This macro reports an error using the GSL conventions and returns a +status value of @code{gsl_errno}. It expands to the following code fragment, + +@example +gsl_error (reason, __FILE__, __LINE__, gsl_errno); +return gsl_errno; +@end example + +@noindent +The macro definition in @file{gsl_errno.h} actually wraps the code +in a @code{do @{ ... @} while (0)} block to prevent possible +parsing problems. +@end deffn + +Here is an example of how the macro could be used to report that a +routine did not achieve a requested tolerance. To report the error the +routine needs to return the error code @code{GSL_ETOL}. + +@example +if (residual > tolerance) + @{ + GSL_ERROR("residual exceeds tolerance", GSL_ETOL); + @} +@end example + +@deffn {Macro} GSL_ERROR_VAL (@var{reason}, @var{gsl_errno}, @var{value}) + +This macro is the same as @code{GSL_ERROR} but returns a user-defined +value of @var{value} instead of an error code. It can be used for +mathematical functions that return a floating point value. +@end deffn + +The following example shows how to return a @code{NaN} at a mathematical +singularity using the @code{GSL_ERROR_VAL} macro, + +@example +if (x == 0) + @{ + GSL_ERROR_VAL("argument lies on singularity", + GSL_ERANGE, GSL_NAN); + @} +@end example + + +@node Error Reporting Examples +@section Examples + +Here is an example of some code which checks the return value of a +function where an error might be reported, + +@example +#include <stdio.h> +#include <gsl/gsl_errno.h> +#include <gsl/gsl_fft_complex.h> + +... + int status; + size_t n = 37; + + gsl_set_error_handler_off(); + + status = gsl_fft_complex_radix2_forward (data, n); + + if (status) @{ + if (status == GSL_EINVAL) @{ + fprintf (stderr, "invalid argument, n=%d\n", n); + @} else @{ + fprintf (stderr, "failed, gsl_errno=%d\n", + status); + @} + exit (-1); + @} +... +@end example +@comment + +@noindent +The function @code{gsl_fft_complex_radix2} only accepts integer lengths +which are a power of two. If the variable @code{n} is not a power of +two then the call to the library function will return @code{GSL_EINVAL}, +indicating that the length argument is invalid. The function call to +@code{gsl_set_error_handler_off} stops the default error handler from +aborting the program. The @code{else} clause catches any other possible +errors. + |