Loading...
Searching...
No Matches
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()

Referenced by cpl_apertures_extract(), cpl_apertures_extract_sigma(), cpl_apertures_extract_window(), cpl_apertures_get_bottom(), cpl_apertures_get_bottom_x(), cpl_apertures_get_centroid_x(), cpl_apertures_get_centroid_y(), cpl_apertures_get_flux(), cpl_apertures_get_fwhm(), cpl_apertures_get_left(), cpl_apertures_get_left_y(), cpl_apertures_get_max(), cpl_apertures_get_maxpos_x(), cpl_apertures_get_maxpos_y(), cpl_apertures_get_mean(), cpl_apertures_get_median(), cpl_apertures_get_min(), cpl_apertures_get_minpos_x(), cpl_apertures_get_minpos_y(), cpl_apertures_get_npix(), cpl_apertures_get_pos_x(), cpl_apertures_get_pos_y(), cpl_apertures_get_right(), cpl_apertures_get_right_y(), cpl_apertures_get_size(), cpl_apertures_get_stdev(), cpl_apertures_get_top(), cpl_apertures_get_top_x(), cpl_bivector_duplicate(), cpl_bivector_get_size(), cpl_bivector_get_x(), cpl_bivector_get_x_const(), cpl_bivector_get_x_data(), cpl_bivector_get_x_data_const(), cpl_bivector_get_y(), cpl_bivector_get_y_const(), cpl_bivector_get_y_data(), cpl_bivector_get_y_data_const(), cpl_bivector_new(), cpl_bivector_read(), cpl_bivector_wrap_vectors(), cpl_fit_imagelist_polynomial_window(), cpl_fits_count_extensions(), cpl_fits_find_extension(), cpl_frameset_extract(), cpl_frameset_labelise(), cpl_geom_img_offset_combine(), cpl_geom_img_offset_fine(), cpl_geom_img_offset_saa(), cpl_image_abs_create(), cpl_image_add_scalar_create(), cpl_image_average_create(), cpl_image_cast(), cpl_image_collapse_create(), cpl_image_collapse_median_create(), cpl_image_count_rejected(), cpl_image_divide_create(), cpl_image_divide_scalar_create(), cpl_image_duplicate(), cpl_image_exponential_create(), cpl_image_extract(), cpl_image_extract_subsample(), cpl_image_fill_test_create(), cpl_image_filter_linear(), cpl_image_filter_median(), cpl_image_filter_morpho(), cpl_image_filter_stdev(), cpl_image_get(), cpl_image_get_bpm(), cpl_image_get_bpm_const(), cpl_image_get_complex(), cpl_image_get_data(), cpl_image_get_data_const(), cpl_image_get_flux(), cpl_image_get_interpolated(), cpl_image_get_size_x(), cpl_image_get_size_y(), cpl_image_get_type(), cpl_image_iqe(), cpl_image_is_rejected(), cpl_image_labelise_mask_create(), cpl_image_logarithm_create(), cpl_image_multiply_scalar_create(), cpl_image_new_from_accepted(), cpl_image_new_from_mask(), cpl_image_normalise_create(), cpl_image_power_create(), cpl_image_rebin(), cpl_image_set_bpm(), cpl_image_subtract_scalar_create(), cpl_image_unset_bpm(), cpl_image_warp_polynomial(), cpl_image_wrap_double(), cpl_image_wrap_double_complex(), cpl_image_wrap_float(), cpl_image_wrap_float_complex(), cpl_image_wrap_int(), cpl_imagelist_collapse_create(), cpl_imagelist_collapse_median_create(), cpl_imagelist_collapse_minmax_create(), cpl_imagelist_collapse_sigclip_create(), cpl_imagelist_duplicate(), cpl_imagelist_get(), cpl_imagelist_get_const(), cpl_imagelist_get_size(), cpl_imagelist_is_uniform(), cpl_imagelist_load_frameset(), cpl_imagelist_swap_axis_create(), cpl_imagelist_unset(), cpl_mask_collapse_create(), cpl_mask_count(), cpl_mask_count_window(), cpl_mask_extract_subsample(), cpl_mask_get(), cpl_mask_get_data(), cpl_mask_get_data_const(), cpl_mask_get_size_x(), cpl_mask_get_size_y(), cpl_mask_new(), cpl_mask_wrap(), cpl_matrix_get_determinant(), cpl_matrix_invert_create(), cpl_matrix_product_create(), cpl_matrix_solve(), cpl_matrix_solve_normal(), cpl_matrix_solve_svd(), cpl_matrix_solve_svd_threshold(), cpl_multiframe_dataset_get_id(), cpl_multiframe_dataset_get_position(), cpl_polynomial_compare(), cpl_polynomial_duplicate(), cpl_polynomial_eval(), cpl_polynomial_eval_1d(), cpl_polynomial_eval_1d_diff(), cpl_polynomial_eval_2d(), cpl_polynomial_eval_3d(), cpl_polynomial_extract(), cpl_polynomial_get_coeff(), cpl_polynomial_get_degree(), cpl_polynomial_get_dimension(), cpl_sprintf(), cpl_stats_get_absflux(), cpl_stats_get_centroid_x(), cpl_stats_get_centroid_y(), cpl_stats_get_flux(), cpl_stats_get_mad(), cpl_stats_get_max(), cpl_stats_get_max_x(), cpl_stats_get_max_y(), cpl_stats_get_mean(), cpl_stats_get_median(), cpl_stats_get_median_dev(), cpl_stats_get_min(), cpl_stats_get_min_x(), cpl_stats_get_min_y(), cpl_stats_get_npix(), cpl_stats_get_sqflux(), cpl_stats_get_stdev(), cpl_stats_new_from_image(), cpl_vector_correlate(), cpl_vector_duplicate(), cpl_vector_extract(), cpl_vector_filter_lowpass_create(), cpl_vector_filter_median_create(), cpl_vector_find(), cpl_vector_get(), cpl_vector_get_data(), cpl_vector_get_data_const(), cpl_vector_get_maxpos(), cpl_vector_get_mean(), cpl_vector_get_median(), cpl_vector_get_median_const(), cpl_vector_get_minpos(), cpl_vector_get_size(), cpl_vector_get_stdev(), cpl_vector_get_sum(), cpl_vector_load(), cpl_vector_new_from_image_column(), cpl_vector_new_from_image_row(), cpl_vector_product(), cpl_vector_read(), cpl_vsprintf(), cpl_wcs_duplicate(), cpl_wcs_get_cd(), cpl_wcs_get_crpix(), cpl_wcs_get_crval(), cpl_wcs_get_ctype(), cpl_wcs_get_cunit(), cpl_wcs_get_image_dims(), cpl_wcs_get_image_naxis(), and cpl_wcs_new_from_propertylist().

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

Referenced by cpl_apertures_sort_by_flux(), cpl_apertures_sort_by_max(), cpl_apertures_sort_by_npix(), cpl_bivector_interpolate_linear(), cpl_bivector_sort(), cpl_detector_interpolate_rejected(), cpl_dfs_save_imagelist(), cpl_dfs_save_paf(), cpl_dfs_save_table(), cpl_dfs_setup_product_header(), cpl_dfs_sign_products(), cpl_fft_imagelist(), cpl_flux_get_noise_ring(), cpl_image_abs(), cpl_image_accept(), cpl_image_add_scalar(), cpl_image_and(), cpl_image_and_scalar(), cpl_image_conjugate(), cpl_image_copy(), cpl_image_divide(), cpl_image_divide_scalar(), cpl_image_dump_structure(), cpl_image_dump_window(), cpl_image_exponential(), cpl_image_fft(), cpl_image_fill_abs_arg(), cpl_image_fill_gaussian(), cpl_image_fill_noise_uniform(), cpl_image_fill_polynomial(), cpl_image_fill_re_im(), cpl_image_fill_rejected(), cpl_image_fill_window(), cpl_image_filter(), cpl_image_filter_mask(), cpl_image_fit_gaussian(), cpl_image_flip(), cpl_image_get_fwhm(), cpl_image_get_mad(), cpl_image_get_mad_window(), cpl_image_get_maxpos(), cpl_image_get_maxpos_window(), cpl_image_get_median_dev(), cpl_image_get_median_dev_window(), cpl_image_get_minpos(), cpl_image_get_minpos_window(), cpl_image_hypot(), cpl_image_logarithm(), cpl_image_move(), cpl_image_multiply(), cpl_image_multiply_scalar(), cpl_image_normalise(), cpl_image_not(), cpl_image_or(), cpl_image_or_scalar(), cpl_image_power(), cpl_image_reject(), cpl_image_reject_from_mask(), cpl_image_set(), cpl_image_set_complex(), cpl_image_shift(), cpl_image_subtract_scalar(), cpl_image_threshold(), cpl_image_turn(), cpl_image_warp(), cpl_image_warp_polynomial(), cpl_image_xor(), cpl_image_xor_scalar(), cpl_imagelist_add_scalar(), cpl_imagelist_divide_scalar(), cpl_imagelist_dump_structure(), cpl_imagelist_dump_window(), cpl_imagelist_erase(), cpl_imagelist_exponential(), cpl_imagelist_logarithm(), cpl_imagelist_multiply_scalar(), cpl_imagelist_normalise(), cpl_imagelist_power(), cpl_imagelist_save(), cpl_imagelist_set(), cpl_imagelist_subtract_scalar(), cpl_imagelist_threshold(), cpl_mask_and(), cpl_mask_copy(), cpl_mask_dump_window(), cpl_mask_filter(), cpl_mask_flip(), cpl_mask_move(), cpl_mask_not(), cpl_mask_or(), cpl_mask_save(), cpl_mask_set(), cpl_mask_shift(), cpl_mask_threshold_image(), cpl_mask_turn(), cpl_mask_xor(), cpl_matrix_decomp_chol(), cpl_matrix_solve_chol(), cpl_matrix_swap_rows(), cpl_multiframe_dataset_properties_remove(), cpl_multiframe_dataset_properties_update(), cpl_photom_fill_blackbody(), cpl_plot_bivectors(), cpl_plot_column(), cpl_plot_columns(), cpl_plot_image_col(), cpl_plot_image_row(), cpl_plot_vectors(), cpl_polynomial_add(), cpl_polynomial_copy(), cpl_polynomial_derivative(), cpl_polynomial_dump(), cpl_polynomial_fit(), cpl_polynomial_multiply(), cpl_polynomial_multiply_scalar(), cpl_polynomial_set_coeff(), cpl_polynomial_shift_1d(), cpl_polynomial_subtract(), cpl_propertylist_save(), cpl_stats_dump(), cpl_vector_add(), cpl_vector_add_scalar(), cpl_vector_convolve_symmetric(), cpl_vector_copy(), cpl_vector_cycle(), cpl_vector_divide(), cpl_vector_divide_scalar(), cpl_vector_exponential(), cpl_vector_fill(), cpl_vector_fill_kernel_profile(), cpl_vector_fill_polynomial(), cpl_vector_fill_polynomial_fit_residual(), cpl_vector_fit_gaussian(), cpl_vector_logarithm(), cpl_vector_multiply(), cpl_vector_multiply_scalar(), cpl_vector_power(), cpl_vector_save(), cpl_vector_set(), cpl_vector_set_size(), cpl_vector_sort(), cpl_vector_sqrt(), cpl_vector_subtract(), cpl_vector_subtract_scalar(), cpl_wcs_convert(), cpl_wcs_platesol(), cpl_wlcalib_fill_line_spectrum(), cpl_wlcalib_fill_line_spectrum_fast(), cpl_wlcalib_fill_logline_spectrum(), cpl_wlcalib_fill_logline_spectrum_fast(), cpl_wlcalib_find_best_1d(), cpl_wlcalib_slitmodel_set_catalog(), cpl_wlcalib_slitmodel_set_threshold(), cpl_wlcalib_slitmodel_set_wfwhm(), and cpl_wlcalib_slitmodel_set_wslit().

## 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_table_get_int
int cpl_table_get_int(const cpl_table *table, const char *name, cpl_size row, int *null)
Read a value from an integer column.
Definition cpl_table.c:5037

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

Referenced by cpl_array_get_type(), cpl_frame_get_nextensions(), cpl_imagelist_load_frameset(), cpl_parameter_disable(), cpl_parameter_duplicate(), cpl_parameter_enable(), cpl_parameter_get_alias(), cpl_parameter_get_bool(), cpl_parameter_get_class(), cpl_parameter_get_context(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_flag(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_enum_double(), cpl_parameter_get_enum_int(), cpl_parameter_get_enum_size(), cpl_parameter_get_enum_string(), cpl_parameter_get_help(), cpl_parameter_get_id(), cpl_parameter_get_int(), cpl_parameter_get_name(), cpl_parameter_get_range_max_double(), cpl_parameter_get_range_max_int(), cpl_parameter_get_range_min_double(), cpl_parameter_get_range_min_int(), cpl_parameter_get_string(), cpl_parameter_get_tag(), cpl_parameter_get_type(), cpl_parameter_is_enabled(), cpl_parameter_new_enum(), cpl_parameter_new_enum_from_array(), cpl_parameter_new_range(), cpl_parameter_new_value(), cpl_parameter_set_alias(), cpl_parameter_set_bool(), cpl_parameter_set_default_bool(), cpl_parameter_set_default_double(), cpl_parameter_set_default_int(), cpl_parameter_set_default_string(), cpl_parameter_set_double(), cpl_parameter_set_id(), cpl_parameter_set_int(), cpl_parameter_set_string(), cpl_parameter_set_tag(), cpl_ppm_match_points(), cpl_ppm_match_positions(), cpl_table_get_ncol(), cpl_table_get_nrow(), cpl_table_has_column(), and cpl_table_new().

## 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);
}
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 t...
Definition cpl_error.h:351
CPL_ERROR_NULL_INPUT
@ CPL_ERROR_NULL_INPUT
Definition cpl_error.h:420
if (error_string != NULL) {
return cpl_error_set_message(cpl_func, CPL_ERROR_ILLEGAL_INPUT,
"%s", error_string);
}
CPL_ERROR_ILLEGAL_INPUT
@ CPL_ERROR_ILLEGAL_INPUT
Definition cpl_error.h:424

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_code
enum _cpl_error_code_ cpl_error_code
The cpl_error_code type definition.
Definition cpl_error.h:453
cpl_sprintf
char * cpl_sprintf(const char *format,...)
Create a string and fill it in an sprintf()-like manner.
Definition cpl_memory.c:386
cpl_free
void cpl_free(void *memblk)
Memory block deallocation.
Definition cpl_memory.c:224

Referenced by cpl_multiframe_dataset_properties_update(), cpl_parameter_disable(), cpl_parameter_enable(), cpl_parameter_get_alias(), cpl_parameter_get_bool(), cpl_parameter_get_default_bool(), cpl_parameter_get_default_double(), cpl_parameter_get_default_int(), cpl_parameter_get_default_string(), cpl_parameter_get_double(), cpl_parameter_get_enum_double(), cpl_parameter_get_enum_int(), cpl_parameter_get_enum_size(), cpl_parameter_get_enum_string(), cpl_parameter_get_int(), cpl_parameter_get_range_max_double(), cpl_parameter_get_range_max_int(), cpl_parameter_get_range_min_double(), cpl_parameter_get_range_min_int(), cpl_parameter_get_string(), cpl_parameter_is_enabled(), cpl_parameter_new_enum(), cpl_parameter_new_enum_from_array(), cpl_parameter_new_range(), cpl_parameter_new_value(), cpl_parameter_set_alias(), cpl_parameter_set_bool(), cpl_parameter_set_default_bool(), cpl_parameter_set_default_double(), cpl_parameter_set_default_int(), cpl_parameter_set_default_string(), cpl_parameter_set_double(), cpl_parameter_set_int(), and cpl_parameter_set_string().

## 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_error_set_where
#define cpl_error_set_where(function)
Propagate a CPL-error to the current location.
Definition cpl_error.h:285

Referenced by cpl_frameset_find(), cpl_matrix_solve_svd(), cpl_matrix_solve_svd_threshold(), cpl_multiframe_append_datagroup(), cpl_multiframe_append_datagroup_from_position(), cpl_multiframe_append_dataset(), cpl_multiframe_append_dataset_from_position(), cpl_parameterlist_find(), cpl_parameterlist_find_context(), cpl_parameterlist_find_tag(), cpl_parameterlist_find_type(), cpl_parameterlist_get_first(), cpl_parameterlist_get_last(), and cpl_parameterlist_get_next().

## 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);
}
CPL_ERROR_EOL
@ CPL_ERROR_EOL
Definition cpl_error.h:442

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_propertylist_save(), 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().