Magic
[Tools]

These functions provide magic checks management for projects. More...

Defines

#define EINA_MAGIC_NONE   0x1234fedc
 Random value for specifying that a structure using the magic feature has already been freed.

Typedefs

typedef unsigned int Eina_Magic
 An abstract type for a magic number.

Functions

EAPI const char * eina_magic_string_get (Eina_Magic magic)
 Return the string associated to the given magic identifier.
EAPI Eina_Bool eina_magic_string_set (Eina_Magic magic, const char *magic_name)
 Set the string associated to the given magic identifier.
EAPI Eina_Bool eina_magic_string_static_set (Eina_Magic magic, const char *magic_name)
 Set the string associated to the given magic identifier.
Eina_Bool eina_magic_string_init (void)
Eina_Bool eina_magic_string_shutdown (void)
EAPI void eina_magic_fail (void *d, Eina_Magic m, Eina_Magic req_m, const char *file, const char *fnc, int line)
 Display a message or abort is a magic check failed.

Detailed Description

These functions provide magic checks management for projects.


Define Documentation

#define EINA_MAGIC_NONE   0x1234fedc

Random value for specifying that a structure using the magic feature has already been freed.

It is used by eina_agic_fail().

If the magic feature of Eina is disabled, EINA_MAGIC_NONE is just 0.


Function Documentation

EAPI const char * eina_magic_string_get ( Eina_Magic  magic  ) 

Return the string associated to the given magic identifier.

Parameters:
magic The magic identifier.
Returns:
The string associated to the identifier.

This function returns the string associated to magic. If none are found, the this function returns NULL. The returned value must not be freed.

EAPI Eina_Bool eina_magic_string_set ( Eina_Magic  magic,
const char *  magic_name 
)

Set the string associated to the given magic identifier.

Parameters:
magic The magic identifier.
The string associated to the identifier, must not be NULL.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.

This function sets the string magic_name to magic. It is not checked if number or string are already set, then you might end with duplicates in that case.

See also:
eina_magic_string_static_set()
EAPI Eina_Bool eina_magic_string_static_set ( Eina_Magic  magic,
const char *  magic_name 
)

Set the string associated to the given magic identifier.

Parameters:
magic The magic identifier.
The string associated to the identifier, must not be NULL, it will not be duplcated, just referenced thus it must be live during magic number usage.
Returns:
EINA_TRUE on success, EINA_FALSE on failure.

This function sets the string magic_name to magic. It is not checked if number or string are already set, then you might end with duplicates in that case.

See also:
eina_magic_string_set()
EAPI void eina_magic_fail ( void *  d,
Eina_Magic  m,
Eina_Magic  req_m,
const char *  file,
const char *  fnc,
int  line 
)

Display a message or abort is a magic check failed.

Parameters:
d The checked data pointer.
m The magic identifer to check.
req_m The requested magic identifier to check.
file The file in which the magic check failed.
fcn The function in which the magic check failed.
line The line at which the magic check failed.

This function displays an error message if a magic check has failed, using the following logic in the following order:

  • If d is NULL, a message warns about a NULL pointer.
  • Otherwise, if m is equal to EINA_MAGIC_NONE, a message warns about a handle that was already freed.
  • Otherwise, if m is equal to req_m, a message warns about a handle that is of wrong type.
  • Otherwise, a message warns you about ab-using that function...

If the environment variable EINA_ERROR_ABORT is set, abort() is called and the program stops. It is useful for debugging programs with gdb.