Error Functions

These functions provide error management for porjects. 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_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 porjects.

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 commant:

 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

List of available error levels.

Enumerator:

EINA_ERROR_LEVEL_ERR	Error error level.
EINA_ERROR_LEVEL_WARN	Warning error level.
EINA_ERROR_LEVEL_INFO	Information error level.
EINA_ERROR_LEVEL_DBG	Debug error level.
EINA_ERROR_LEVELS	Count of error level.

Function Documentation

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

EAPI int eina_error_init ( void )

Initialize the error system.

Returns:: 1 or greater on success, 0 on error.

This function sets up the error system or Eina. It is called by eina_init() and by all subsystems 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().

If you call explicitely 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_hash_init(), eina_list_init(), and eina_stringshare_init().

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

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.

References eina_list_nth().

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 retrive later by passing to eina_error_msg_get() the returned value.

References eina_list_append().

Referenced by eina_error_init().

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 immediatly, 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_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_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_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_hash_add_by_hash(), eina_hash_direct_add_by_hash(), eina_list_append(), and eina_list_prepend().

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.

This function shut down the error system set up by eina_error_init(). It is called by eina_shutdown() and by all subsystems shutdown functions. It returns 0 when it is called the same number of times than eina_error_init() and it clears the error list.

References eina_list_free().

Referenced by eina_hash_shutdown(), eina_list_shutdown(), and eina_stringshare_shutdown().

Error Functions

Defines

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation