DLL Programmer's Guide for TNS/E Systems

Dynamic Use of DLLs
DLL Programmer’s Guide for TNS/E Systems—527252-006
3-6
Returned Values of dlsym
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 appropriate 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) on page 3-6.

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.
When dlsym() returns 0, call dlerror() for a textual description of the error, or
dlresultcode() for an encoded error code and error-detail. In the rare event that
dlsym() found the symbol and its value was 0, dlerror() and dlresultcode()
return 0.
Closing a Running Loadfile’s Handle to a DLL
(dlclose)
To invalidate a handle obtained by a dlopen call, a running process issues the following
call.
int dlclose(dlhandle dlopen_handle)