rld Manual

Using the rld Loader Library
RLD Manual—528857-006
2-4
dlopen()
Return Values
Upon successful completion, the dlopen() function returns a library handle valid for
use with other DLL functions. This handle is an arbitrary token, not an address. It
cannot be assigned to a pointer and dereferenced.
dlopen() returns a 0 (zero) if the file designated by object_pathname:

Cannot be found

Cannot be opened for execution

Is not a DLL or an unlicensed public SRL

Encounters an error during the loading or adjustment of the file’s symbolic
references
Call the dlerror() or dlresultcode() function immediately to determine the
problem.
Considerations
The dlopen() function invokes the rld loader to make a loadfile available to a
running process.
The library handle that dlopen() returns can be used by the dlsym() function to
access external symbols defined in the file. A library handle created using a null
object_pathname can be destroyed by dlclose(), but that action has no affect on
the loaded program.
A library handle is returned every time dlopen() is called successfully, even if the
loadfile is already loaded in the process. Loadfiles that are already loaded in the
process are not loaded again.
Until the library handle is invalidated by a call to the dlclose() function, the library
designated by object_pathname, and all the DLLs that the object_pathname
library requires, remain loaded. Any library handle returned by dlopen() counts as a
usage of the target library and any DLLs it requires. Until the last handle is invalidated
by the dlclose() function, the library is not unloaded.
A usage count is maintained for each library. The usage count is incremented by calls
to dlopen()and decremented by calls to dlclose(). When the usage count
indicates that a library has become unused, it is unloaded.
Symbol controls within the loadfiles affect a call to dlopen(). Therefore, the library
designated by object_pathname and each library it requires can be localized,
globalized, or semiglobalized itself, and its symbols are resolved accordingly.
Unlike loadfiles loaded at process startup, loadfiles loaded by dlopen() will not be
automatically updated. However, the loader will take advantage of preset bindings
where appropriate by use of FastLoad.
dlopen() does not load licensed DLLs.