Error handling

Macros
#define	cpl_ensure(BOOL, ERRCODE, RETURN)
	Set an error code and return iff a boolean expression is false.
#define	cpl_ensure_code(BOOL, ERRCODE)
	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
	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_HISTORY_LOST ,   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.

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:

• If no error occurs in a CPL function the cpl_error_code will remain unchanged.
• If an error occurs in a CPL function, a new CPL error is set, causing the cpl_error_code to be modified to the new error.

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>

Macro Definition Documentation

cpl_ensure

#define cpl_ensure	(		BOOL,
			ERRCODE,
			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()

cpl_ensure_code

#define cpl_ensure_code	(		BOOL,
			ERRCODE
	)

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()

cpl_error_ensure

#define cpl_error_ensure	(		CONDITION,
			CODE,
			ACTION,
			...
	)

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");

CPL_ERROR_MAX_MESSAGE_LENGTH

#define CPL_ERROR_MAX_MESSAGE_LENGTH   256

The maximum length of a CPL error message.

See also

cpl_error_get_message()

cpl_error_set

#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), if code is CPL_ERROR_HISTORY_LOST (but avoid that) then CPL_ERROR_UNSPECIFIED is set and returned.

cpl_error_set_message

#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. If the CPL-based application may use variadic macros, the message may be a printf-style format string supplied with matching arguments. If variadic macros are not allowed (e.g. when compiling with gcc -ansi) only a non-format string is accepted. Please be aware that the format string should always be a string literal, otherwise the code may be vulnerable to the socalled 'format string exploit'. Sufficiently recent versions of gcc supports the option -Wformat-security, which tries to warn of this issue. If variadic macros are not supported, a printf-style message can be created prior to the call to cpl_error_set_message(), as in the below example.

Examples of usage:

if (image == NULL) {
    return cpl_error_set_message(cpl_func, CPL_ERROR_NULL_INPUT,
                                 "Image number %d is NULL", number);
}

if (error_string != NULL) {
    return cpl_error_set_message(cpl_func, CPL_ERROR_ILLEGAL_INPUT,
                                 "%s", error_string);
}

Example of usage if and only if variadic macros are unavaiable (e.g. when compiling with gcc -ansi):

if (image == NULL) {
    char * my_txt = cpl_sprintf("Image number %d is NULL", number);
    const cpl_error_code my_code =
        cpl_error_set_message(cpl_func, CPL_ERROR_NULL_INPUT, my_txt);
    cpl_free(my_txt);
    return my_code;
}

cpl_error_set_where

#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);

CPL_HAVE_VA_ARGS

#define CPL_HAVE_VA_ARGS

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, typically at compile-time of a CPL-based application. This check, which is hardly robust, should support

• disabling of variadic macros when compiling with gcc -ansi
• enabling them when compiling with a C99 compliant compiler, such as gcc -std=c99

Typedef Documentation

cpl_error_code

typedef enum _cpl_error_code_ cpl_error_code

The cpl_error_code type definition.

Enumeration Type Documentation

_cpl_error_code_

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-h.nosp@m.elp@.nosp@m.eso.o.nosp@m.rg.

Enumerator
CPL_ERROR_NONE	No error condition
CPL_ERROR_UNSPECIFIED	An unspecified error
CPL_ERROR_HISTORY_LOST	The actual CPL error has been lost. Do not use to create a CPL error
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_get_code()

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.

References CPL_ERROR_NONE.

Referenced by cpl_apertures_extract_window(), cpl_bivector_interpolate_linear(), cpl_detector_interpolate_rejected(), cpl_dfs_save_paf(), cpl_dfs_setup_product_header(), cpl_dfs_sign_products(), cpl_errorstate_dump(), cpl_frameset_dump(), cpl_frameset_extract(), cpl_frameset_labelise(), cpl_image_abs_create(), cpl_image_add_scalar_create(), cpl_image_collapse_create(), cpl_image_divide_scalar_create(), cpl_image_exponential_create(), cpl_image_fft(), cpl_image_filter_median(), cpl_image_filter_stdev(), cpl_image_get_fwhm(), cpl_image_get_interpolated(), cpl_image_logarithm_create(), cpl_image_multiply_scalar_create(), cpl_image_normalise(), cpl_image_power_create(), cpl_image_subtract_scalar_create(), cpl_image_warp_polynomial(), cpl_imagelist_add_scalar(), cpl_imagelist_divide_scalar(), cpl_imagelist_dump_structure(), cpl_imagelist_dump_window(), cpl_imagelist_exponential(), cpl_imagelist_load_frameset(), cpl_imagelist_logarithm(), cpl_imagelist_multiply_scalar(), cpl_imagelist_normalise(), cpl_imagelist_power(), cpl_imagelist_subtract_scalar(), cpl_imagelist_threshold(), cpl_plot_image_col(), cpl_sprintf(), cpl_test_end(), cpl_vector_copy(), cpl_vector_fill_kernel_profile(), and cpl_wcs_platesol().

cpl_error_get_file()

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.

Referenced by cpl_error_get_where().

cpl_error_get_function()

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.

Referenced by cpl_error_get_where().

cpl_error_get_line()

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.

Referenced by cpl_error_get_where().

cpl_error_get_message()

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.

References cpl_error_get_message_default(), and CPL_ERROR_NONE.

cpl_error_get_message_default()

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

References CPL_ERROR_ACCESS_OUT_OF_RANGE, CPL_ERROR_ASSIGNING_STREAM, CPL_ERROR_BAD_FILE_FORMAT, CPL_ERROR_CONTINUE, CPL_ERROR_DATA_NOT_FOUND, CPL_ERROR_DIVISION_BY_ZERO, CPL_ERROR_DUPLICATING_STREAM, CPL_ERROR_EOL, CPL_ERROR_FILE_ALREADY_OPEN, CPL_ERROR_FILE_IO, CPL_ERROR_FILE_NOT_CREATED, CPL_ERROR_FILE_NOT_FOUND, CPL_ERROR_HISTORY_LOST, CPL_ERROR_ILLEGAL_INPUT, CPL_ERROR_ILLEGAL_OUTPUT, CPL_ERROR_INCOMPATIBLE_INPUT, CPL_ERROR_INVALID_TYPE, CPL_ERROR_NO_WCS, CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, CPL_ERROR_SINGULAR_MATRIX, CPL_ERROR_TYPE_MISMATCH, CPL_ERROR_UNSPECIFIED, and CPL_ERROR_UNSUPPORTED_MODE.

Referenced by cpl_error_get_message().

cpl_error_get_where()

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

References cpl_error_get_file(), cpl_error_get_function(), and cpl_error_get_line().