Functions that manage dynamic-link libraries.
Evil

This header provides functions to load and unload dynamic-link libaries, to get the address of a symbol, and to get diagnostic information. More...

## Functions

EVIL_API void * | dlopen (const char *path, int mode)
| Map a specified executable module (either a .dll or .exe file) into the address space of the user process.
EVIL_API int | dlclose (void *handle)
| Close a dynamic-link library.
EVIL_API void * | dlsym (void *handle, const char *symbol)
| Get the address of a symbol.
EVIL_API char * | dlerror (void)
| Get diagnostic information.

## Detailed Description

This header provides functions to load and unload dynamic-link libaries, to get the address of a symbol, and to get diagnostic information.

## Function Documentation

## dlopen()

EVIL_API void * dlopen | ( | const char * | path,
|  | int | mode )

Map a specified executable module (either a .dll or .exe file) into the address space of the user process.

Parameters

  path | Name of the module.
  mode | Unused.

Returns
  A pointer that represent the module, or `NULL` on failure.

Map a specified executable module (either a .dll or .exe file) into the address space of the user process. If `path` is `NULL`, then the module corresponding to the current process is returned. Otherwise the module specified by `path` is loaded if it exists. If not, `NULL` is returned. The directory separators can be forward slash, or backward ones. Mapping a module can map other modules. `mode` is unused.

If an error occurred, an error string can be retrieved with dlerror().

According to the OS, the search order of the module can change, according to the value of SafeDllSearchMode.

- For Windows Vista, Windows Server 2003, and Windows XP SP2: SafeDLLSearchMode is enabled by default.
- For Windows XP and Windows 2000 SP4: SafeDLLSearchMode is disabled by default.

If SafeDllSearchMode is enabled

- The directory from which the application loaded.
- The system directory. Use the GetSystemDirectory() function to get the path of this directory.
- The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched.
- The Windows directory. Use the GetWindowsDirectory() function to get the path of this directory.
- The current directory.
- The directories that are listed in the PATH environment variable. Note that this does not include the per-application path specified by the App Paths registry key.

If SafeDllSearchMode is disabled

- The directory from which the application loaded.
- The current directory.
- The system directory. Use the GetSystemDirectory() function to get the path of this directory.
- The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched.
- The Windows directory. Use the GetWindowsDirectory() function to get the path of this directory.
- The directories that are listed in the PATH environment variable. Note that this does not include the per-application path specified by the App Paths registry key.

Conformity: None.

Supported OS: Windows Vista, Windows XP or Windows 2000 Professional.

References evil_char_to_wchar().

Referenced by efl_quicklaunch_prepare(), eina_module_load(), and elm_quicklaunch_prepare().

## dlclose()

EVIL_API int dlclose | ( | void * | handle | ) |

Close a dynamic-link library.

Parameters

  handle | Handle that references a dynamic-link library.

Returns
  O on success, -1 otherwise.

Release a reference to the dynamic-link library referenced by `handle`. If the reference count drops to 0, the handle is removed from the address space and is rendered invalid. `handle` is the value returned by a previous call to dlopen().

If no error occurred, the returned value is 0, otherwise the returned value is -1 and an error string can be retrieved with dlerror().

Conformity: None.

Supported OS: Windows Vista, Windows XP or Windows 2000 Professional.

Referenced by efl_quicklaunch_prepare(), eina_module_load(), eina_module_unload(), elm_quicklaunch_cleanup(), and elm_quicklaunch_prepare().

## dlsym()

EVIL_API void * dlsym | ( | void * | handle,
|  | const char * | symbol )

Get the address of a symbol.

Parameters

  handle | Handle that references a dynamic-link library.
  symbol | `NULL-terminated` string.

Returns
  O on success, NULL otherwise.

Return the address of the code or data location specified by the string `symbol`. `handle` references a library that contains the function or variable `symbol`.

If no error occurred, the returned value is the code or data location, otherwise the returned value is NULL and an error string can be retrieved with dlerror().

Conformity: None.

Supported OS: Windows Vista, Windows XP or Windows 2000 Professional.

References evil_char_to_wchar().

Referenced by efl_quicklaunch_prepare(), eina_module_load(), eina_module_symbol_get(), eina_module_unload(), and elm_quicklaunch_prepare().

## dlerror()

EVIL_API char * dlerror | ( | void |  | ) |

Get diagnostic information.

Returns
  A `NULL-terminated` string if an error occurred, `NULL` otherwise.

Return a `NULL-terminated` character string describing the last error that occurred on this thread during a call to dlopen(), dlsym(), or dlclose(). If no such error has occurred, dlerror() returns a null pointer. At each call to dlerror(), the error indication is reset. Thus in the case of two calls to dlerror(), where the second call follows the first immediately, the second call will always return a null pointer.

Conformity: None.

Supported OS: Windows Vista, Windows XP or Windows 2000 Professional.

Referenced by efl_quicklaunch_prepare(), eina_module_load(), and elm_quicklaunch_prepare().