Each of the module loaders implemented by libltdl is stored
according to a unique name, which can be used to lookup the associated
handle. These handles operate in much the same way as
lt_dlhandles: They are used for passing references to modules in
and out of the API, except that they represent a kind of
module loading method, as opposed to a loaded module instance.
This function finds the `lt_dlloader_t' handle associated with the
unique name passed as the only argument, or else returns `NULL' if
there is no such module loader registered.
Function: int lt_dlloader_add(lt_dlloader_t *place, lt_user_dlloader *dlloader, const char *loader_name)
This function is used to register your own module loading mechanisms
with libltdl. If place is given it must be a handle for an
already registered module loader, which the new loader dlloader
will be placed in front of for the purposes of which order to try
loaders in. If place is `NULL', on the other hand, the new
dlloader will be added to the end of the list of loaders to try
when loading a module instance. In either case loader_name must be
a unique name for use with lt_dlloader_find.
The dlloader argument must be a C structure of the following
format, populated with suitable function pointers which determine the
functionality of your module loader:
Function: int lt_dlloader_remove(const char *loader_name)
When there are no more loaded modules that were opened by the given
module loader, the loader itself can be removed using this function.
When you come to set the fields in the lt_user_dlloader
structure, they must each be of the correct type, as described below:
Type: const char * sym_prefix
If a particular module loader relies on a prefix to each symbol being
looked up (for example, the Windows module loader necessarily adds a
`_' prefix to each symbol name pased to lt_dlsym), it should
be recorded in the `sym_prefix' field.
When lt_dlopen has reached your registered module loader when
attempting to load a dynamic module, this is the type of the
module_open function that will be called. The name of the module
that libltdl is attempting to load, along with the module loader
instance data associated with the loader being used currently, are
passed as arguments to such a function call.
The lt_module_t returned by functions of this type can be
anything at all that can be recognised as unique to a successfully
loaded module instance when passed back into the module_close or
find_sym functions in the lt_user_dlloader module loader
structure.
Type: int lt_module_close_t(lt_dlloader_data_t loader_data, lt_module_t module)
In a similar vein, a function of this type will be called by
lt_dlclose, where module is the returned value from the
`module_open' function which loaded this dynamic module instance.
In a similar vein once more, a function of this type will be called by
lt_dlsym, and must return the address of symbol_name in
module.
Type: int lt_dlloader_exit_t(lt_dlloader_data_t loader_data)
When a user module loader is lt_dlloader_removed, a function of
this type will be called. That function is responsible for releasing
any resouces that were allocated during the initialisation of the
loader, so that they are not `leaked' when the lt_user_dlloader
structure is recycled.
Note that there is no initialisation function type: the initialisation
of a user module loader should be performed before the loader is
registered with lt_dlloader_add.
Type: lt_dlloader_data_t dlloader_data
The dlloader_data is a spare field which can be used to store or
pass any data specific to a particular module loader. That data will
always be passed as the value of the first argument to each of the
implementation functions above.
This document was generated
by Gary V. Vaughan on May, 24 2001
using texi2html