libltdl/ltdl.h

   1 /* ltdl.h -- generic dlopen functions
   2    Copyright (C) 1998-2000, 2004, 2005 Free Software Foundation, Inc.
   3    Originally by Thomas Tanner <tanner@ffii.org>
   4
   5    NOTE: The canonical source of this file is maintained with the
   6    GNU Libtool package.  Report bugs to bug-libtool@gnu.org.
   7
   8 This library is free software; you can redistribute it and/or
   9 modify it under the terms of the GNU Lesser General Public
  10 License as published by the Free Software Foundation; either
  11 version 2 of the License, or (at your option) any later version.
  12
  13 As a special exception to the GNU Lesser General Public License,
  14 if you distribute this file as part of a program or library that
  15 is built using GNU libtool, you may include it under the same
  16 distribution terms that you use for the rest of that program.
  17
  18 This library is distributed in the hope that it will be useful,
  19 but WITHOUT ANY WARRANTY; without even the implied warranty of
  20 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  21 Lesser General Public License for more details.
  22
  23 You should have received a copy of the GNU Lesser General Public
  24 License along with this library; if not, write to the Free
  25 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  26 02110-1301  USA
  27 */
  28
  29 /* Only include this header file once. */
  30 #if !defined(LTDL_H)
  31 #define LTDL_H 1
  32
  33 #include <libltdl/lt_system.h>
  34 #include <libltdl/lt_error.h>
  35 #include <libltdl/lt_dlloader.h>
  36
  37 LT_BEGIN_C_DECLS
  38
  39
  40 /* LT_STRLEN can be used safely on NULL pointers.  */
  41 #define LT_STRLEN(s)    (((s) && (s)[0]) ? strlen (s) : 0)
  42
  43
  44 \f
  45 /* --- DYNAMIC MODULE LOADING API --- */
  46
  47
  48 typedef void * lt_dlhandle;     /* A loaded module.  */
  49
  50 /* Initialisation and finalisation functions for libltdl. */
  51 LT_SCOPE int        lt_dlinit           (void);
  52 LT_SCOPE int        lt_dlexit           (void);
  53
  54 /* Module search path manipulation.  */
  55 LT_SCOPE int        lt_dladdsearchdir    (const char *search_dir);
  56 LT_SCOPE int        lt_dlinsertsearchdir (const char *before,
  57                                                   const char *search_dir);
  58 LT_SCOPE int        lt_dlsetsearchpath   (const char *search_path);
  59 LT_SCOPE const char *lt_dlgetsearchpath  (void);
  60 LT_SCOPE int        lt_dlforeachfile     (
  61                         const char *search_path,
  62                         int (*func) (const char *filename, void *data),
  63                         void *data);
  64
  65 /* Portable libltdl versions of the system dlopen() API. */
  66 LT_SCOPE lt_dlhandle lt_dlopen          (const char *filename);
  67 LT_SCOPE lt_dlhandle lt_dlopenext       (const char *filename);
  68 LT_SCOPE void *     lt_dlsym            (lt_dlhandle handle, const char *name);
  69 LT_SCOPE const char *lt_dlerror         (void);
  70 LT_SCOPE int        lt_dlclose          (lt_dlhandle handle);
  71
  72 /* Module residency management. */
  73 LT_SCOPE int        lt_dlmakeresident   (lt_dlhandle handle);
  74 LT_SCOPE int        lt_dlisresident     (lt_dlhandle handle);
  75
  76
  77
  78 \f
  79 /* --- PRELOADED MODULE SUPPORT --- */
  80
  81
  82 /* A preopened symbol. Arrays of this type comprise the exported
  83    symbols for a dlpreopened module. */
  84 typedef struct {
  85   const char *name;
  86   void       *address;
  87 } lt_dlsymlist;
  88
  89 typedef int lt_dlpreload_callback_func (lt_dlhandle handle);
  90
  91 LT_SCOPE int    lt_dlpreload         (const lt_dlsymlist *preloaded);
  92 LT_SCOPE int    lt_dlpreload_default (const lt_dlsymlist *preloaded);
  93 LT_SCOPE int    lt_dlpreload_open    (const char *originator,
  94                                       lt_dlpreload_callback_func *func);
  95
  96 #define lt_preloaded_symbols    lt__PROGRAM__LTX_preloaded_symbols
  97 #define LTDL_SET_PRELOADED_SYMBOLS()                    LT_STMT_START{  \
  98         extern const lt_dlsymlist lt_preloaded_symbols[];               \
  99         lt_dlpreload_default(lt_preloaded_symbols);                     \
 100                                                         }LT_STMT_END
 101
 102
 103
 104 \f
 105 /* --- MODULE INFORMATION --- */
 106
 107
 108 /* Associating user data with loaded modules. */
 109 typedef void * lt_dlinterface_id;
 110 typedef int lt_dlhandle_interface (lt_dlhandle handle, const char *id_string);
 111
 112 LT_SCOPE lt_dlinterface_id lt_dlinterface_register (const char *id_string,
 113                                           lt_dlhandle_interface *iface);
 114 LT_SCOPE void   lt_dlinterface_free (lt_dlinterface_id key);
 115 LT_SCOPE void * lt_dlcaller_set_data  (lt_dlinterface_id key,
 116                                           lt_dlhandle handle, void *data);
 117 LT_SCOPE void * lt_dlcaller_get_data  (lt_dlinterface_id key,
 118                                           lt_dlhandle handle);
 119
 120
 121 /* Read only information pertaining to a loaded module. */
 122 typedef struct {
 123   char *        filename;       /* file name */
 124   char *        name;           /* module name */
 125   int           ref_count;      /* number of times lt_dlopened minus
 126                                    number of times lt_dlclosed. */
 127 } lt_dlinfo;
 128
 129 LT_SCOPE const lt_dlinfo *lt_dlgetinfo      (lt_dlhandle handle);
 130
 131 LT_SCOPE lt_dlhandle    lt_dlhandle_iterate (lt_dlinterface_id iface,
 132                                              lt_dlhandle place);
 133 LT_SCOPE lt_dlhandle    lt_dlhandle_fetch   (lt_dlinterface_id iface,
 134                                              const char *module_name);
 135 LT_SCOPE int            lt_dlhandle_map     (lt_dlinterface_id iface,
 136                                 int (*func) (lt_dlhandle handle, void *data),
 137                                 void *data);
 138
 139 #define lt_ptr void *
 140
 141 LT_END_C_DECLS
 142
 143 #endif /*!defined(LTDL_H)*/