GNU Scientific Library – Reference Manual: Using GSL error reporting in your own functions

Next: Error Reporting Examples, Previous: Error Handlers, Up: Error Handling [Index]

### 3.4 Using GSL error reporting in your own functions

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 `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 value of value instead of an error code. It can be used for mathematical functions that return a floating point value.

The following example shows how to return a `NaN` at a mathematical singularity using the `GSL_ERROR_VAL` macro,

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

Next: Error Reporting Examples, Previous: Error Handlers, Up: Error Handling [Index]