ltdl.h

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