Error
[Tools]
These functions provide error management for projects.
More...
Defines | |
#define | EINA_ERROR_PERR(fmt,...) eina_error_print(EINA_ERROR_LEVEL_ERR, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Print the error message described with the formatted string fmt using the current print callback, file function and line, with the error level EINA_ERROR_LEVEL_ERR. | |
#define | EINA_ERROR_PINFO(fmt,...) eina_error_print(EINA_ERROR_LEVEL_INFO, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Print the error message described with the formatted string fmt using the current print callback, file function and line, with the error level EINA_ERROR_LEVEL_INFO. | |
#define | EINA_ERROR_PWARN(fmt,...) eina_error_print(EINA_ERROR_LEVEL_WARN, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Print the error message described with the formatted string fmt using the current print callback, file function and line, with the error level EINA_ERROR_LEVEL_WARN. | |
#define | EINA_ERROR_PDBG(fmt,...) eina_error_print(EINA_ERROR_LEVEL_DBG, __FILE__, __FUNCTION__, __LINE__, fmt, ##__VA_ARGS__) |
Print the error message described with the formatted string fmt using the current print callback, file function and line, with the error level EINA_ERROR_LEVEL_DBG. | |
Typedefs | |
typedef enum _Eina_Error_Level | Eina_Error_Level |
List of available error levels. | |
typedef int | Eina_Error |
Error type. | |
typedef void(* | Eina_Error_Print_Cb )(Eina_Error_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Type for print callbacks. | |
Enumerations | |
enum | _Eina_Error_Level { EINA_ERROR_LEVEL_ERR, EINA_ERROR_LEVEL_WARN, EINA_ERROR_LEVEL_INFO, EINA_ERROR_LEVEL_DBG, EINA_ERROR_LEVELS } |
List of available error levels. More... | |
Functions | |
EAPI int | eina_error_init (void) |
Initialize the error system. | |
EAPI int | eina_error_shutdown (void) |
Shut down the error system. | |
EAPI Eina_Error | eina_error_msg_register (const char *msg) |
Register a new error type. | |
EAPI Eina_Error | eina_error_get (void) |
Return the last set error. | |
EAPI void | eina_error_set (Eina_Error err) |
Set the last error. | |
EAPI const char * | eina_error_msg_get (Eina_Error error) |
Return the description of the given an error number. | |
EAPI void | eina_error_print (Eina_Error_Level level, const char *file, const char *fnc, int line, const char *fmt,...) |
Print the error to a file. | |
EAPI void | EINA_PRINTF (5, 6) |
EAPI void | eina_error_vprint (Eina_Error_Level level, const char *file, const char *fnc, int line, const char *fmt, va_list args) EINA_ARG_NONNULL(2 |
EAPI void EAPI void | eina_error_print_cb_stdout (Eina_Error_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Print callback that sends the error message to stdout. | |
EAPI void | eina_error_print_cb_file (Eina_Error_Level level, const char *file, const char *fnc, int line, const char *fmt, void *data, va_list args) |
Print callback that sends the error message to a specified stream. | |
EAPI void | eina_error_print_cb_set (Eina_Error_Print_Cb cb, void *data) |
Set the default print callback. | |
EAPI void | eina_error_log_level_set (Eina_Error_Level level) |
Set the default error log level. | |
Variables | |
EAPI Eina_Error | EINA_ERROR_OUT_OF_MEMORY |
Error identifier corresponding to a lack of memory. |
Detailed Description
These functions provide error management for projects.The error system must be initialized with eina_error_init() and shut down with eina_error_shutdown(). The most generic way to print errors is to use eina_error_print() but the helper macros EINA_ERROR_PERR(), EINA_ERROR_PINFO(), EINA_ERROR_PWARN() and EINA_ERROR_PDBG() should be used instead.
Here is a straightforward example:
#include <stdlib.h> #include <stdio.h> #include <eina_error.h> void test_warn(void) { EINA_ERROR_PWARN("Here is a warning message\n"); } int main(void) { if (!eina_error_init()) { printf ("Error during the initialization of eina_error module\n"); return EXIT_FAILURE; } test_warn(); eina_error_shutdown(); return EXIT_SUCCESS; }
Compile this code with the following command:
gcc -Wall -o test_eina_error test_eina.c `pkg-config --cflags --libs eina`
If Eina is compiled without debug mode, then executing the resulting program displays nothing because the default error level is EINA_ERROR_LEVEL_ERR and we want to display a warning message, which level is strictly greater than the error level (see eina_error_print() for more informations). Now execute the program with:
EINA_ERROR_LEVEL=2 ./test_eina_error
You should see a message displayed in the terminal.
For more information, you can look at the Error Tutorial.
Enumeration Type Documentation
enum _Eina_Error_Level |
Function Documentation
EAPI int eina_error_init | ( | void | ) |
Initialize the error system.
- Returns:
- 1 or greater on success, 0 on error.
The default error level value is set by default to EINA_ERROR_LEVEL_DBG if Eina is compiled with debug mode, or to EINA_ERROR_LEVEL_ERR otherwise. That value can be overwritten by setting the environment variable EINA_ERROR_LEVEL. This function checks the value of that environment variable in the first call. Its value must be a number between 0 and 3, to match the error levels EINA_ERROR_LEVEL_ERR, EINA_ERROR_LEVEL_WARN, EINA_ERROR_LEVEL_INFO and EINA_ERROR_LEVEL_DBG. That value can also be set later with eina_error_log_level_set().
If you call explicitly this function and once the error subsystem is not used anymore, then eina_error_shutdown() must be called to shut down the error system.
References eina_error_msg_register(), and EINA_ERROR_OUT_OF_MEMORY.
Referenced by eina_array_init(), eina_benchmark_init(), eina_convert_init(), eina_counter_init(), eina_hash_init(), eina_list_init(), eina_module_init(), and eina_stringshare_init().
EAPI int eina_error_shutdown | ( | void | ) |
Shut down the error system.
- Returns:
- 0 when the error system is completely shut down, 1 or greater otherwise.
Referenced by eina_array_shutdown(), eina_benchmark_shutdown(), eina_convert_shutdown(), eina_counter_shutdown(), eina_hash_shutdown(), eina_list_shutdown(), eina_module_shutdown(), and eina_stringshare_shutdown().
EAPI Eina_Error eina_error_msg_register | ( | const char * | msg | ) |
Register a new error type.
- Parameters:
-
msg The description of the error.
- Returns:
- The unique number identifier for this error.
msg
. The returned value is a unique identifier greater or equal than 1. The description can be retrieve later by passing to eina_error_msg_get() the returned value.
References eina_inlist_append().
Referenced by eina_convert_init(), eina_counter_init(), eina_error_init(), and eina_module_init().
EAPI Eina_Error eina_error_get | ( | void | ) |
Return the last set error.
- Returns:
- The last error.
EAPI void eina_error_set | ( | Eina_Error | err | ) |
Set the last error.
- Parameters:
-
err The error identifier.
Referenced by eina_array_accessor_new(), eina_array_iterator_new(), eina_array_new(), eina_array_remove(), eina_benchmark_new(), eina_benchmark_register(), eina_convert_atod(), eina_counter_add(), eina_counter_start(), eina_hash_iterator_data_new(), eina_hash_iterator_key_new(), eina_hash_iterator_tuple_new(), eina_list_accessor_new(), eina_list_append(), eina_list_append_relative_list(), eina_list_iterator_new(), eina_list_iterator_reversed_new(), eina_list_prepend(), eina_list_prepend_relative_list(), and eina_module_load().
EAPI const char * eina_error_msg_get | ( | Eina_Error | error | ) |
Return the description of the given an error number.
- Parameters:
-
error The error number.
- Returns:
- The description of the error.
NULL
is returned.
EAPI void eina_error_print | ( | Eina_Error_Level | level, | |
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
... | ||||
) |
Print the error to a file.
- Parameters:
-
level The error level. file The name of the file where the error occurred. fnc The name of the function where the error occurred. line The number of the line where the error occurred. fmt The format to use.
level
, the name of the file, of the function and the number of the line where the error occurred are respectively set by file
, fnc
and line
. A description of the error message is given by fmt
, which is a formatted string, followed by optional arguments that can be converted (like with printf). If level
is strictly larger than the current error level, that function returns immediately, otherwise it prints all the errors up to the current error level. The current error level can be changed with eina_error_log_level_set(). See also eina_error_init() for more informations.By default, that formatted message is send to stdout and is formatted by eina_error_print_cb_stdout(). The destination of the formatted message is send and the way it is formatted can be changed by setting a print callback with eina_error_print_cb_set(). Some print callbacks are already defined: eina_error_print_cb_stdout() that send the message to stdout and eina_error_print_cb_file() that sends it to a file, but custom print callbacks can be used. They must be of type Eina_Error_Print_Cb.
EAPI void eina_error_print_cb_stdout | ( | Eina_Error_Level | level, | |
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
void * | data, | |||
va_list | args | |||
) |
Print callback that sends the error message to stdout.
- Parameters:
-
level The error level. file The name of the file where the error occurred. fnc The name of the function where the error occurred. line The number of the line where the error occurred. fmt The format to use. data Unused. args The arguments that will be converted.
References EINA_ERROR_LEVEL_INFO.
EAPI void eina_error_print_cb_file | ( | Eina_Error_Level | level, | |
const char * | file, | |||
const char * | fnc, | |||
int | line, | |||
const char * | fmt, | |||
void * | data, | |||
va_list | args | |||
) |
Print callback that sends the error message to a specified stream.
- Parameters:
-
level Unused. file The name of the file where the error occurred. fnc The name of the function where the error occurred. line The number of the line where the error occurred. fmt The format to use. data The file stream. args The arguments that will be converted.
data
. That stream must be of type FILE *. Look at eina_error_print_cb_stdout() for the description of the other parameters. Use eina_error_print_cb_set() to set it as default print callback in eina_error_print().
EAPI void eina_error_print_cb_set | ( | Eina_Error_Print_Cb | cb, | |
void * | data | |||
) |
Set the default print callback.
- Parameters:
-
cb The print callback. data The data to pass to the callback
cb
used by eina_error_print(). A data can be passed to that callback with data
.
EAPI void eina_error_log_level_set | ( | Eina_Error_Level | level | ) |
Set the default error log level.
- Parameters:
-
level The error level.
level
. It is used in eina_error_print().