3.3 Using GSL error reporting in your own functions

To report an error you need to call the function gsl_error with a string describing the error and then return an appropriate error code from gsl_errno.h, or a special value, such as NaN. For convenience the file `gsl_errno.h' defines two macros which carry out these steps:

Macro: GSL_ERROR (reason, gsl_errno)

This macro reports an error using the GSL conventions and returns a status value of gsl_errno. It expands to the following code fragment,

gsl_error (reason, __FILE__, __LINE__, gsl_errno); return gsl_errno;

The macro definition in `gsl_errno.h' actually wraps the code in a do { ... } while (0) block to prevent possible parsing problems.

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

if (residual > tolerance) { GSL_ERROR("residual exceeds tolerance", GSL_ETOL); }

Macro: GSL_ERROR_VAL (reason, gsl_errno, value)

This macro is the same as GSL_ERROR but returns a user-defined status value of value instead of an error code. It can be used for mathematical functions that return a floating point value.

Here is an example where a function needs to return a NaN because of a mathematical singularity,

if (x == 0) { GSL_ERROR_VAL("argument lies on singularity", GSL_ERANGE, GSL_NAN); }