Error

Macros | Typedefs | Functions | Variables
Error
Eina » Tools

This group discusses the functions that provide error management for projects. More...

## Macros
#define | EINA_ERROR_NO_ERROR ((Eina_Error)0)
| No error reported. More...

## Typedefs
typedef int | Eina_Error
| The integer type containing the error type. More...
typedef Eina_Bool | Eina_Success_Flag
| A flag indicating a function completed succesfully. More...

## Functions
EINA_API Eina_Error | eina_error_msg_register (const char *msg)
| Registers a new error type. More...
EINA_API Eina_Error | eina_error_msg_static_register (const char *msg)
| Registers a new error type, statically allocated message. More...
EINA_API Eina_Bool | eina_error_msg_modify (Eina_Error error, const char *msg)
| Changes the message of an already registered message. More...
EINA_API Eina_Error | eina_error_get (void)
| Returns the last set error. More...
EINA_API void | eina_error_set (Eina_Error err)
| Sets the last error. More...
EINA_API const char * | eina_error_msg_get (Eina_Error error)
| Returns the description of the given error number. More...
EINA_API Eina_Error | eina_error_find (const char *msg)
| Finds the Eina_Error corresponding to a message string. More...

## Variables
EINA_API Eina_Error EINA_ERROR_OUT_OF_MEMORY | EINA_DEPRECATED

## Detailed Description

This group discusses the functions that provide error management for projects.

The Eina error module provides a way to manage errors in a simple but powerful way in libraries and modules. It is also used in Eina itself. An extension to libC's `errno` and strerror() facilities, this is extensible and recommended for other libraries and applications as well.

While libC's `errno` is fixed, Eina_Error can be extended by libraries and applications with domain-specific codes and associated error messages. All `errno.h` codes are usable seamlessly with Eina_Error. The constants defined in errno.h will have messages as reported by strerror() in eina_error_msg_get()

Success (no-error) condition is reported with Eina_Error 0 (EINA_ERROR_NO_ERROR).

A simple example of how to use this can be seen here.

## Macro Definition Documentation

## ◆ EINA_ERROR_NO_ERROR

#define EINA_ERROR_NO_ERROR ((Eina_Error)0)

No error reported.

This is a convenience macro for people that are extra verbose, same as "0".

## Typedef Documentation

## ◆ Eina_Error

Eina_Error

The integer type containing the error type.

Errors are registered with eina_error_msg_register(), eina_error_msg_static_register() or those inherited from the system's `errno.h` such as `ENOMEM`.

## ◆ Eina_Success_Flag

Eina_Success_Flag

A flag indicating a function completed succesfully.

Errors are reported with a EINA_FALSE value for Eina_Success_Flag return and success with a EINA_TRUE.

## Function Documentation

## ◆ eina_error_msg_register()

EINA_API Eina_Error eina_error_msg_register | ( | const char * | msg | ) |

Registers a new error type.

This function stores the error message described by `msg` in a list. The returned value is a unique identifier greater than or equal to `1`. The description can be retrieved later by passing the returned value to eina_error_msg_get().

Parameters

  [in] | msg | The description of the error It is duplicated using eina_stringshare_add().

Returns
  The unique number identifier for this error

Note
  There is no need to register messages that exist in libC's `errno.h`, such as `ENOMEM` or `EBADF`.

See also
  eina_error_msg_static_register()

References EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), and EINA_TRUE.

Referenced by ecore_evas_init().

## ◆ eina_error_msg_static_register()

EINA_API Eina_Error eina_error_msg_static_register | ( | const char * | msg | ) |

Registers a new error type, statically allocated message.

This function stores the error message described by `msg` in a list. The returned value is a unique identifier greater than or equal to `1`. The description can be retrieved later by passing the returned value to eina_error_msg_get().

Parameters

  [in] | msg | The description of the error This string is not duplicated and thus the given pointer should live during the usage of eina_error.

Returns
  The unique number identifier for this error

Note
  There is no need to register messages that exist in libC's `errno.h`, such as `ENOMEM` or `EBADF`.

See also
  eina_error_msg_register()

References EINA_FALSE, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_init().

## ◆ eina_error_msg_modify()

EINA_API Eina_Bool eina_error_msg_modify | ( | Eina_Error | error,
|  | const char * | msg
| ) |  |

Changes the message of an already registered message.

This function modifies the message associated with `error` and changes it to `msg`. If the error is previously registered by eina_error_msg_static_register then the string is not duplicated, otherwise the previous message is unref'ed and `msg` is copied.

Parameters

  [in] | error | The Eina_Error to change the message of
  [in] | msg | The description of the error This string is duplicated only if the error is registered with eina_error_msg_register, otherwise it must remain intact for the duration.

Returns
  EINA_TRUE if successful, otherwise EINA_FALSE on error

Note
  It is not possible to modify messages that exist in libC's `errno.h`, such as `ENOMEM` or `EBADF`.

See also
  eina_error_msg_register()

References EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_stringshare_add(), eina_stringshare_del(), and EINA_TRUE.

## ◆ eina_error_get()

EINA_API Eina_Error eina_error_get | ( | void |  | ) |

Returns the last set error.

This function returns the last error set by eina_error_set(). The description of the message is returned by eina_error_msg_get().

Returns
  The last error or 0 (EINA_ERROR_NO_ERROR).

Note
  This function is thread safe

Since
  1.10, but slower to use.

References eina_main_loop_is(), and eina_tls_get().

Referenced by elm_photocam_file_set().

## ◆ eina_error_set()

EINA_API void eina_error_set | ( | Eina_Error | err | ) |

Sets the last error.

This function sets the last error identifier. The last error can be retrieved by eina_error_get().

Parameters

  [in] | err | The error identifier

Note
  This is also used to clear previous errors, in which case `err` should be `0` (EINA_ERROR_NO_ERROR).
  This function is thread safe

Since
  1.10, but slower to use.

References eina_main_loop_is(), and eina_tls_set().

Referenced by edje_edit_state_image_border_fill_set(), edje_edit_state_image_border_set(), edje_edit_state_image_set(), and edje_edit_state_vector_set().

## ◆ eina_error_msg_get()

EINA_API const char* eina_error_msg_get | ( | Eina_Error | error | ) |

Returns the description of the given error number.

This function returns the description of an error that has been registered by eina_error_msg_register(). If an incorrect error is given, then `NULL` is returned.

Parameters

  [in] | error | The error number

Returns
  The description of the error

References eina_hash_add(), eina_hash_find(), EINA_LOCK_SUCCEED, eina_spinlock_release(), eina_spinlock_take(), eina_stringshare_add(), and eina_strlcpy().

Referenced by ecore_con_client_send(), ecore_con_server_send(), and eina_promise_reject().

## ◆ eina_error_find()

EINA_API Eina_Error eina_error_find | ( | const char * | msg | ) |

Finds the Eina_Error corresponding to a message string.

This function attempts to match `msg` with its corresponding Eina_Error value. If no such value is found, `0` is returned.

Parameters

  [in] | msg | The error message string to match (NOT `NULL`)

Returns
  The Eina_Error matching `msg`, otherwise `0` on failure

Note
  this function only works for explicitly registered errors such as the messages given to eina_error_msg_register(), eina_error_msg_static_register() or modified with eina_error_msg_modify().

References EINA_SAFETY_ON_NULL_RETURN_VAL.