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 module. | |
EAPI int | eina_error_shutdown (void) |
Shut down the error module. | |
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 module.
- Returns:
- 1 or greater on success, 0 on error.
This function sets up the error module of Eina. It is called by eina_init() and by all modules initialization functions. It returns 0
on failure, otherwise it returns the number of times it is called.
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().
This function registers the error EINA_ERROR_OUT_OF_MEMORY.
Once the error module is not used anymore, then eina_error_shutdown() must be called to shut down the error module.
- See also:
- eina_init()
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_init(), eina_list_init(), eina_module_init(), and eina_stringshare_init().
EAPI int eina_error_shutdown | ( | void | ) |
Shut down the error module.
- Returns:
- 0 when the error module is completely shut down, 1 or greater otherwise.
This function shuts down the error module set up by eina_error_init(). It is called by eina_shutdown() and by all modules shutdown functions. It returns 0 when it is called the same number of times than eina_error_init(). In that case it clears the error list.
- See also:
- eina_shutdown()
Referenced by eina_array_init(), eina_array_shutdown(), eina_benchmark_init(), eina_benchmark_shutdown(), eina_convert_shutdown(), eina_counter_init(), eina_counter_shutdown(), eina_hash_shutdown(), eina_init(), eina_list_init(), eina_list_shutdown(), eina_module_shutdown(), eina_shutdown(), eina_stringshare_init(), 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.
This function stores in a list the error message described by 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.
This function returns the last error set by eina_error_set(). The description of the message is returned by eina_error_msg_get().
EAPI void eina_error_set | ( | Eina_Error | err | ) |
Set the last error.
- Parameters:
-
err The error identifier.
This function sets the last error identifier. The last error can be retrieved with eina_error_get().
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_init(), eina_counter_new(), eina_counter_start(), eina_hash_iterator_data_new(), eina_hash_iterator_key_new(), eina_hash_iterator_tuple_new(), eina_inlist_accessor_new(), eina_inlist_iterator_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.
This function returns the description of an error that has been registered with eina_error_msg_register(). If an incorrect error is given, then 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.
This function sends to a stream (like stdout or stderr) a formatted string that describes the error. The error level is set by 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.
This function is used to send a formatted error message to standard output and is used as a print callback, with eina_error_print(). This is the default print callback.
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.
This function is used to send a formatted error message to the stream specified by 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
This function sets the default print 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.
This function sets the error log level level
. It is used in eina_error_print().