Functions that manage dynamic-link libraries.

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

EAPI 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. More...
 
EAPI int dlclose (void *handle)
 Close a dynamic-link library. More...
 
EAPI void * dlsym (void *handle, const char *symbol)
 Get the address of a symbol. More...
 
EAPI int dladdr (const void *addr, Dl_info *info)
 Get the location of the current process (.exe) More...
 
EAPI char * dlerror (void)
 Get diagnostic information. More...
 

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

EAPI 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
pathName of the module.
modeUnused.
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 retrived 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 ecore_x_init(), and eina_module_load().

EAPI int dlclose ( void *  handle)

Close a dynamic-link library.

Parameters
handleHandle that references a dynamic-link library.
Returns
O on sucess, -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 retrived with dlerror().

Conformity: None.

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

Referenced by eina_module_load(), and eina_module_unload().

EAPI void* dlsym ( void *  handle,
const char *  symbol 
)

Get the address of a symbol.

Parameters
handleHandle that references a dynamic-link library.
symbolNULL-terminated string.
Returns
O on sucess, 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 retrived with dlerror().

Conformity: None.

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

References evil_char_to_wchar(), and RTLD_DEFAULT.

Referenced by ecore_x_init(), eina_module_load(), eina_module_symbol_get(), and eina_module_unload().

EAPI int dladdr ( const void *  addr,
Dl_info info 
)

Get the location of the current process (.exe)

Parameters
addrUnused.
infoPointer to the Dl_info to fill.
Returns
1 on success, 0 otherwise.

Fill the dli_fname member of info with the absolute name of the current calling process (.exe file that is executed). All other members are set to NULL.

Contrary to the unix function, the full name of the shared library is not returned, but insted the full name of the current calling process (.exe file).

Conformity: None.

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

Referenced by eina_module_symbol_path_get(), and eina_prefix_new().

EAPI char* dlerror ( void  )

Get diagnostic information.

Returns
A NULL-terminated string if an error occured, 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 eina_module_load().