include/ltdl.h

   1 /* ltdl.h -- generic dlopen functions
   2    Copyright (C) 1998-2001, 2003, 2004, 2007 Free Software Foundation, Inc.
   3    Originally by Thomas Tanner <tanner@ffii.org>
   4    This file is part of GNU Libtool.
   5
   6 This library is free software; you can redistribute it and/or
   7 modify it under the terms of the GNU Lesser General Public
   8 License as published by the Free Software Foundation; either
   9 version 2 of the License, or (at your option) any later version.
  10
  11 As a special exception to the GNU Lesser General Public License,
  12 if you distribute this file as part of a program or library that
  13 is built using GNU libtool, you may include it under the same
  14 distribution terms that you use for the rest of that program.
  15
  16 This library is distributed in the hope that it will be useful,
  17 but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 Lesser General Public License for more details.
  20
  21 You should have received a copy of the GNU Lesser General Public
  22 License along with this library; if not, write to the Free
  23 Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  24 02110-1301  USA
  25 */
  26
  27 /* Only include this header file once. */
  28 #ifndef LTDL_H
  29 #define LTDL_H 1
  30
  31 #include <sys/types.h>          /* for size_t declaration */
  32
  33 \f
  34 /* --- MACROS FOR PORTABILITY --- */
  35
  36
  37 /* Saves on those hard to debug '\0' typos....  */
  38 #define LT_EOS_CHAR     '\0'
  39
  40 /* LTDL_BEGIN_C_DECLS should be used at the beginning of your declarations,
  41    so that C++ compilers don't mangle their names.  Use LTDL_END_C_DECLS at
  42    the end of C declarations. */
  43 #ifdef __cplusplus
  44 # define LT_BEGIN_C_DECLS       extern "C" {
  45 # define LT_END_C_DECLS         }
  46 #else
  47 # define LT_BEGIN_C_DECLS       /* empty */
  48 # define LT_END_C_DECLS         /* empty */
  49 #endif
  50
  51 LT_BEGIN_C_DECLS
  52
  53
  54 /* LT_PARAMS is a macro used to wrap function prototypes, so that compilers
  55    that don't understand ANSI C prototypes still work, and ANSI C
  56    compilers can issue warnings about type mismatches.  */
  57 #if defined (__STDC__) || defined (_AIX) || (defined (__mips) && defined (_SYSTYPE_SVR4)) || defined(WIN32) || defined(__cplusplus)
  58 # define LT_PARAMS(protos)      protos
  59 # define lt_ptr         void*
  60 #else
  61 # define LT_PARAMS(protos)      ()
  62 # define lt_ptr         char*
  63 #endif
  64
  65 /* LT_STMT_START/END are used to create macros which expand to a
  66    a single compound statement in a portable way.  */
  67 #if defined (__GNUC__) && !defined (__STRICT_ANSI__) && !defined (__cplusplus)
  68 #  define LT_STMT_START        (void)(
  69 #  define LT_STMT_END          )
  70 #else
  71 #  if (defined (sun) || defined (__sun__))
  72 #    define LT_STMT_START      if (1)
  73 #    define LT_STMT_END        else (void)0
  74 #  else
  75 #    define LT_STMT_START      do
  76 #    define LT_STMT_END        while (0)
  77 #  endif
  78 #endif
  79
  80 /* LT_CONC creates a new concatenated symbol for the compiler
  81    in a portable way.  */
  82 #if defined(__STDC__) || defined(__cplusplus) || defined(_MSC_VER) || defined(_AIX)
  83 #  define LT_CONC(s,t)  s##t
  84 #else
  85 #  define LT_CONC(s,t)  s/**/t
  86 #endif
  87
  88 /* LT_STRLEN can be used safely on NULL pointers.  */
  89 #define LT_STRLEN(s)    (((s) && (s)[0]) ? strlen (s) : 0)
  90
  91
  92 \f
  93 /* --- WINDOWS SUPPORT --- */
  94
  95
  96 /* Canonicalise Windows and Cygwin recognition macros.  */
  97 #ifdef __CYGWIN32__
  98 #  ifndef __CYGWIN__
  99 #    define __CYGWIN__ __CYGWIN32__
 100 #  endif
 101 #endif
 102 #if defined(_WIN32) || defined(WIN32)
 103 #  ifndef __WINDOWS__
 104 #    ifdef _WIN32
 105 #      define __WINDOWS__ _WIN32
 106 #    else
 107 #      ifdef WIN32
 108 #        define __WINDOWS__ WIN32
 109 #      endif
 110 #    endif
 111 #  endif
 112 #endif
 113
 114
 115 #ifdef __WINDOWS__
 116 #  ifndef __CYGWIN__
 117 /* LT_DIRSEP_CHAR is accepted *in addition* to '/' as a directory
 118    separator when it is set. */
 119 #    define LT_DIRSEP_CHAR      '\\'
 120 #    define LT_PATHSEP_CHAR     ';'
 121 #  endif
 122 #endif
 123 #ifndef LT_PATHSEP_CHAR
 124 #  define LT_PATHSEP_CHAR       ':'
 125 #endif
 126
 127 /* DLL building support on win32 hosts;  mostly to workaround their
 128    ridiculous implementation of data symbol exporting. */
 129 #ifndef LT_SCOPE
 130 #  if defined(__WINDOWS__) || defined(__CYGWIN__)
 131 #    ifdef DLL_EXPORT           /* defined by libtool (if required) */
 132 #      define LT_SCOPE  __declspec(dllexport)
 133 #    endif
 134 #    ifdef LIBLTDL_DLL_IMPORT   /* define if linking with this dll */
 135        /* note: cygwin/mingw compilers can rely instead on auto-import */
 136 #      define LT_SCOPE  extern __declspec(dllimport)
 137 #    endif
 138 #  endif
 139 #  ifndef LT_SCOPE              /* static linking or !__WINDOWS__ */
 140 #    define LT_SCOPE    extern
 141 #  endif
 142 #endif
 143
 144
 145 #if defined(_MSC_VER) /* Visual Studio */
 146 #  define R_OK 4
 147 #endif
 148
 149
 150 \f
 151 /* --- DYNAMIC MODULE LOADING API --- */
 152
 153
 154 typedef struct lt_dlhandle_struct *lt_dlhandle; /* A loaded module.  */
 155
 156 /* Initialisation and finalisation functions for libltdl. */
 157 LT_SCOPE        int         lt_dlinit           LT_PARAMS((void));
 158 LT_SCOPE        int         lt_dlexit           LT_PARAMS((void));
 159
 160 /* Module search path manipulation.  */
 161 LT_SCOPE        int         lt_dladdsearchdir    LT_PARAMS((const char *search_dir));
 162 LT_SCOPE        int         lt_dlinsertsearchdir LT_PARAMS((const char *before,
 163                                                     const char *search_dir));
 164 LT_SCOPE        int         lt_dlsetsearchpath   LT_PARAMS((const char *search_path));
 165 LT_SCOPE        const char *lt_dlgetsearchpath   LT_PARAMS((void));
 166 LT_SCOPE        int         lt_dlforeachfile     LT_PARAMS((
 167                         const char *search_path,
 168                         int (*func) (const char *filename, lt_ptr data),
 169                         lt_ptr data));
 170
 171 /* Portable libltdl versions of the system dlopen() API. */
 172 LT_SCOPE        lt_dlhandle lt_dlopen           LT_PARAMS((const char *filename));
 173 LT_SCOPE        lt_dlhandle lt_dlopenext        LT_PARAMS((const char *filename));
 174 LT_SCOPE        lt_ptr      lt_dlsym            LT_PARAMS((lt_dlhandle handle,
 175                                                      const char *name));
 176 LT_SCOPE        const char *lt_dlerror          LT_PARAMS((void));
 177 LT_SCOPE        int         lt_dlclose          LT_PARAMS((lt_dlhandle handle));
 178
 179 /* Module residency management. */
 180 LT_SCOPE        int         lt_dlmakeresident   LT_PARAMS((lt_dlhandle handle));
 181 LT_SCOPE        int         lt_dlisresident     LT_PARAMS((lt_dlhandle handle));
 182
 183
 184
 185 \f
 186 /* --- MUTEX LOCKING --- */
 187
 188
 189 typedef void    lt_dlmutex_lock         LT_PARAMS((void));
 190 typedef void    lt_dlmutex_unlock       LT_PARAMS((void));
 191 typedef void    lt_dlmutex_seterror     LT_PARAMS((const char *errmsg));
 192 typedef const char *lt_dlmutex_geterror LT_PARAMS((void));
 193
 194 LT_SCOPE        int     lt_dlmutex_register     LT_PARAMS((lt_dlmutex_lock *lock,
 195                                             lt_dlmutex_unlock *unlock,
 196                                             lt_dlmutex_seterror *seterror,
 197                                             lt_dlmutex_geterror *geterror));
 198
 199
 200
 201 \f
 202 /* --- MEMORY HANDLING --- */
 203
 204
 205 /* By default, the realloc function pointer is set to our internal
 206    realloc implementation which iself uses lt_dlmalloc and lt_dlfree.
 207    libltdl relies on a featureful realloc, but if you are sure yours
 208    has the right semantics then you can assign it directly.  Generally,
 209    it is safe to assign just a malloc() and a free() function.  */
 210 LT_SCOPE  lt_ptr   (*lt_dlmalloc)       LT_PARAMS((size_t size));
 211 LT_SCOPE  lt_ptr   (*lt_dlrealloc)      LT_PARAMS((lt_ptr ptr, size_t size));
 212 LT_SCOPE  void     (*lt_dlfree)         LT_PARAMS((lt_ptr ptr));
 213
 214
 215
 216 \f
 217 /* --- PRELOADED MODULE SUPPORT --- */
 218
 219
 220 /* A preopened symbol. Arrays of this type comprise the exported
 221    symbols for a dlpreopened module. */
 222 typedef struct {
 223   const char *name;
 224   lt_ptr      address;
 225 } lt_dlsymlist;
 226
 227 LT_SCOPE        int     lt_dlpreload    LT_PARAMS((const lt_dlsymlist *preloaded));
 228 LT_SCOPE        int     lt_dlpreload_default
 229                                 LT_PARAMS((const lt_dlsymlist *preloaded));
 230
 231 #define LTDL_SET_PRELOADED_SYMBOLS()            LT_STMT_START{  \
 232         extern const lt_dlsymlist lt_preloaded_symbols[];               \
 233         lt_dlpreload_default(lt_preloaded_symbols);                     \
 234                                                 }LT_STMT_END
 235
 236
 237
 238 \f
 239 /* --- MODULE INFORMATION --- */
 240
 241
 242 /* Read only information pertaining to a loaded module. */
 243 typedef struct {
 244   char  *filename;              /* file name */
 245   char  *name;                  /* module name */
 246   int   ref_count;              /* number of times lt_dlopened minus
 247                                    number of times lt_dlclosed. */
 248 } lt_dlinfo;
 249
 250 LT_SCOPE        const lt_dlinfo *lt_dlgetinfo       LT_PARAMS((lt_dlhandle handle));
 251 LT_SCOPE        lt_dlhandle     lt_dlhandle_next    LT_PARAMS((lt_dlhandle place));
 252 LT_SCOPE        int             lt_dlforeach        LT_PARAMS((
 253                                 int (*func) (lt_dlhandle handle, lt_ptr data),
 254                                 lt_ptr data));
 255
 256 /* Associating user data with loaded modules. */
 257 typedef unsigned lt_dlcaller_id;
 258
 259 LT_SCOPE        lt_dlcaller_id  lt_dlcaller_register  LT_PARAMS((void));
 260 LT_SCOPE        lt_ptr          lt_dlcaller_set_data  LT_PARAMS((lt_dlcaller_id key,
 261                                                 lt_dlhandle handle,
 262                                                 lt_ptr data));
 263 LT_SCOPE        lt_ptr          lt_dlcaller_get_data  LT_PARAMS((lt_dlcaller_id key,
 264                                                 lt_dlhandle handle));
 265
 266
 267 \f
 268 /* --- USER MODULE LOADER API --- */
 269
 270
 271 typedef struct lt_dlloader      lt_dlloader;
 272 typedef lt_ptr                  lt_user_data;
 273 typedef lt_ptr                  lt_module;
 274
 275 /* Function pointer types for creating user defined module loaders. */
 276 typedef lt_module   lt_module_open      LT_PARAMS((lt_user_data loader_data,
 277                                             const char *filename));
 278 typedef int         lt_module_close     LT_PARAMS((lt_user_data loader_data,
 279                                             lt_module handle));
 280 typedef lt_ptr      lt_find_sym         LT_PARAMS((lt_user_data loader_data,
 281                                             lt_module handle,
 282                                             const char *symbol));
 283 typedef int         lt_dlloader_exit    LT_PARAMS((lt_user_data loader_data));
 284
 285 struct lt_user_dlloader {
 286   const char           *sym_prefix;
 287   lt_module_open       *module_open;
 288   lt_module_close      *module_close;
 289   lt_find_sym          *find_sym;
 290   lt_dlloader_exit     *dlloader_exit;
 291   lt_user_data          dlloader_data;
 292 };
 293
 294 LT_SCOPE        lt_dlloader    *lt_dlloader_next    LT_PARAMS((lt_dlloader *place));
 295 LT_SCOPE        lt_dlloader    *lt_dlloader_find    LT_PARAMS((
 296                                                 const char *loader_name));
 297 LT_SCOPE        const char     *lt_dlloader_name    LT_PARAMS((lt_dlloader *place));
 298 LT_SCOPE        lt_user_data   *lt_dlloader_data    LT_PARAMS((lt_dlloader *place));
 299 LT_SCOPE        int             lt_dlloader_add     LT_PARAMS((lt_dlloader *place,
 300                                 const struct lt_user_dlloader *dlloader,
 301                                 const char *loader_name));
 302 LT_SCOPE        int             lt_dlloader_remove  LT_PARAMS((
 303                                                 const char *loader_name));
 304
 305
 306 \f
 307 /* --- ERROR MESSAGE HANDLING --- */
 308
 309
 310 /* Defining error strings alongside their symbolic names in a macro in
 311    this way allows us to expand the macro in different contexts with
 312    confidence that the enumeration of symbolic names will map correctly
 313    onto the table of error strings.  */
 314 #define lt_dlerror_table                                                \
 315     LT_ERROR(UNKNOWN,               "unknown error")                    \
 316     LT_ERROR(DLOPEN_NOT_SUPPORTED,  "dlopen support not available")     \
 317     LT_ERROR(INVALID_LOADER,        "invalid loader")                   \
 318     LT_ERROR(INIT_LOADER,           "loader initialization failed")     \
 319     LT_ERROR(REMOVE_LOADER,         "loader removal failed")            \
 320     LT_ERROR(FILE_NOT_FOUND,        "file not found")                   \
 321     LT_ERROR(DEPLIB_NOT_FOUND,      "dependency library not found")     \
 322     LT_ERROR(NO_SYMBOLS,            "no symbols defined")               \
 323     LT_ERROR(CANNOT_OPEN,           "can't open the module")            \
 324     LT_ERROR(CANNOT_CLOSE,          "can't close the module")           \
 325     LT_ERROR(SYMBOL_NOT_FOUND,      "symbol not found")                 \
 326     LT_ERROR(NO_MEMORY,             "not enough memory")                \
 327     LT_ERROR(INVALID_HANDLE,        "invalid module handle")            \
 328     LT_ERROR(BUFFER_OVERFLOW,       "internal buffer overflow")         \
 329     LT_ERROR(INVALID_ERRORCODE,     "invalid errorcode")                \
 330     LT_ERROR(SHUTDOWN,              "library already shutdown")         \
 331     LT_ERROR(CLOSE_RESIDENT_MODULE, "can't close resident module")      \
 332     LT_ERROR(INVALID_MUTEX_ARGS,    "invalid mutex handler registration") \
 333     LT_ERROR(INVALID_POSITION,      "invalid search path insert position")
 334
 335 /* Enumerate the symbolic error names. */
 336 enum {
 337 #define LT_ERROR(name, diagnostic)      LT_CONC(LT_ERROR_, name),
 338         lt_dlerror_table
 339 #undef LT_ERROR
 340
 341         LT_ERROR_MAX
 342 };
 343
 344 /* These functions are only useful from inside custom module loaders. */
 345 LT_SCOPE        int     lt_dladderror   LT_PARAMS((const char *diagnostic));
 346 LT_SCOPE        int     lt_dlseterror   LT_PARAMS((int errorcode));
 347
 348
 349
 350 \f
 351 /* --- SOURCE COMPATIBILITY WITH OLD LIBLTDL --- */
 352
 353
 354 #ifdef LT_NON_POSIX_NAMESPACE
 355 #  define lt_ptr_t              lt_ptr
 356 #  define lt_module_t           lt_module
 357 #  define lt_module_open_t      lt_module_open
 358 #  define lt_module_close_t     lt_module_close
 359 #  define lt_find_sym_t         lt_find_sym
 360 #  define lt_dlloader_exit_t    lt_dlloader_exit
 361 #  define lt_dlloader_t         lt_dlloader
 362 #  define lt_dlloader_data_t    lt_user_data
 363 #endif
 364
 365 LT_END_C_DECLS
 366
 367 #endif /* !LTDL_H */