Error handling


Defines

#define cpl_ensure(BOOL, ERRCODE, RETURN)   cpl_error_ensure(BOOL, ERRCODE, return(RETURN), " ")
 Set an error code and return iff a boolean expression is false.
#define cpl_ensure_code(BOOL, ERRCODE)   cpl_error_ensure(BOOL, ERRCODE, return(cpl_error_get_code()), " ")
 Set an error code and return it iff a boolean expression is false.
#define cpl_error_ensure(CONDITION, CODE, ACTION,)
 Generic error handling macro.
#define CPL_ERROR_MAX_MESSAGE_LENGTH   256
 The maximum length of a CPL error message.
#define cpl_error_set(function, code)
 Set CPL error code, function name, source file and line number where an error occurred.
#define cpl_error_set_message(function, code,)
 Set CPL error code, function name, source file and line number where an error occurred along with a text message.
#define cpl_error_set_where(function)
 Propagate a CPL-error to the current location.
#define CPL_HAVE_VA_ARGS   1
 Flag to indicate support for variadic macros.

Typedefs

typedef enum _cpl_error_code_ cpl_error_code
 The cpl_error_code type definition.

Enumerations

enum  _cpl_error_code_ {
  CPL_ERROR_NONE = 0,
  CPL_ERROR_UNSPECIFIED = 1,
  CPL_ERROR_DUPLICATING_STREAM,
  CPL_ERROR_ASSIGNING_STREAM,
  CPL_ERROR_FILE_IO,
  CPL_ERROR_BAD_FILE_FORMAT,
  CPL_ERROR_FILE_ALREADY_OPEN,
  CPL_ERROR_FILE_NOT_CREATED,
  CPL_ERROR_FILE_NOT_FOUND,
  CPL_ERROR_DATA_NOT_FOUND,
  CPL_ERROR_ACCESS_OUT_OF_RANGE,
  CPL_ERROR_NULL_INPUT,
  CPL_ERROR_INCOMPATIBLE_INPUT,
  CPL_ERROR_ILLEGAL_INPUT,
  CPL_ERROR_ILLEGAL_OUTPUT,
  CPL_ERROR_UNSUPPORTED_MODE,
  CPL_ERROR_SINGULAR_MATRIX,
  CPL_ERROR_DIVISION_BY_ZERO,
  CPL_ERROR_TYPE_MISMATCH,
  CPL_ERROR_INVALID_TYPE,
  CPL_ERROR_CONTINUE,
  CPL_ERROR_NO_WCS,
  CPL_ERROR_EOL
}
 Available error codes. More...

Functions

cpl_error_code cpl_error_get_code (void)
 Get the last cpl_error_code set.
const char * cpl_error_get_file (void)
 Get the source code file name where the last CPL error occurred.
const char * cpl_error_get_function (void)
 Get the function name where the last CPL error occurred.
unsigned cpl_error_get_line (void)
 Get the line number where the last CPL error occurred.
const char * cpl_error_get_message (void)
 Get the text message of the current CPL error.
const char * cpl_error_get_message_default (cpl_error_code code)
 Return the standard CPL error message of the current CPL error.
const char * cpl_error_get_where (void)
 Get function name, source file and line number where the last CPL error occurred.
void cpl_error_reset (void)
 Reset the cpl_error_code.

Detailed Description

This module provides functions to maintain the cpl_error_code set by any CPL function, similarly to what is done with the errno variable of the standard C library. The following guidelines are respected:

A cpl_error_code equal to the enumeration constant CPL_ERROR_NONE would indicate no error condition. Note, however, that the cpl_error_code is only set when an error occurs, and it is not reset by successful function calls. For this reason it may be appropriate in some cases to reset the cpl_error_code using the function cpl_error_reset(). The cpl_error_code set by a CPL function can be obtained by calling the function cpl_error_get_code(), but functions of type cpl_error_code would not only return this code directly, but would also return CPL_ERROR_NONE in case of success. Other CPL functions return zero on success, or a non-zero value to indicate a change of the cpl_error_code, while CPL functions returning a pointer would flag an error by returning a NULL.

To each cpl_error_code is associated a standard error message, that can be obtained by calling the function cpl_error_get_message(). Conventionally, no CPL function will ever display any error message, leaving to the caller the decision of how to handle a given error condition. A call to the function cpl_error_get_function() would return the name of the function where the error occurred, and the functions cpl_error_get_file() and cpl_error_get_line() would also return the name of the source file containing the function code, and the line number where the error occurred. The function cpl_error_get_where() would gather all this items together, in a colon-separated string.

Synopsis:
   #include <cpl_error.h>

Define Documentation

#define cpl_ensure ( BOOL,
ERRCODE,
RETURN   )     cpl_error_ensure(BOOL, ERRCODE, return(RETURN), " ")

Set an error code and return iff a boolean expression is false.

Parameters:
BOOL The boolean to evaluate
ERRCODE The error code to set
RETURN The value to return
Note:
This macro will cause a return from its calling function. If ERRCODE equals CPL_ERROR_NONE, the error-code is set to CPL_ERROR_UNSPECIFIED. The boolean is always evaluated (unlike assert()). This macro may not be used in inline'd functions.
See also:
cpl_error_set()

#define cpl_ensure_code ( BOOL,
ERRCODE   )     cpl_error_ensure(BOOL, ERRCODE, return(cpl_error_get_code()), " ")

Set an error code and return it iff a boolean expression is false.

Parameters:
BOOL The boolean to evaluate
ERRCODE The error code to set and return
See also:
cpl_ensure()

#define cpl_error_ensure ( CONDITION,
CODE,
ACTION   ) 

Value:

do if (!(CONDITION)) {                                                     \
        /* Evaluate exactly once using a name-space protected variable name */ \
        const cpl_error_code cpl_ensure_error = (CODE);                        \
        (void)cpl_error_set_message_macro(cpl_func, cpl_ensure_error           \
                                          ? cpl_ensure_error :                 \
                                          CPL_ERROR_UNSPECIFIED,               \
                                           __FILE__, __LINE__, __VA_ARGS__);   \
        ACTION;                                                                \
    } while (0)
Generic error handling macro.

Parameters:
CONDITION The condition to check
CODE The CPL error code to set if CONDTION is non-zero
ACTION A statement that is executed iff the CONDITION evaluates to non-zero.
... A printf-style message for cpl_error_set_message().
See also:
cpl_error_set_message()
Note:
This macro should not be used directly. It is defined only to support user-defined error handling macros. If CODE equals CPL_ERROR_NONE, a CPL error with code CPL_ERROR_UNSPECIFIED is created. The message may be a printf-like format string supplied with arguments unless variadic macros are not supported in which case only a non-format string is accepted. The provided CODE, ACTION and __VA_ARGS__ are evaluated/executed only if the CONDITION evaluates to false (zero). The ACTION break is unsupported (it currently causes the execution to continue after cpl_error_ensure()). Some of the below examples use a goto statement to jump to a single cleanup label, assumed to be located immediately before the function's unified cleanup-code and return point. This error-handling scheme is reminiscent of using exceptions in languages that support exceptions (C++, Java, ...). The use of goto and a single clean-up label per function "if the error-handling code is non- trivial, and if errors can occur in several places" is sanctioned by Kernigan & Richie: "The C Programming Language". For any other purpose goto should be avoided.
Useful definitions might include

   #define assure(BOOL, CODE)                                                  \
     cpl_error_ensure(BOOL, CODE, goto cleanup, " ")

   #define  check(CMD)                                                         \
     cpl_error_ensure((CMD, cpl_error_get_code() == CPL_ERROR_NONE),           \
                      cpl_error_get_code(), goto cleanup, " ")

   #define assert(BOOL)                                                        \
     cpl_error_ensure(BOOL, CPL_ERROR_UNSPECIFIED, goto cleanup,               \
                      "Internal error, please report to " PACKAGE_BUGREPORT)

or (same as above, but including printf-style error messages)

   #define assure(BOOL, CODE, ...)                                             \
     cpl_error_ensure(BOOL, CODE, goto cleanup, __VA_ARGS__)

   #define  check(CMD, ...)                                                    \
     cpl_error_ensure((CMD, cpl_error_get_code() == CPL_ERROR_NONE),           \
                      cpl_error_get_code(), goto cleanup, __VA_ARGS__)

   #define assert(BOOL, ...)                                                   \
     cpl_error_ensure(BOOL, CPL_ERROR_UNSPECIFIED, goto cleanup,               \
                      "Internal error, please report to " PACKAGE_BUGREPORT    \
                      " " __VA_ARGS__)
                      / *  Assumes that PACKAGE_BUGREPORT
                           contains no formatting special characters  * /

or

   #define skip_if(BOOL)                                                       \
     cpl_error_ensure(BOOL, cpl_error_get_code() != CPL_ERROR_NONE ?           \
                      cpl_error_get_code() : CPL_ERROR_UNSPECIFIED,            \
                      goto cleanup, " ")

The check macros in the examples above can be used to check a command which sets the cpl_error_code in case of failure (or, by use of a comma expression, a longer sequence of such commands):

   check(
       (x = cpl_table_get_int(table, "x", 0, NULL),
        y = cpl_table_get_int(table, "y", 0, NULL),
        z = cpl_table_get_int(table, "z", 0, NULL)),
       "Error reading wavelength catalogue");

#define CPL_ERROR_MAX_MESSAGE_LENGTH   256

The maximum length of a CPL error message.

See also:
cpl_error_get_message()

#define cpl_error_set ( function,
code   ) 

Set CPL error code, function name, source file and line number where an error occurred.

Parameters:
function Character string with function name, cpl_func
code Error code
Returns:
The specified error code.
Note:
If code is CPL_ERROR_NONE, nothing is done (and code is returned).

#define cpl_error_set_message ( function,
code   ) 

Set CPL error code, function name, source file and line number where an error occurred along with a text message.

Parameters:
function Character string with function name, cpl_func
code Error code
... Variable argument list with message
Returns:
The CPL error code
See also:
cpl_error_set()
Note:
The message is ignored if it is NULL, empty, or consists of a single ' ' (space). Otherwise, the user supplied message is appended to the default message using ': ' (colon+space) as delimiter. The message may be a printf-like format string supplied with arguments unless variadic macros are not supported in which case only a non-format string is accepted.
Example of usage:
    if (image == NULL) {
        return cpl_error_set_message(cpl_func, CPL_ERROR_NULL_INPUT,
                                     "Image number %d is NULL", number);
    }

#define cpl_error_set_where ( function   ) 

Propagate a CPL-error to the current location.

Parameters:
function Character string with function name, cpl_func
Returns:
The preexisting CPL error code (possibly CPL_ERROR_NONE).
See also:
cpl_error_set()
Note:
If no error exists, nothing is done and CPL_ERROR_NONE is returned
If a CPL error already exists, this function creates a new CPL error with the preexisting CPL error code and the current location.

In a function of type cpl_error_code an error can be propagated with:

    return cpl_error_set_where(cpl_func);

#define CPL_HAVE_VA_ARGS   1

Flag to indicate support for variadic macros.

See also:
cpl_error_set_message()
Note:
Unless already defined, tries to detect whether variadic macros are supported, not only when CPL is compiled, but also when the CPL-based application is compiled. This check, which is hardly robust, should support
  • disabling of variadic macros when compiling with gcc -ansi
  • enabling them when compiling with gcc -std=c99


Typedef Documentation

typedef enum _cpl_error_code_ cpl_error_code

The cpl_error_code type definition.


Enumeration Type Documentation

enum _cpl_error_code_

Available error codes.

CPL_ERROR_NONE is equal to zero and compares to less than all other error codes.

All error codes are guaranteed to be less than CPL_ERROR_EOL (End Of List). CPL_ERROR_EOL allows user defined error codes to be added in this fashion:

      const int my_first_error_code  = 0 + CPL_ERROR_EOL;
      const int my_second_error_code = 1 + CPL_ERROR_EOL;
      const int my_third_error_code  = 2 + CPL_ERROR_EOL;

      if (is_connected() == CPL_FALSE) {
         return cpl_error_set_message(cpl_func, my_first_error_code, "No "
                                      "connection to host %s (after %u tries)",
                                      hostname, max_attempts);
      }

Extensive use of user defined error codes should be avoided. Instead a request of new CPL error codes should be emailed to cpl-help@eso.org.

Enumerator:
CPL_ERROR_NONE  No error condition
CPL_ERROR_UNSPECIFIED  An unspecified error. FIXME: Do not set to 1 and verify correctness
CPL_ERROR_DUPLICATING_STREAM  Could not duplicate output stream
CPL_ERROR_ASSIGNING_STREAM  Could not associate a stream with a file descriptor
CPL_ERROR_FILE_IO  Permission denied
CPL_ERROR_BAD_FILE_FORMAT  Input file had not the expected format
CPL_ERROR_FILE_ALREADY_OPEN  Attempted to open a file twice
CPL_ERROR_FILE_NOT_CREATED  Could not create a file
CPL_ERROR_FILE_NOT_FOUND  A specified file or directory was not found
CPL_ERROR_DATA_NOT_FOUND  Data searched within a valid object were not found
CPL_ERROR_ACCESS_OUT_OF_RANGE  Data were accessed beyond boundaries
CPL_ERROR_NULL_INPUT  A NULL pointer was found where a valid pointer was expected
CPL_ERROR_INCOMPATIBLE_INPUT  Data that had to be processed together did not match
CPL_ERROR_ILLEGAL_INPUT  Illegal values were detected
CPL_ERROR_ILLEGAL_OUTPUT  A given operation would have generated an illegal object
CPL_ERROR_UNSUPPORTED_MODE  The requested functionality is not supported
CPL_ERROR_SINGULAR_MATRIX  Could not invert a matrix
CPL_ERROR_DIVISION_BY_ZERO  Attempted to divide a number by zero
CPL_ERROR_TYPE_MISMATCH  Data were not of the expected type
CPL_ERROR_INVALID_TYPE  Data type was unsupported or invalid
CPL_ERROR_CONTINUE  An iterative process did not converge
CPL_ERROR_NO_WCS  The WCS functionalities are missing
CPL_ERROR_EOL  To permit extensibility of error handling. It is a coding error to use this within CPL itself!


Function Documentation

cpl_error_code cpl_error_get_code ( void   ) 

Get the last cpl_error_code set.

Returns:
cpl_error_code of last occurred CPL error.
Get cpl_error_code of last occurred error.

const char* cpl_error_get_file ( void   ) 

Get the source code file name where the last CPL error occurred.

Returns:
Name of source file name where the last CPL error occurred.
Get the source code file name where the last CPL error occurred.

const char* cpl_error_get_function ( void   ) 

Get the function name where the last CPL error occurred.

Returns:
Identifier string of the function name where the last CPL error occurred.
Get the function name where the last CPL error occurred.

unsigned cpl_error_get_line ( void   ) 

Get the line number where the last CPL error occurred.

Returns:
Line number of the source file where the last CPL error occurred.
Get the line number of the source file where the last CPL error occurred.

const char* cpl_error_get_message ( void   ) 

Get the text message of the current CPL error.

Returns:
The text message of the current CPL error.
See also:
cpl_error_get_message_default(), cpl_error_set_message()
If the cpl_error_code is equal to CPL_ERROR_NONE, an empty string is returned. Otherwise, the message is the default message for the current CPL error code, possibly extended with a custom message supplied when the error was set.

const char* cpl_error_get_message_default ( cpl_error_code  code  ) 

Return the standard CPL error message of the current CPL error.

Parameters:
code The error code of the current CPL error
Returns:
The standard CPL error message of the current CPL error

const char* cpl_error_get_where ( void   ) 

Get function name, source file and line number where the last CPL error occurred.

Returns:
String containing function name, source file and line number separated by colons (:).
Get where the last CPL error occurred in the form function_name:source_file:line_number

void cpl_error_reset ( void   ) 

Reset the cpl_error_code.

Returns:
Nothing.
This function initialises the cpl_error_code to CPL_ERROR_NONE.


Generated on Wed Mar 18 09:40:12 2009 for Common Pipeline Library Reference Manual by  doxygen 1.4.7