( Module loaders for libltdl

Info Catalog ( User defined module data ( Using libltdl ( Distributing libltdl
 10.5 How to create and register new module loaders
 Sometimes libltdl's many ways of gaining access to modules are not
 sufficient for the purposes of a project.  You can write your own
 loader, and register it with libltdl so that `lt_dlopen' will be able
 to use it.
    Writing a loader involves writing at least three functions which can
 be called  by `lt_dlopen', `lt_dlsym' and `lt_dlclose'.  Optionally,
 you can provide a finalisation function to perform any cleanup
 operations when `lt_dlexit' executes, and a symbol prefix string which
 will be prepended to any symbols passed to `lt_dlsym'.  These functions
 must match the function pointer types below, after which they can be
 allocated to an instance of `lt_user_dlloader' and registered.
    Registering the loader requires that you choose a name for it, so
 that it can be recognised by `lt_dlloader_find' and removed with
 `lt_dlloader_remove'.  The name you choose must be unique, and not
 already in use by libltdl's builtin loaders:
      The system dynamic library loader, if one exists.
      The GNU dld loader, if `libdld' was installed when libltdl was
      The loader for `lt_dlopen'ing of preloaded static modules.
    The prefix "dl" is reserved for loaders supplied with future
 versions of libltdl, so you should not use that for your own loader
 The following types are defined in `ltdl.h':
  -- Type: lt_module
      `lt_module' is a dlloader dependent module.  The dynamic module
      loader extensions communicate using these low level types.
  -- Type: lt_dlloader
      `lt_dlloader' is a handle for module loader types.
  -- Type: lt_dlloader_data
      `lt_dlloader_data' is used for specifying loader instance data.
  -- Type: struct lt_user_dlloader {const char *SYM_PREFIX;
           lt_module_open *MODULE_OPEN;lt_module_close *MODULE_CLOSE;
           lt_find_sym *FIND_SYM; lt_dlloader_exit *DLLOADER_EXIT;
           lt_dlloader_data DLLOADER_DATA; }
      If you want to define a new way to open dynamic modules, and have
      the `lt_dlopen' API use it, you need to instantiate one of these
      structures and pass it to `lt_dlloader_add'.  You can pass whatever
      you like in the DLLOADER_DATA field, and it will be passed back as
      the value of the first parameter to each of the functions
      specified in the function pointer fields.
  -- Type: lt_module lt_module_open (lt_user_data LOADER_DATA,
           const char *FILENAME)
      The type of the loader function for an `lt_dlloader' module
      loader.  The value set in the dlloader_data field of the `struct
      lt_user_dlloader' structure will be passed into this function in
      the LOADER_DATA parameter.  Implementation of such a function
      should attempt to load the named module, and return an `lt_module'
      suitable for passing in to the associated `lt_module_close' and
      `lt_sym_find' function pointers.  If the function fails it should
      return `NULL', and set the error message with `lt_dlseterror'.
  -- Type: int lt_module_close (lt_dlloader_data LOADER_DATA,
           lt_module MODULE)
      The type of the unloader function for a user defined module loader.
      Implementatation of such a function should attempt to release any
      resources tied up by the MODULE module, and then unload it from
      memory.  If the function fails for some reason, set the error
      message with `lt_dlseterror' and return non-zero.
  -- Type: lt_ptr lt_find_sym (lt_user_data LOADER_DATA,
           lt_module MODULE, const char *SYMBOL)
      The type of the symbol lookup function for a user defined module
      loader.  Implementation of such a function should return the
      address of the named SYMBOL in the module MODULE, or else set the
      error message with `lt_dlseterror' and return `NULL' if lookup
  -- Type: int lt_dlloader_exit (lt_user_data LOADER_DATA)
      The type of the finalisation function for a user defined module
      loader.  Implementation of such a function should free any
      resources associated with the loader, including any user specified
      data in the `dlloader_data' field of the `lt_user_dlloader'.  If
      non-`NULL', the function will be called by `lt_dlexit', and
    For example:
      register_myloader (void)
        lt_user_dlloader dlloader;
        /* User modules are responsible for their own initialisation. */
        if (myloader_init () != 0)
          return MYLOADER_INIT_ERROR;
        dlloader.sym_prefix    = NULL;
        dlloader.module_open   = myloader_open;
        dlloader.module_close  = myloader_close;
        dlloader.find_sym      = myloader_find_sym.
        dlloader.dlloader_exit = myloader_exit;
        dlloader.dlloader_data = (lt_user_data)myloader_function;
        /* Add my loader as the default module loader. */
        if (lt_dlloader_add (lt_dlloader_next (NULL), &dlloader, "myloader") != 0)
          return ERROR;
        return OK;
    Note that if there is any initialisation required for the loader, it
 must be performed manually before the loader is registered - libltdl
 doesn't handle user loader initialisation.
    Finalisation _is_ handled by libltdl however, and it is important to
 ensure the `dlloader_exit' callback releases any resources claimed
 during the initialisation phase.
 libltdl provides the following functions for writing your own module
  -- Function: int lt_dlloader_add (lt_dlloader *PLACE,
           lt_user_dlloader *DLLOADER, const char *LOADER_NAME)
      Add a new module loader to the list of all loaders, either as the
      last loader (if PLACE is `NULL'), else immediately before the
      loader passed as PLACE.  LOADER_NAME will be returned by
      `lt_dlloader_name' if it is subsequently passed a newly registered
      loader.  These LOADER_NAMEs must be unique, or
      `lt_dlloader_remove' and `lt_dlloader_find' cannot work. Returns 0
      for success.
             /* Make myloader be the last one. */
             if (lt_dlloader_add (NULL, myloader) != 0)
               perror (lt_dlerror ());
  -- Function: int lt_dlloader_remove (const char *LOADER_NAME)
      Remove the loader identified by the unique name, LOADER_NAME.
      Before this can succeed, all modules opened by the named loader
      must have been closed.  Returns 0 for success, otherwise an error
      message can be obtained from `lt_dlerror'.
             /* Remove myloader. */
             if (lt_dlloader_remove ("myloader") != 0)
               perror (lt_dlerror ());
  -- Function: lt_dlloader * lt_dlloader_next (lt_dlloader *PLACE)
      Iterate over the module loaders, returning the first loader if
      PLACE is `NULL', and the next one on subsequent calls. The handle
      is for use with `lt_dlloader_add'.
             /* Make myloader be the first one. */
             if (lt_dlloader_add (lt_dlloader_next (NULL), myloader) != 0)
               return ERROR;
  -- Function: lt_dlloader * lt_dlloader_find (const char *LOADER_NAME)
      Return the first loader with a matching LOADER_NAME identifier, or
      else `NULL', if the identifier is not found.
      The identifiers which may be used by libltdl itself, if the host
      architecture supports them are "dlopen"(1), "dld" and "dlpreload".
             /* Add a user loader as the next module loader to be tried if
                the standard dlopen loader were to fail when lt_dlopening. */
             if (lt_dlloader_add (lt_dlloader_find ("dlopen"), myloader) != 0)
               return ERROR;
  -- Function: const char * lt_dlloader_name (lt_dlloader *PLACE)
      Return the identifying name of PLACE, as obtained from
      `lt_dlloader_next' or `lt_dlloader_find'.  If this function fails,
      it will return `NULL' and set an error for retrieval with
  -- Function: lt_user_data * lt_dlloader_data (lt_dlloader *PLACE)
      Return the address of the `dlloader_data' of PLACE, as obtained
      from `lt_dlloader_next' or `lt_dlloader_find'.  If this function
      fails, it will return `NULL' and set an error for retrieval with
 10.5.1 Error handling within user module loaders
  -- Function: int lt_dladderror (const char *DIAGNOSTIC)
      This function allows you to integrate your own error messages into
      `lt_dlerror'.  Pass in a suitable diagnostic message for return by
      `lt_dlerror', and an error identifier for use with `lt_dlseterror'
      is returned.
      If the allocation of an identifier fails, this function returns -1.
           int myerror = lt_dladderror ("Doh!");
           if (myerror < 0)
             perror (lt_dlerror ());
  -- Function: int lt_dlseterror (int ERRORCODE)
      When writing your own module loaders, you should use this function
      to raise errors so that they are propogated through the
      `lt_dlerror' interface. All of the standard errors used by libltdl
      are declared in `ltdl.h', or you can add more of your own with
      `lt_dladderror'.  This function returns 0 on success.
           if (lt_dlseterror (LTDL_ERROR_NO_MEMORY) != 0)
             perror (lt_dlerror ());
 ---------- Footnotes ----------
    (1) This is used for the host dependent module loading API -
 `shl_load' and `LoadLibrary' for example
Info Catalog ( User defined module data ( Using libltdl ( Distributing libltdl
automatically generated byinfo2html