Error management module for DBALLE. More...
Go to the source code of this file.
Defines | |
#define | DBA_RUN_OR_RETURN(...) |
Run the given function, checking the dba_err result value. | |
#define | DBA_RUN_OR_GOTO(label,...) |
Run the given function, checking the dba_err result value. | |
#define | DBA_FAIL_RETURN(...) |
Return the error error. | |
#define | DBA_FAIL_GOTO(label,...) |
Report the error error by jumping to a label instead of returning. | |
#define | dba_error_notfound(fmt,...) dba_error_generic1(DBA_ERR_NOTFOUND, fmt , ## __VA_ARGS__) |
Reports that a search-like function could not find what was requested. | |
#define | dba_error_type(fmt,...) dba_error_generic1(DBA_ERR_TYPE, fmt , ## __VA_ARGS__) |
For functions handling data with multiple types, reports a mismatch between the type requested and the type found. | |
#define | dba_error_handles(fmt,...) dba_error_generic1(DBA_ERR_HANDLES, fmt , ## __VA_ARGS__) |
For functions working with handles, reports a problem with handling handles, such as impossibility to allocate a new one, or an invalid handle being passed to the function. | |
#define | dba_error_toolong(fmt,...) dba_error_generic1(DBA_ERR_TOOLONG, fmt , ## __VA_ARGS__) |
Report an error with a buffer being to short for the data it needs to fit. | |
#define | dba_error_consistency(fmt,...) dba_error_generic1(DBA_ERR_CONSISTENCY, fmt , ## __VA_ARGS__) |
Report an error when a consistency check failed. | |
#define | dba_error_unimplemented(fmt,...) dba_error_generic1(DBA_ERR_UNIMPLEMENTED, fmt , ## __VA_ARGS__) |
Reports that a feature is still not implemented. | |
Typedefs | |
typedef enum _dba_err | dba_err |
typedef void(* | dba_err_callback )(void *data) |
Type of the callback function that can be registered to be invoked when some error happens. | |
typedef struct _dba_error_info * | dba_error_info |
Opaque structure that is used to save all the error reporting informations, to be restored later. | |
Enumerations | |
enum | _dba_err { DBA_OK = 0, DBA_ERROR = 1 } |
Return value used to denote success or failure for a function. More... | |
enum | dba_err_code { DBA_ERR_NONE = 0, DBA_ERR_NOTFOUND = 1, DBA_ERR_TYPE = 2, DBA_ERR_ALLOC = 3, DBA_ERR_ODBC = 4, DBA_ERR_HANDLES = 5, DBA_ERR_TOOLONG = 6, DBA_ERR_SYSTEM = 7, DBA_ERR_CONSISTENCY = 8, DBA_ERR_PARSE = 9, DBA_ERR_WRITE = 10, DBA_ERR_REGEX = 11, DBA_ERR_UNIMPLEMENTED = 12 } |
Error code identifying a type of error. More... | |
Functions | |
dba_err | dba_error_generic0 (dba_err_code code, char *context, char *extended_message) |
Set a generic message. | |
dba_err | dba_error_generic1 (dba_err_code code, const char *fmt,...) |
Set a generic message. | |
dba_err | dba_error_ok () |
Reports the success of a function. | |
dba_err | dba_error_alloc (const char *message) |
Reports that memory allocation has failed. | |
dba_err | dba_error_system (const char *fmt,...) |
Report a system error message. | |
dba_err | dba_error_parse (const char *file, int line, const char *fmt,...) |
Report an error when parsing informations. | |
dba_err | dba_error_regexp (int code, void *re, const char *fmt,...) |
Report an error while handling regular expressions. | |
dba_err_code | dba_error_get_code () |
Get the error code for the last error. | |
const char * | dba_error_get_message () |
Get the error message for the last error. | |
const char * | dba_error_get_context () |
Get the description of the context in which the last error happened. | |
const char * | dba_error_get_details () |
Get the details about the last error happening. | |
const char * | dba_error_get_backtrace () |
Get the stack backtrace at the time the last error happened. | |
void | dba_error_set_callback (dba_err_code code, dba_err_callback cb, void *data) |
Set a callback to be invoked when an error of a specific kind happens. | |
void | dba_error_remove_callback (dba_err_code code, dba_err_callback cb, void *data) |
Removes a callback that has been set previously. | |
void | dba_error_state_get (dba_error_info *info) |
Save all error informations inside info, to be restored later with dba_error_state_set. | |
void | dba_error_state_set (dba_error_info info) |
Restore saved error informations. | |
void | dba_error_state_delete (dba_error_info *info) |
Deallocate a dba_error_info. | |
void | dba_error_print_to_stderr () |
Convenience function to output the current error status to standard error. |
Error management module for DBALLE.
These functions, implement the error-handling framework used throrough all DB-ALLe. It allows to have a uniform way and uniform expectations on the way functions report, detect and handle errors.
All functions in DB-ALLe that can fail return a value of type 'dba_err'. This value can be used to check if the function succeeded or not. If a function does not return a value of dba_err, then it cannot fail: this allows to know the error behaviour of the function by just looking at its return value.
In case the function failed, there are four functions that can be used to understand what happened: dba_error_get_code(), dba_error_get_message(), dba_error_get_context() and dba_error_get_details().
A callback can also be set to be invoked when errors happen. It can be set to be triggered only on a specific kind of error or on all errors.
This is a simple invocation of a function that can fail:
if (dba_enqi(rec, 1234, &value))
handle_errors(...);
This is a function that can print all possible details about an error:
const char* details = dba_error_get_details(); fprintf(stderr, "Error %d (%s) while %s", dba_error_get_code(), dba_error_get_message(), dba_error_get_context()); if (details == NULL) fputc('\n', stderr); else fprintf(stderr, ". Details:\n%s\n", details);
These are examples of setting callbacks:
void count(void* data) { ++(*(int*)data); } void alloc_fail(void*) { fprintf(stderr, "Memory exausted while %s: shutting down.\n", dba_error_get_context()); emergency_shutdown(); } int main(int argc, char* argv[]) { int error_counter = 0; ... dba_error_set_callback(DBA_ERR_NONE, count, &error_counter); dba_error_set_callback(DBA_ERR_ALLOC, alloc_fail, NULL); ... // We are not interested in counting errors anymore dba_error_remove_callback(DBA_ERR_NONE, count, &error_counter); ... }
Convenience macros are provided to implement trivial error-handling strategies: see DBA_RUN_OR_RETURN, DBA_RUN_OR_GOTO, DBA_FAIL_RETURN, DBA_FAIL_GOTO.
When writing library code, these are the rules to keep in mind about error handling:
#define dba_error_consistency | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_CONSISTENCY, fmt , ## __VA_ARGS__) |
Report an error when a consistency check failed.
fmt | printf-style format string used to build the context informations for this error |
Referenced by aof_codec_fix_header(), bufr_encoder_encode(), bufrex_encode_bufr(), bufrex_encode_crex(), bufrex_msg_decode(), bufrex_msg_decode_header(), bufrex_msg_encode(), bufrex_msg_from_dba_msgs(), bufrex_msg_generate_datadesc(), bufrex_msg_load_tables(), bufrex_msg_parse_template(), bufrex_subset_add_attr(), bufrex_subset_add_attrs(), crex_encoder_encode(), dba_convert_BUFR20003_to_WMO4677(), dba_convert_BUFR20004_to_WMO4561(), dba_convert_WMO4561_to_BUFR20004(), dba_convert_WMO4677_to_BUFR20003(), dba_db_create_from_url(), dba_db_insert(), dba_db_qc_query(), dba_db_qc_remove(), dba_db_repinfo_update(), dba_file_create(), dba_import_msg(), dba_querybuf_append(), dba_querybuf_append_listf(), dba_querybuf_appendf(), dba_querybuf_create(), dba_record_parse_date_extremes(), and dba_record_set_from_string().
#define dba_error_handles | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_HANDLES, fmt , ## __VA_ARGS__) |
For functions working with handles, reports a problem with handling handles, such as impossibility to allocate a new one, or an invalid handle being passed to the function.
fmt | printf-style format string used to build the context informations for this error |
#define dba_error_notfound | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_NOTFOUND, fmt , ## __VA_ARGS__) |
Reports that a search-like function could not find what was requested.
fmt | printf-style format string used to build the context informations for this error |
Referenced by bufrex_dtable_query(), dba_convert_BUFR20012_to_WMO0500(), dba_convert_BUFR20012_to_WMO0509(), dba_convert_BUFR20012_to_WMO0513(), dba_convert_BUFR20012_to_WMO0515(), dba_convert_units(), dba_convert_units_get_mul(), dba_convert_WMO0500_to_BUFR20012(), dba_convert_WMO0509_to_BUFR20012(), dba_convert_WMO0513_to_BUFR20012(), dba_convert_WMO0515_to_BUFR20012(), dba_db_context_get_data(), dba_db_pseudoana_get_data(), dba_db_rep_memo_from_cod(), dba_db_repinfo_get_id(), dba_db_seq_read(), dba_file_create(), dba_import_msg(), dba_record_contains(), dba_record_contains_key(), dba_record_enq(), dba_record_key_set(), dba_record_key_setc(), dba_record_key_setd(), dba_record_key_seti(), dba_record_key_unset(), dba_record_keyword_info(), dba_record_set_from_string(), dba_var_enqc(), dba_var_enqd(), dba_var_enqi(), and dba_vartable_query().
#define dba_error_toolong | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_TOOLONG, fmt , ## __VA_ARGS__) |
Report an error with a buffer being to short for the data it needs to fit.
fmt | printf-style format string used to build the context informations for this error |
Referenced by dba_var_setc(), dba_var_setd(), and dba_var_seti().
#define dba_error_type | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_TYPE, fmt , ## __VA_ARGS__) |
For functions handling data with multiple types, reports a mismatch between the type requested and the type found.
fmt | printf-style format string used to build the context informations for this error |
Referenced by dba_var_enqd(), dba_var_enqi(), dba_var_setd(), and dba_var_seti().
#define dba_error_unimplemented | ( | fmt, | |
... | |||
) | dba_error_generic1(DBA_ERR_UNIMPLEMENTED, fmt , ## __VA_ARGS__) |
Reports that a feature is still not implemented.
fmt | printf-style format string used to build the context informations for this error |
Referenced by bufrex_msg_generate_datadesc(), dba_convert_press_to_icao(), dba_db_cursor_query(), dba_file_create(), dba_file_read(), dba_file_write(), dba_file_write_msgs(), dba_marshal_encode(), dba_msg_context_lua_check(), dba_msg_context_lua_push(), dba_msg_lua_check(), dba_msg_lua_push(), and dba_var_lua_push().
#define DBA_FAIL_GOTO | ( | label, | |
... | |||
) |
do { \ err = __VA_ARGS__; \ goto label; \ } while (0)
Report the error error by jumping to a label instead of returning.
Example:
if (idx > max) DBA_FAIL_GOTO(cleanup, dba_error_notfound, "looking for item %s", name);
#define DBA_FAIL_RETURN | ( | ... ) |
do { \ return __VA_ARGS__; \ } while (0)
Return the error error.
Example:
if (idx > max) DBA_FAIL_RETURN(dba_error_notfound, "looking for item %s", name);
#define DBA_RUN_OR_GOTO | ( | label, | |
... | |||
) |
do { \ err = __VA_ARGS__; \ if (err != DBA_OK) \ goto label; \ } while (0)
Run the given function, checking the dba_err result value.
If the function failed, then goto the given label
This is used to perform some cleanup before returning the error.
Example:
// Special cleanup on failure dba_err example(dba_var* result) { dba_err err; dba_var var; // A temporary variable is needed DBA_RUN_OR_RETURN(dba_var_create_local(DBA_VAR(0, 1, 2), &var)); DBA_RUN_OR_GOTO(fail, dba_var_setd(var, compute_some_value())); *result = var; return dba_error_ok(); fail: dba_var_delete(var); return err; } // Cleanup is needed in case of both success and failure dba_err example() { dba_err err = DBA_OK; dba_var var = NULL; // perform some computation... DBA_RUN_OR_GOTO(cleanup, dba_var_create_local(DBA_VAR(0, 1, 2), &var)); DBA_RUN_OR_GOTO(cleanup, dba_var_setd(var, compute_some_value())); cleanup: if (var != NULL) dba_var_delete(var); return err == DBA_OK ? dba_error_ok() : err; }
Referenced by aof_codec_decode(), aof_codec_fix_header(), aof_codec_read_header(), bufr_decoder_decode(), bufr_decoder_decode_header(), bufr_encoder_encode(), bufrex_decode_bufr(), bufrex_decode_crex(), bufrex_encode_bufr(), bufrex_encode_crex(), bufrex_msg_encode(), bufrex_msg_to_dba_msgs(), crex_decoder_decode(), crex_decoder_decode_header(), crex_encoder_encode(), dba_db_ana_query(), dba_db_attr_create(), dba_db_attr_load(), dba_db_context_create(), dba_db_create(), dba_db_create_generic(), dba_db_cursor_create(), dba_db_data_create(), dba_db_delete_tables(), dba_db_drop_table_if_exists(), dba_db_export(), dba_db_insert(), dba_db_pseudoana_create(), dba_db_qc_insert_or_replace(), dba_db_qc_query(), dba_db_query(), dba_db_remove(), dba_db_remove_orphans(), dba_db_repinfo_create(), dba_db_repinfo_update(), dba_db_reset(), dba_db_run_sql(), dba_db_seq_create(), dba_file_create(), dba_file_read_msgs(), dba_file_write_msgs(), dba_formatter_describe_level_or_layer(), dba_import_msg(), dba_msg_context_copy(), dba_msg_filter_copy(), dba_msg_set(), dba_msg_set_by_id(), dba_msg_set_nocopy(), dba_msg_setc(), dba_msg_setd(), dba_msg_seti(), dba_msg_sounding_pack_levels(), dba_msg_sounding_unpack_levels(), dba_rawmsg_copy(), dba_record_var_set(), dba_record_var_setc(), dba_record_var_setd(), dba_record_var_seti(), dba_var_convert(), dba_var_copy(), dba_var_copy_val(), dba_var_createc(), dba_var_created(), dba_var_createi(), and dba_var_seta().
#define DBA_RUN_OR_RETURN | ( | ... ) |
do { \ dba_err err = __VA_ARGS__; \ if (err != DBA_OK) \ return err; \ } while (0)
Run the given function, checking the dba_err result value.
If the function failed, then execute a "return" with that value.
Referenced by aof_codec_decode(), aof_codec_get_category(), aof_codec_write_dummy_header(), aof_codec_write_record(), bufr_encoder_encode(), bufrex_dtable_create(), bufrex_msg_append_datadesc(), bufrex_msg_encode(), bufrex_msg_from_dba_msg(), bufrex_msg_from_dba_msgs(), bufrex_msg_generate_datadesc(), bufrex_msg_get_subset(), bufrex_msg_load_tables(), bufrex_opcode_pop_n(), bufrex_subset_append_attrs(), bufrex_subset_append_dpb(), bufrex_subset_append_fixed_attrs(), bufrex_subset_append_fixed_dpb(), bufrex_subset_apply_attributes(), bufrex_subset_store_variable_c(), bufrex_subset_store_variable_d(), bufrex_subset_store_variable_i(), bufrex_subset_store_variable_undef(), bufrex_subset_store_variable_var(), crex_encoder_encode(), dba_db_ana_query(), dba_db_check_rep_cod(), dba_db_context_insert(), dba_db_context_obtain_ana(), dba_db_cursor_query(), dba_db_cursor_to_record(), dba_db_data_insert_or_ignore(), dba_db_export(), dba_db_insert(), dba_db_pseudoana_insert(), dba_db_qc_insert_or_replace(), dba_db_qc_query(), dba_db_qc_remove(), dba_db_query(), dba_db_remove(), dba_db_rep_cod_from_memo(), dba_db_rep_memo_from_cod(), dba_db_repinfo_get_id(), dba_db_repinfo_update(), dba_db_update_repinfo(), dba_file_read(), dba_file_read_msgs(), dba_file_write(), dba_import_msg(), dba_import_msgs(), dba_marshal_decode(), dba_marshal_encode(), dba_msg_context_copy(), dba_msg_context_set_nocopy(), dba_msg_filter_copy(), dba_msg_set(), dba_msg_set_by_id(), dba_msg_set_nocopy(), dba_msg_setc(), dba_msg_setd(), dba_msg_seti(), dba_msg_sounding_pack_levels(), dba_msg_sounding_unpack_levels(), dba_querybuf_append_list(), dba_querybuf_append_listf(), dba_record_add(), dba_record_copy(), dba_record_difference(), dba_record_enq(), dba_record_enqc(), dba_record_enqd(), dba_record_enqi(), dba_record_key_enq(), dba_record_key_enqc(), dba_record_key_enqd(), dba_record_key_enqi(), dba_record_key_set(), dba_record_set_ana_context(), dba_record_set_from_string(), dba_record_var_enq(), dba_record_var_enqc(), dba_record_var_enqd(), dba_record_var_enqi(), dba_record_var_set_direct(), dba_record_var_setc(), dba_record_var_setd(), dba_record_var_seti(), dba_var_convert(), dba_var_copy(), dba_var_copy_attrs(), dba_var_create_local(), dba_var_createc(), dba_var_created(), dba_var_createi(), dba_var_seta(), dba_var_setc(), dba_var_setd(), dba_var_seti(), dba_varinfo_get_local_table(), dba_varinfo_query_local(), dba_varinfo_query_local_altered(), dba_vartable_create(), and dba_vartable_query_altered().
Return value used to denote success or failure for a function.
It is guaranteed to evaluate to false to indicate success (absence of errors), or to true to indicate failure (presence of errors).
enum _dba_err |
Return value used to denote success or failure for a function.
It is guaranteed to evaluate to false to indicate success (absence of errors), or to true to indicate failure (presence of errors).
enum dba_err_code |
Error code identifying a type of error.
It can be used by code to implement special handling for some kind of errors.
dba_err dba_error_alloc | ( | const char * | message ) |
dba_err dba_error_generic0 | ( | dba_err_code | code, |
char * | context, | ||
char * | extended_message | ||
) |
Set a generic message.
To be used by other modules to implement their own error functions.
code | The error code for this error |
context | The context description for this error. It can be NULL. If it is non-NULL, then it will be deallocated by the dba_error module. |
extended_message | The extended message for this error. It can be NULL. If it is non-NULL, then it will be deallocated by the dba_error module. |
dba_err dba_error_generic1 | ( | dba_err_code | code, |
const char * | fmt, | ||
... | |||
) |
Set a generic message.
To be used by other modules to implement their own error functions.
code | The error code for this error |
fmt | printf-style format string used to build the context informations for this error |
const char* dba_error_get_backtrace | ( | ) |
Get the stack backtrace at the time the last error happened.
dba_err_code dba_error_get_code | ( | ) |
Get the error code for the last error.
const char* dba_error_get_context | ( | ) |
Get the description of the context in which the last error happened.
const char* dba_error_get_details | ( | ) |
Get the details about the last error happening.
This is used in those cases in which it is possible to find out various kinds of detailed informations about an error.
const char* dba_error_get_message | ( | ) |
Get the error message for the last error.
dba_err dba_error_ok | ( | ) |
dba_err dba_error_parse | ( | const char * | file, |
int | line, | ||
const char * | fmt, | ||
... | |||
) |
Report an error when parsing informations.
file | The file that is being parsed |
line | The line of the file where the problem has been found |
fmt | printf-style format string used to build the context informations for this error |
References DBA_ERR_PARSE.
dba_err dba_error_regexp | ( | int | code, |
void * | re, | ||
const char * | fmt, | ||
... | |||
) |
Report an error while handling regular expressions.
code | The error code returned by the regular expression functions. |
re | The pointer to the regex_t structure that was being used when the error occurred. |
fmt | printf-style format string used to build the context informations for this error |
References DBA_ERR_REGEX.
void dba_error_remove_callback | ( | dba_err_code | code, |
dba_err_callback | cb, | ||
void * | data | ||
) |
Removes a callback that has been set previously.
The same values of code, cb and data given when setting the callback must be provided for the callback to be identified.
code | The 'code' parameter used when setting the callback to be deleted. |
cb | The 'cb' parameter used when setting the callback to be deleted. |
data | The 'data' parameter used when setting the callback to be deleted. |
void dba_error_set_callback | ( | dba_err_code | code, |
dba_err_callback | cb, | ||
void * | data | ||
) |
Set a callback to be invoked when an error of a specific kind happens.
code | The error code (See dba_err_code) of the error that triggers this callback. If DBA_ERR_NONE is used, then the callback is invoked on all errors. |
cb | The function to be called. |
data | An arbitrary data that is passed verbatim to the callback function when invoked. |
void dba_error_state_get | ( | dba_error_info * | info ) |
Save all error informations inside info, to be restored later with dba_error_state_set.
info | The dba_error_info where the informations will be saved. If info points to NULL, it will be allocated, else it will be considered as an old dba_error_info to reuse. In both cases, it will need to be deallocated with dba_error_state_delete. |
void dba_error_state_set | ( | dba_error_info | info ) |
Restore saved error informations.
info | The dba_error_info where the state was previously saved by dba_error_state_get |
dba_err dba_error_system | ( | const char * | fmt, |
... | |||
) |
Report a system error message.
The message description will be looked up using the current value of errno.
fmt | printf-style format string used to build the context informations for this error |
References DBA_ERR_SYSTEM.