GNU Info

(libtool.info)User defined module data

---

Next: Module loaders for libltdl Prev: Thread Safety in libltdl Up: Using libltdl

---

Enter node , (file) or (file)node

Data associated with loaded modules
===================================

   Some of the internal information about each loaded module that is
maintained by libltdl is available to the user, in the form of this
structure:

 - Type: struct lt_dlinfo { char *FILENAME; char *NAME; int REF_COUNT; }
     `lt_dlinfo' is used to store information about a module.  The
     FILENAME attribute is a null-terminated character string of the
     real module file name.  If the module is a libtool module then
     NAME is its module name (e.g. `"libfoo"' for `"dir/libfoo.la"'),
     otherwise it is set to `NULL'.  The REF_COUNT attribute is a
     reference counter that describes how often the same module is
     currently loaded.

   The following function will return a pointer to libltdl's internal
copy of this structure for the given HANDLE:

 - Function: const lt_dlinfo * lt_dlgetinfo (lt_dlhandle HANDLE)
     Return a pointer to a struct that contains some information about
     the module HANDLE.  The contents of the struct must not be
     modified.  Return `NULL' on failure.

   Furthermore, in order to save you from having to keep a list of the
handles of all the modules you have loaded, these functions allow you to
iterate over libltdl's list of loaded modules:

 - Function: int lt_dlforeach
          (int (*FUNC) (lt_dlhandle HANDLE, lt_ptr DATA), lt_ptr DATA)
     For each loaded module call the function FUNC.  The argument
     HANDLE is the handle of one of the loaded modules, DATA is the
     DATA argument passed to `lt_dlforeach'.  As soon as FUNC returns a
     non-zero value for one of the handles, `lt_dlforeach' will stop
     calling FUNC and immediately return 1.  Otherwise 0 is returned.

 - Function: lt_dlhandle lt_dlhandle_next (lt_dlhandle place)
     Iterate over the loaded module handles, returning the first handle
     in the list if PLACE is `NULL', and the next one on subsequent
     calls.  If PLACE is the last element in the list of loaded
     modules, this function returns `NULL'.

   Of course, you would still need to maintain your own list of loaded
module handles to parallel the list maintained by libltdl if there are
any other data that you need to associate with each handle for the
purposes of your application.  However, if you use the following API
calls to associate your application data with individual module handles
as they are loaded there is actually no need to do that.  You must
first obtain a unique caller id from libltdl which you subsequently use
to retrieve the data you stored earlier.  This allows for different
libraries that each wish to store their own data against loaded modules
to do so without interfering with one another's data.

 - Type: lt_dlcaller_id
     The opaque type used to hold individual data set keys.

 - Function: lt_dlcaller_id lt_dlcaller_register (void)
     Use this to obtain a unique key to store and retrieve individual
     sets of per module data.

 - Function: lt_ptr lt_dlcaller_set_data (lt_dlcaller_id KEY,
          lt_dlhandle HANDLE, lt_ptr DATA)
     Set DATA as the set of data uniquely associated with KEY and
     HANDLE for later retrieval.  This function returns the DATA
     previously associated with KEY and HANDLE if any.  A result of 0,
     may indicate that a diagnostic for the last error (if any) is
     available from `lt_dlerror()'.

     For example, to correctly remove some associated data:

              lt_ptr stale = lt_dlcaller_set_data (key, handle, 0);
              if (stale == NULL)
                {
                  char *error_msg = lt_dlerror ();
          
                  if (error_msg != NULL)
                    {
                      my_error_handler (error_msg);
                      return STATUS_FAILED;
                    }
                }
              else
                {
                  free (stale);
                }

 - Function: lt_ptr lt_dlcaller_get_data (lt_dlcaller_id KEY,
          lt_dlhandle HANDLE)
     Return the address of the data associated with KEY and HANDLE, or
     else `NULL' if there is none.

   The preceding functions can be combined with `lt_dlforeach' to
implement search and apply operations without the need for your
application to track the modules that have been loaded and unloaded:

     int
     my_dlcaller_callback (lt_dlhandle handle, lt_ptr key_ptr)
     {
       struct my_module_data *my_data;
     
       my_data = lt_dlcaller_get_data (handle, (lt_dlcaller_id) *key_ptr);
     
       return process (my_data);
     }
     
     int
     my_dlcaller_foreach (lt_dlcaller_id key)
     {
       lt_dlforeach (my_dlcaller_callback, (lt_ptr) &key);
     }