2 This chapter describes the way that GSL functions report and handle
3 errors. By examining the status information returned by every function
4 you can determine whether it succeeded or failed, and if it failed you
5 can find out what the precise cause of failure was. You can also define
6 your own error handling functions to modify the default behavior of the
9 The functions described in this section are declared in the header file
16 * Using GSL error reporting in your own functions::
17 * Error Reporting Examples::
21 @section Error Reporting
23 The library follows the thread-safe error reporting conventions of the
24 @sc{posix} Threads library. Functions return a non-zero error code to
25 indicate an error and @code{0} to indicate success.
28 int status = gsl_function (...)
30 if (status) @{ /* an error occurred */
32 /* status value specifies the type of error */
36 The routines report an error whenever they cannot perform the task
37 requested of them. For example, a root-finding function would return a
38 non-zero error code if could not converge to the requested accuracy, or
39 exceeded a limit on the number of iterations. Situations like this are
40 a normal occurrence when using any mathematical library and you should
41 check the return status of the functions that you call.
43 Whenever a routine reports an error the return value specifies the type
44 of error. The return value is analogous to the value of the variable
45 @code{errno} in the C library. The caller can examine the return code
46 and decide what action to take, including ignoring the error if it is
47 not considered serious.
49 In addition to reporting errors by return codes the library also has an
50 error handler function @code{gsl_error}. This function is called by
51 other library functions when they report an error, just before they
52 return to the caller. The default behavior of the error handler is to
53 print a message and abort the program,
56 gsl: file.c:67: ERROR: invalid argument supplied by user
57 Default GSL error handler invoked.
61 The purpose of the @code{gsl_error} handler is to provide a function
62 where a breakpoint can be set that will catch library errors when
63 running under the debugger. It is not intended for use in production
64 programs, which should handle any errors using the return codes.
68 @cindex error codes, reserved
69 The error code numbers returned by library functions are defined in
70 the file @file{gsl_errno.h}. They all have the prefix @code{GSL_} and
71 expand to non-zero constant integer values. Error codes above 1024 are
72 reserved for applications, and are not used by the library. Many of
73 the error codes use the same base name as the corresponding error code
74 in the C library. Here are some of the most common error codes,
77 @deftypefn {Macro} int GSL_EDOM
78 Domain error; used by mathematical functions when an argument value does
79 not fall into the domain over which the function is defined (like
80 EDOM in the C library)
83 @deftypefn {Macro} int GSL_ERANGE
84 Range error; used by mathematical functions when the result value is not
85 representable because of overflow or underflow (like ERANGE in the C
89 @deftypefn {Macro} int GSL_ENOMEM
90 No memory available. The system cannot allocate more virtual memory
91 because its capacity is full (like ENOMEM in the C library). This error
92 is reported when a GSL routine encounters problems when trying to
93 allocate memory with @code{malloc}.
96 @deftypefn {Macro} int GSL_EINVAL
97 Invalid argument. This is used to indicate various kinds of problems
98 with passing the wrong argument to a library function (like EINVAL in the C
102 The error codes can be converted into an error message using the
103 function @code{gsl_strerror}.
105 @deftypefun {const char *} gsl_strerror (const int @var{gsl_errno})
106 This function returns a pointer to a string describing the error code
107 @var{gsl_errno}. For example,
110 printf ("error: %s\n", gsl_strerror (status));
114 would print an error message like @code{error: output range error} for a
115 status value of @code{GSL_ERANGE}.
119 @section Error Handlers
120 @cindex Error handlers
122 The default behavior of the GSL error handler is to print a short
123 message and call @code{abort}. When this default is in use programs
124 will stop with a core-dump whenever a library routine reports an error.
125 This is intended as a fail-safe default for programs which do not check
126 the return status of library routines (we don't encourage you to write
129 If you turn off the default error handler it is your responsibility to
130 check the return values of routines and handle them yourself. You can
131 also customize the error behavior by providing a new error handler. For
132 example, an alternative error handler could log all errors to a file,
133 ignore certain error conditions (such as underflows), or start the
134 debugger and attach it to the current process when an error occurs.
136 All GSL error handlers have the type @code{gsl_error_handler_t}, which is
137 defined in @file{gsl_errno.h},
139 @deftp {Data Type} gsl_error_handler_t
141 This is the type of GSL error handler functions. An error handler will
142 be passed four arguments which specify the reason for the error (a
143 string), the name of the source file in which it occurred (also a
144 string), the line number in that file (an integer) and the error number
145 (an integer). The source file and line number are set at compile time
146 using the @code{__FILE__} and @code{__LINE__} directives in the
147 preprocessor. An error handler function returns type @code{void}.
148 Error handler functions should be defined like this,
151 void handler (const char * reason,
160 To request the use of your own error handler you need to call the
161 function @code{gsl_set_error_handler} which is also declared in
164 @deftypefun {gsl_error_handler_t *} gsl_set_error_handler (gsl_error_handler_t * @var{new_handler})
166 This function sets a new error handler, @var{new_handler}, for the GSL
167 library routines. The previous handler is returned (so that you can
168 restore it later). Note that the pointer to a user defined error
169 handler function is stored in a static variable, so there can be only
170 one error handler per program. This function should be not be used in
171 multi-threaded programs except to set up a program-wide error handler
172 from a master thread. The following example shows how to set and
173 restore a new error handler,
176 /* save original handler, install new handler */
177 old_handler = gsl_set_error_handler (&my_handler);
179 /* code uses new handler */
182 /* restore original handler */
183 gsl_set_error_handler (old_handler);
187 To use the default behavior (@code{abort} on error) set the error
188 handler to @code{NULL},
191 old_handler = gsl_set_error_handler (NULL);
195 @deftypefun {gsl_error_handler_t *} gsl_set_error_handler_off ()
196 This function turns off the error handler by defining an error handler
197 which does nothing. This will cause the program to continue after any
198 error, so the return values from any library routines must be checked.
199 This is the recommended behavior for production programs. The previous
200 handler is returned (so that you can restore it later).
203 The error behavior can be changed for specific applications by
204 recompiling the library with a customized definition of the
205 @code{GSL_ERROR} macro in the file @file{gsl_errno.h}.
207 @node Using GSL error reporting in your own functions
208 @section Using GSL error reporting in your own functions
209 @cindex error handling macros
210 If you are writing numerical functions in a program which also uses GSL
211 code you may find it convenient to adopt the same error reporting
212 conventions as in the library.
214 To report an error you need to call the function @code{gsl_error} with a
215 string describing the error and then return an appropriate error code
216 from @code{gsl_errno.h}, or a special value, such as @code{NaN}. For
217 convenience the file @file{gsl_errno.h} defines two macros which carry
220 @deffn {Macro} GSL_ERROR (@var{reason}, @var{gsl_errno})
222 This macro reports an error using the GSL conventions and returns a
223 status value of @code{gsl_errno}. It expands to the following code fragment,
226 gsl_error (reason, __FILE__, __LINE__, gsl_errno);
231 The macro definition in @file{gsl_errno.h} actually wraps the code
232 in a @code{do @{ ... @} while (0)} block to prevent possible
236 Here is an example of how the macro could be used to report that a
237 routine did not achieve a requested tolerance. To report the error the
238 routine needs to return the error code @code{GSL_ETOL}.
241 if (residual > tolerance)
243 GSL_ERROR("residual exceeds tolerance", GSL_ETOL);
247 @deffn {Macro} GSL_ERROR_VAL (@var{reason}, @var{gsl_errno}, @var{value})
249 This macro is the same as @code{GSL_ERROR} but returns a user-defined
250 value of @var{value} instead of an error code. It can be used for
251 mathematical functions that return a floating point value.
254 The following example shows how to return a @code{NaN} at a mathematical
255 singularity using the @code{GSL_ERROR_VAL} macro,
260 GSL_ERROR_VAL("argument lies on singularity",
261 GSL_ERANGE, GSL_NAN);
266 @node Error Reporting Examples
269 Here is an example of some code which checks the return value of a
270 function where an error might be reported,
274 #include <gsl/gsl_errno.h>
275 #include <gsl/gsl_fft_complex.h>
281 gsl_set_error_handler_off();
283 status = gsl_fft_complex_radix2_forward (data, stride, n);
286 if (status == GSL_EINVAL) @{
287 fprintf (stderr, "invalid argument, n=%d\n", n);
289 fprintf (stderr, "failed, gsl_errno=%d\n",
299 The function @code{gsl_fft_complex_radix2} only accepts integer lengths
300 which are a power of two. If the variable @code{n} is not a power of
301 two then the call to the library function will return @code{GSL_EINVAL},
302 indicating that the length argument is invalid. The function call to
303 @code{gsl_set_error_handler_off} stops the default error handler from
304 aborting the program. The @code{else} clause catches any other possible