DLL Programmer's Guide for TNS/R Systems

Dynamic Use of DLLs
DLL Programmer’s Guide for TNS/R Systems—522203-002
3-5
Accessing Symbols (dlsym)
When dlopen returns 0, call dlerror() for a textual description of the error, or
dlresultcode() for an encoded error code and error-detail.
Accessing Symbols (dlsym)
Using the handle returned to the calling process by dlopen, that process can access a
named symbol if it is exported by the targeted DLL or any library in its loadList. dlsym
is the only way to access symbols in a dynamically loaded library; but it also allows a
process to obtain the address of a symbol exported by any currently loaded loadfile for
which the process has a dlopen handle or by the libraries in that loadfile’s loadList. The
following function call invokes dlsym:
void *dlsym(dlhandle dlopen_handle, const char *symbol_name)
The parameters of dlsym are:
*dlopen_handle – A handle returned by a previous dlopen call and not
invalidated by dlclose()..
*symbol_name – A pointer to the null-terminated name (string) of a symbol to be
accessed in the specified loadfile.
Returned Values of dlsym
Each dlsym call returns the address of a specified symbol. You can use the returned
address by storing it as a pointer of a type appropraite for the function or datum
designated by the symbol. dlsym finds this address by searching for the first exported
occurrence of the named symbol starting with the loadfile designated by the dlopen
handle and followed by the libraries in that loadfile’s loadList. The import and re-
export controls of the searched loadfiles are ignored. If the handle is for the main
program, dlsym starts with the main program and searches the entire operating load
set.
Each dlsym call returns the address of only one symbol, so the calling process must
issue a separate dlsym call for the address of each symbol it needs.
Error-Returned Value of dlsym
If dlsym encounters any of the following conditions, it returns the value 0:
•
Invalid dlopen_handle, including a handle that has been invalidated by dlclose,
as discussed in Closing a Running Loadfile’s Handle to a DLL (dlclose) below.
•
symbol_name cannot be found
•
The value of the symbol is 0 (rare, non-error case). Only an "absolute" symbol
exported from an assembler module can have the value 0; symbols exported by
higher-level languages are virtual addresses, and zero is never a valid address in
native processes.