Module
Eina » Tools

These functions provide module management. More...

## Macros

#define | EINA_MODULE_LICENSE(_license)
| This macro is used for defining license.
#define | EINA_MODULE_AUTHOR(_author)
| This macro is used for defining author Use "name <email>" or just "name" for multiple authors, use multiple lines like below.
#define | EINA_MODULE_VERSION(_ver)
| This macro is used for defining version.
#define | EINA_MODULE_DESCRIPTION(_desc)
| This macro is used for defining description.
#define | EINA_MODULE_INIT(f)
| declares the given function as the module initializer (__eina_module_init).
#define | EINA_MODULE_SHUTDOWN(f)
| declares the given function as to be called on shutdown (__eina_module_shutdown).

## Typedefs

typedef struct _Eina_Module | Eina_Module
| Dynamic module loader handle.
typedef Eina_Bool(* | Eina_Module_Cb) (Eina_Module *m, void *data)
| Dynamic module loader callback.
typedef Eina_Bool(* | Eina_Module_Init) (void)
| If a function with this signature is exported by module as __eina_module_init, it will be called on the first load after dlopen() and if EINA_FALSE is returned, load will fail, EINA_TRUE means the module was successfully initialized.
typedef void(* | Eina_Module_Shutdown) (void)
| If a function with this signature is exported by module as __eina_module_shutdown, it will be called before calling dlclose().

## Functions

EINA_API Eina_Module * | eina_module_new (const char *file)
| Returns a new module.
EINA_API Eina_Bool | eina_module_free (Eina_Module *module)
| Deletes a module.
EINA_API Eina_Bool | eina_module_load (Eina_Module *module)
| Loads a module.
EINA_API Eina_Bool | eina_module_unload (Eina_Module *module)
| Unloads a module.
EINA_API void * | eina_module_symbol_get (const Eina_Module *module, const char *symbol)
| Retrieves the data associated with a symbol.
EINA_API const char * | eina_module_file_get (const Eina_Module *module)
| Returns the file name associated with the module.
EINA_API void | eina_module_symbol_global_set (Eina_Module *module, Eina_Bool global)
| Defines if on module load we should expose all symbol.
EINA_API char * | eina_module_symbol_path_get (const void *symbol, const char *sub_dir)
| Returns the path built from the location of a library and a given sub directory.
EINA_API char * | eina_module_environment_path_get (const char *env, const char *sub_dir)
| Returns the path built from the value of an environment variable and a given sub directory.
EINA_API Eina_Array * | eina_module_arch_list_get (Eina_Array *array, const char *path, const char *arch)
| Gets an array of modules found on the directory path matching an arch type.
EINA_API Eina_Array * | eina_module_list_get (Eina_Array *array, const char *path, Eina_Bool recursive, Eina_Module_Cb cb, void *data)
| Gets a list of modules found on the directory path.
EINA_API void | eina_module_list_load (Eina_Array *array)
| Loads every module on the list of modules.
EINA_API void | eina_module_list_unload (Eina_Array *array)
| Unloads every module on the list of modules.
EINA_API void | eina_module_list_free (Eina_Array *array)
| `Frees` every module on the list of modules.
EINA_API Eina_Module * | eina_module_find (const Eina_Array *array, const char *module)
| Finds a module in array.

## Variables

EINA_API Eina_Error | EINA_ERROR_WRONG_MODULE
EINA_API Eina_Error | EINA_ERROR_MODULE_INIT_FAILED

## Detailed Description

These functions provide module management.

Eina module provides some helpers over POSIX dlopen(). It is not meant to replace, abstract or make a "portable" version of POSIX, but enhance its usage by defining some good practices.

Modules are created with eina_module_new() and later loaded with eina_module_load(). Loads are reference counted and there must be the same number of eina_module_unload() in order to have it to call dlclose(). This makes simple to have different users for the same module.

The loaded shared objects may have two visible functions that will be called and might provide initialization and shutdown procedures. The symbols are `__eina_module_init` and `__eina_module_shutdown` and will be defined by the macros EINA_MODULE_INIT() and EINA_MODULE_SHUTDOWN().

There are some helpers to automatically create modules based on directory listing. See eina_module_arch_list_get(), eina_module_list_get() and eina_module_find().

EINA_MODULE_LICENSE, EINA_MODULE_AUTHOR, EINA_MODULE_VERSION and EINA_MODULE_DESCRIPTION allow you to define module information that can be retrieved with the `eina_modinfo` tool.

$ eina_modinfo module.so
version: 0.1
description: Entry test
license: GPLv2
author: Enlightenment Community

## Macro Definition Documentation

## EINA_MODULE_LICENSE

#define EINA_MODULE_LICENSE | ( |  | _license | ) |

Value:
EINA_MODINFO(license, _license)

This macro is used for defining license.

## EINA_MODULE_AUTHOR

#define EINA_MODULE_AUTHOR | ( |  | _author | ) |

Value:
EINA_MODINFO(author, _author)

This macro is used for defining author Use "name <email>" or just "name" for multiple authors, use multiple lines like below.

EINA_MODULE_AUTHOR("Author 1 <author1.email>\n"
"Author 2 <author2.email>");
EINA_MODULE_AUTHOR
#define EINA_MODULE_AUTHOR(_author)
This macro is used for defining author Use "name <email>" or just "name" for multiple authors,...
Definition eina_inline_modinfo.x:49

## EINA_MODULE_VERSION

#define EINA_MODULE_VERSION | ( |  | _ver | ) |

Value:
EINA_MODINFO(ver, _ver)

This macro is used for defining version.

## EINA_MODULE_DESCRIPTION

#define EINA_MODULE_DESCRIPTION | ( |  | _desc | ) |

Value:
EINA_MODINFO(desc, _desc)

This macro is used for defining description.

Explain what your module does.

## EINA_MODULE_INIT

#define EINA_MODULE_INIT | ( |  | f | ) |

Value:
EXPORTAPI Eina_Module_Init __eina_module_init = &f
Eina_Module_Init
Eina_Bool(* Eina_Module_Init)(void)
If a function with this signature is exported by module as __eina_module_init, it will be called on t...
Definition eina_module.h:85
EXPORTAPI
#define EXPORTAPI
An alias for EINA_API.
Definition eina_types.h:101

declares the given function as the module initializer (__eina_module_init).

It must be of signature Eina_Module_Init

## EINA_MODULE_SHUTDOWN

#define EINA_MODULE_SHUTDOWN | ( |  | f | ) |

Value:
EXPORTAPI Eina_Module_Shutdown __eina_module_shutdown = &f
Eina_Module_Shutdown
void(* Eina_Module_Shutdown)(void)
If a function with this signature is exported by module as __eina_module_shutdown,...
Definition eina_module.h:93

declares the given function as to be called on shutdown (__eina_module_shutdown).

It must be of signature Eina_Module_Shutdown

## Typedef Documentation

## Eina_Module_Init

typedef Eina_Bool(* Eina_Module_Init) (void)

If a function with this signature is exported by module as __eina_module_init, it will be called on the first load after dlopen() and if EINA_FALSE is returned, load will fail, EINA_TRUE means the module was successfully initialized.

See also
  Eina_Module_Shutdown

## Eina_Module_Shutdown

typedef void(* Eina_Module_Shutdown) (void)

If a function with this signature is exported by module as __eina_module_shutdown, it will be called before calling dlclose().

See also
  Eina_Module_Init

## Function Documentation

## eina_module_new()

EINA_API Eina_Module * eina_module_new | ( | const char * | file | ) |

Returns a new module.

Parameters

  [in] | file | The name of the file module to load.

Returns
  A new module. If `file` is `NULL`, or if it does not exist, the function returns `NULL`, otherwise, it allocates an Eina_Module, stores a duplicate string of `file`, sets its reference to `0` and its handle to `NULL`.

When the new module is not needed anymore, use eina_module_free() to free the allocated memory.

See also
  eina_module_load

References DBG, EINA_API, EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, and ERR.

## eina_module_free()

EINA_API Eina_Bool eina_module_free | ( | Eina_Module * | module | ) |

Deletes a module.

Parameters

  [in,out] | module | The module to delete.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function calls eina_module_unload() if `module` has been previously loaded and frees the allocated memory. On success this function returns EINA_TRUE and EINA_FALSE otherwise. If `module` is `NULL`, the function returns immediately.

References DBG, EINA_API, EINA_FALSE, eina_module_unload(), EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Referenced by eina_module_list_free().

## eina_module_load()

EINA_API Eina_Bool eina_module_load | ( | Eina_Module * | module | ) |

Loads a module.

Parameters

  [in,out] | module | The module to load.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function load the shared file object passed in eina_module_new(). If it is a internal Eina module (like the mempools), it also initializes it. If the shared file object cannot be loaded, EINA_FALSE is returned. If it is an internal Eina module and the module cannot be initialized, EINA_FALSE is returned. If the module has already been loaded, its reference counter is increased by one and EINA_TRUE is returned. If `module` is `NULL`, the function returns immediately EINA_FALSE.

When the symbols of the shared file objects are not needed anymore, call eina_module_unload() to unload the module.

References DBG, dlclose(), dlerror(), dlopen(), dlsym(), EINA_API, EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, ERR, INF, RTLD_GLOBAL, RTLD_LAZY, and RTLD_NOW.

Referenced by eina_module_list_load().

## eina_module_unload()

EINA_API Eina_Bool eina_module_unload | ( | Eina_Module * | module | ) |

Unloads a module.

Parameters

  [in,out] | module | The module to load.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise.

This function unload the module `module` that has been previously loaded by eina_module_load(). If the reference counter of `module` is strictly greater than `1`, EINA_FALSE is returned. Otherwise, the shared object file is closed and if it is a internal Eina module, it is shut down just before. In that case, EINA_TRUE is returned. In all case, the reference counter is decreased. If `module` is `NULL`, the function returns immediately EINA_FALSE.

References DBG, dlclose(), dlsym(), EINA_API, EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_TRUE.

Referenced by eina_module_free(), and eina_module_list_unload().

## eina_module_symbol_get()

EINA_API void * eina_module_symbol_get | ( | const Eina_Module * | module,
|  | const char * | symbol )

Retrieves the data associated with a symbol.

Parameters

  [in] | module | The module.
  [in] | symbol | The symbol.

Returns
  The data associated with the symbol, or `NULL` on failure.

This function returns the data associated with `symbol` of `module`. `module` must have been loaded before with eina_module_load(). If `module` is `NULL`, or if it has not been correctly loaded before, the function returns immediately `NULL`.

References dlsym(), EINA_API, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by ecore_evas_cocoa_new(), ecore_evas_drm_new(), ecore_evas_extn_plug_new(), ecore_evas_extn_socket_events_block_get(), ecore_evas_extn_socket_events_block_set(), ecore_evas_extn_socket_new(), ecore_evas_fb_new(), ecore_evas_gl_drm_new(), ecore_evas_gl_sdl_new(), ecore_evas_gl_win32_new(), ecore_evas_gl_x11_new(), ecore_evas_gl_x11_options_new(), ecore_evas_gl_x11_pixmap_new(), ecore_evas_pointer_device_xy_get(), ecore_evas_psl1ght_new(), ecore_evas_sdl_new(), ecore_evas_software_ddraw_new(), ecore_evas_software_gdi_new(), ecore_evas_software_x11_new(), ecore_evas_software_x11_pixmap_new(), ecore_evas_vnc_start(), ecore_evas_wayland_egl_new(), and ecore_evas_wayland_shm_new().

## eina_module_file_get()

EINA_API const char * eina_module_file_get | ( | const Eina_Module * | module | ) |

Returns the file name associated with the module.

Parameters

  [in] | module | The module.

Returns
  The file name.

This function returns the file name passed in eina_module_new(). If `module` is `NULL`, the function returns immediately `NULL`. The returned value must no be freed.

References EINA_API, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_module_find().

## eina_module_symbol_global_set()

EINA_API void eina_module_symbol_global_set | ( | Eina_Module * | module,
|  | Eina_Bool | global )

Defines if on module load we should expose all symbol.

Parameters

  [in,out] | module | The module to turn off/on symbol to be exposed
  [in] | global | `true` to turn on symbol to be exposed, `false` otherwise

Since
  1.11

References EINA_API, and EINA_SAFETY_ON_NULL_RETURN.

## eina_module_symbol_path_get()

EINA_API char * eina_module_symbol_path_get | ( | const void * | symbol,
|  | const char * | sub_dir )

Returns the path built from the location of a library and a given sub directory.

Parameters

  [in] | symbol | The symbol to search for.
  [in] | sub_dir | The subdirectory to append.

Returns
  The built path on success, `NULL` otherwise.

This function returns the path built by concatenating the path of the library containing the symbol `symbol` and `sub_dir`. `sub_dir` can be `NULL`. The returned path must be freed when not used anymore. If the symbol is not found, or dl_addr() is not supported, or allocation fails, this function returns `NULL`.

References EINA_API, EINA_PATH_SEP_C, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by ecore_buffer_init().

## eina_module_environment_path_get()

EINA_API char * eina_module_environment_path_get | ( | const char * | env,
|  | const char * | sub_dir )

Returns the path built from the value of an environment variable and a given sub directory.

Parameters

  [in] | env | The environment variable to expand.
  [in] | sub_dir | The subdirectory to append.

Returns
  The built path on success, `NULL` otherwise.

This function returns the path built by concatenating the value of the environment variable named `env` and `sub_dir`. `sub_dir` can be `NULL`. The returned path must be freed when not used anymore. If the symbol is not found, or `env` does not exist, or allocation fails, this function returns `NULL`.

References EINA_API, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## eina_module_arch_list_get()

EINA_API Eina_Array * eina_module_arch_list_get | ( | Eina_Array * | array,
|  | const char * | path,
|  | const char * | arch )

Gets an array of modules found on the directory path matching an arch type.

Parameters

  [in,out] | array | The array that stores the list of the modules.
  [in] | path | The directory's path to search for modules.
  [in] | arch | The architecture string.

Returns
  The array of modules found in `path` matching `arch`.

This function adds to `array` the module names found in `path` which match the cpu architecture `arch`. If `path` or `arch` is `NULL`, the function returns immediately `array`. `array` can be `NULL`. In that case, it is created with 4 elements.

References EINA_API, eina_array_new(), EINA_FALSE, and eina_file_dir_list().

Referenced by ecore_buffer_init().

## eina_module_list_get()

EINA_API Eina_Array * eina_module_list_get | ( | Eina_Array * | array,
|  | const char * | path,
|  | Eina_Bool | recursive,
|  | Eina_Module_Cb | cb,
|  | void * | data )

Gets a list of modules found on the directory path.

Parameters

  [in,out] | array | The array that stores the list of the modules.
  [in] | path | The directory's path to search for modules.
  [in] | recursive | Iterate recursively on the path.
  [in] | cb | Callback function to call on each module.
  [in] | data | Data passed to the callback function.

Returns
  The array of modules found in `path`.

This function adds to `array` the list of modules found in `path`. If `recursive` is EINA_TRUE, then recursive search is done. The callback `cb` is called on each module found, and `data` is passed to `cb`. If `path` is `NULL`, the function returns immediately `array`. If the returned value of `cb` is `0`, the module will not be added to the list, otherwise it will be added. `array` can be `NULL`. In that case, it is created with 4 elements. `cb` can be `NULL`.

References EINA_API, eina_array_new(), and eina_file_dir_list().

Referenced by ecore_buffer_init().

## eina_module_list_load()

EINA_API void eina_module_list_load | ( | Eina_Array * | array | ) |

Loads every module on the list of modules.

Parameters

  [in,out] | array | The array of modules to load.

This function calls eina_module_load() on each element found in `array`. If `array` is `NULL`, this function does nothing.

References _Eina_Array::count, DBG, EINA_API, EINA_ARRAY_ITER_NEXT, and eina_module_load().

Referenced by ecore_buffer_init().

## eina_module_list_unload()

EINA_API void eina_module_list_unload | ( | Eina_Array * | array | ) |

Unloads every module on the list of modules.

Parameters

  [in,out] | array | The array of modules to unload.

This function calls eina_module_unload() on each element found in `array`. If `array` is `NULL`, this function does nothing.

References _Eina_Array::count, DBG, EINA_API, EINA_ARRAY_ITER_NEXT, and eina_module_unload().

## eina_module_list_free()

EINA_API void eina_module_list_free | ( | Eina_Array * | array | ) |

`Frees` every module on the list of modules.

Parameters

  [in,out] | array | The array of modules to free.

This function calls eina_module_free() on each element found in `array`. If `array` is `NULL`, this function does nothing.

References _Eina_Array::count, DBG, EINA_API, eina_array_flush(), EINA_ARRAY_ITER_NEXT, eina_module_free(), and EINA_SAFETY_ON_NULL_RETURN.

Referenced by ecore_buffer_shutdown().

## eina_module_find()

EINA_API Eina_Module * eina_module_find | ( | const Eina_Array * | array,
|  | const char * | module )

Finds a module in array.

Parameters

  [in] | array | The array to find the module.
  [in] | module | The name of module to be searched.

Returns
  The module to find on success, `NULL` otherwise.

This function finds a `module` in `array`. If the element is found the function returns the module, else `NULL` is returned.

References alloca(), EINA_ARRAY_ITER_NEXT, and eina_module_file_get().