libjava/libltdl/ltdl.h

   1 /* ltdl.h -- generic dlopen functions
   2    Copyright (C) 1998-2000 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., 59 Temple Place, Suite 330, Boston, MA
  24 02111-1307  USA
  25 */
  26
  27 /* Only include this header file once. */
  28 #ifndef _LTDL_H_
  29 #define _LTDL_H_ 1
  30
  31 /* Canonicalise Windows and Cygwin recognition macros.  */
  32 #ifdef __CYGWIN32__
  33 #  ifndef __CYGWIN__
  34 #    define __CYGWIN__ __CYGWIN32__
  35 #  endif
  36 #endif
  37 #ifdef _WIN32
  38 #  ifndef WIN32
  39 #    define WIN32 _WIN32
  40 #  endif
  41 #endif
  42
  43 /* __BEGIN_DECLS should be used at the beginning of your declarations,
  44    so that C++ compilers don't mangle their names.  Use __END_DECLS at
  45    the end of C declarations. */
  46 #undef __BEGIN_DECLS
  47 #undef __END_DECLS
  48 #ifdef __cplusplus
  49 # define __BEGIN_DECLS extern "C" {
  50 # define __END_DECLS }
  51 #else
  52 # define __BEGIN_DECLS /* empty */
  53 # define __END_DECLS /* empty */
  54 #endif
  55
  56 /* LTDL_PARAMS is a macro used to wrap function prototypes, so that compilers
  57    that don't understand ANSI C prototypes still work, and ANSI C
  58    compilers can issue warnings about type mismatches. */
  59 #undef LTDL_PARAMS
  60 #undef lt_ptr_t
  61 #if defined (__STDC__) || defined (_AIX) || (defined (__mips) && defined (_SYSTYPE_SVR4)) || defined(WIN32) || defined(__cplusplus)
  62 # define LTDL_PARAMS(protos)    protos
  63 # define lt_ptr_t       void*
  64 #else
  65 # define LTDL_PARAMS(protos)    ()
  66 # define lt_ptr_t       char*
  67 #endif
  68
  69 /* LTDL_STMT_START/END are used to create macros which expand to a
  70    a single compound statement in a portable way. */
  71 #undef LTDL_STMT_START
  72 #undef LTDL_STMT_END
  73 #if defined (__GNUC__) && !defined (__STRICT_ANSI__) && !defined (__cplusplus)
  74 #  define LTDL_STMT_START        (void)(
  75 #  define LTDL_STMT_END          )
  76 #else
  77 #  if (defined (sun) || defined (__sun__))
  78 #    define LTDL_STMT_START      if (1)
  79 #    define LTDL_STMT_END        else (void)0
  80 #  else
  81 #    define LTDL_STMT_START      do
  82 #    define LTDL_STMT_END        while (0)
  83 #  endif
  84 #endif
  85
  86 #ifdef WIN32
  87 #  ifndef __CYGWIN__
  88 /* LTDL_DIRSEP_CHAR is accepted *in addition* to '/' as a directory
  89    separator when it is set. */
  90 #    define LTDL_DIRSEP_CHAR    '\\'
  91 #    define LTDL_PATHSEP_CHAR   ';'
  92 #  endif
  93 #endif
  94 #ifndef LTDL_PATHSEP_CHAR
  95 #  define LTDL_PATHSEP_CHAR     ':'
  96 #endif
  97
  98 /* DLL building support on win32 hosts;  mostly to workaround their
  99    ridiculous implementation of data symbol exporting. */
 100 #ifndef LTDL_SCOPE
 101 #  ifdef _WIN32
 102 #    ifdef DLL_EXPORT           /* defined by libtool (if required) */
 103 #      define LTDL_SCOPE        __declspec(dllexport)
 104 #    endif
 105 #    ifdef LIBLTDL_DLL_IMPORT   /* define if linking with this dll */
 106 #      define LTDL_SCOPE        extern __declspec(dllimport)
 107 #    endif
 108 #  endif
 109 #  ifndef LTDL_SCOPE            /* static linking or !_WIN32 */
 110 #    define LTDL_SCOPE  extern
 111 #  endif
 112 #endif
 113
 114 #include <stdlib.h>
 115
 116 /* Defining error strings alongside their symbolic names in a macro in
 117    this way allows us to expand the macro in different contexts with
 118    confidence that the enumeration of symbolic names will map correctly
 119    onto the table of error strings.  */
 120 #define ltdl_error_table                                                \
 121         LTDL_ERROR(UNKNOWN, "unknown error")                            \
 122         LTDL_ERROR(DLOPEN_NOT_SUPPORTED, "dlopen support not available")\
 123         LTDL_ERROR(INVALID_LOADER, "invalid loader")                    \
 124         LTDL_ERROR(INIT_LOADER, "loader initialization failed")         \
 125         LTDL_ERROR(REMOVE_LOADER, "loader removal failed")              \
 126         LTDL_ERROR(FILE_NOT_FOUND, "file not found")                    \
 127         LTDL_ERROR(DEPLIB_NOT_FOUND, "dependency library not found")    \
 128         LTDL_ERROR(NO_SYMBOLS, "no symbols defined")                    \
 129         LTDL_ERROR(CANNOT_OPEN, "can't open the module")                \
 130         LTDL_ERROR(CANNOT_CLOSE, "can't close the module")              \
 131         LTDL_ERROR(SYMBOL_NOT_FOUND, "symbol not found")                \
 132         LTDL_ERROR(NO_MEMORY, "not enough memory")                      \
 133         LTDL_ERROR(INVALID_HANDLE, "invalid module handle")             \
 134         LTDL_ERROR(BUFFER_OVERFLOW, "internal buffer overflow")         \
 135         LTDL_ERROR(INVALID_ERRORCODE, "invalid errorcode")              \
 136         LTDL_ERROR(SHUTDOWN, "library already shutdown")
 137
 138 /* Enumerate the symbolic error names. */
 139 #if defined(__STDC__) || defined(__cplusplus)
 140 #  define LTDL_ERROR(name, diagnostic)  LTDL_ERROR_##name,
 141 #else
 142 #  define LTDL_ERROR(name, diagnostic)  LTDL_ERROR_/**/name,
 143 #endif
 144 enum {
 145         ltdl_error_table
 146         LTDL_ERROR_MAX
 147 };
 148 #undef LTDL_ERROR
 149
 150 /* An opaque handle for a successfully lt_dlopened module instance. */
 151 #ifdef _LTDL_COMPILE_
 152 typedef struct lt_dlhandle_t *lt_dlhandle;
 153 #else
 154 typedef lt_ptr_t lt_dlhandle;
 155 #endif
 156
 157 /* A preopened symbol. Arrays of this type comprise the exported
 158    symbols for a dlpreopened module. */
 159 typedef struct {
 160         const char *name;
 161         lt_ptr_t address;
 162 } lt_dlsymlist;
 163
 164 /* Read only information pertaining to a loaded module. */
 165 typedef struct {
 166         char    *filename;      /* file name */
 167         char    *name;          /* module name */
 168         int     ref_count;      /* number of times lt_dlopened minus
 169                                    number of times lt_dlclosed. */
 170 } lt_dlinfo;
 171
 172 /* An opaque handle for a module loaded by a system call.  This is only
 173    used internally by ltdl loaders, and by user module loaders. */
 174 typedef lt_ptr_t lt_module_t;
 175
 176 /* An opaque handle for a module loader.  */
 177 #ifdef _LTDL_COMPILE_
 178 typedef struct lt_dlloader_t lt_dlloader_t;
 179 #else
 180 typedef lt_ptr_t lt_dlloader_t;
 181 #endif
 182
 183 typedef lt_ptr_t lt_dlloader_data_t;
 184
 185 /* Function pointer types for creating user defined module loaders. */
 186 typedef lt_module_t lt_module_open_t LTDL_PARAMS((lt_dlloader_data_t loader_data, const char *filename));
 187 typedef int lt_module_close_t LTDL_PARAMS((lt_dlloader_data_t loader_data, lt_module_t handle));
 188 typedef lt_ptr_t lt_find_sym_t LTDL_PARAMS((lt_dlloader_data_t loader_data, lt_module_t handle, const char *symbol));
 189 typedef int lt_dlloader_exit_t LTDL_PARAMS((lt_dlloader_data_t loader_data));
 190
 191 __BEGIN_DECLS
 192 /* Initialisation and finalisation functions for libltdl. */
 193 extern int lt_dlinit LTDL_PARAMS((void));
 194 extern int lt_dlexit LTDL_PARAMS((void));
 195
 196 /* Module search path manipultation.  */
 197 extern int lt_dladdsearchdir LTDL_PARAMS((const char *search_dir));
 198 extern int lt_dlsetsearchpath LTDL_PARAMS((const char *search_path));
 199 extern const char *lt_dlgetsearchpath LTDL_PARAMS((void));
 200
 201 /* Portable libltdl versions of the system dlopen() API. */
 202 extern lt_dlhandle lt_dlopen LTDL_PARAMS((const char *filename));
 203 extern lt_dlhandle lt_dlopenext LTDL_PARAMS((const char *filename));
 204 extern lt_ptr_t lt_dlsym LTDL_PARAMS((lt_dlhandle handle, const char *name));
 205 extern const char *lt_dlerror LTDL_PARAMS((void));
 206 extern int lt_dlclose LTDL_PARAMS((lt_dlhandle handle));
 207
 208 /* Support for preloaded modules through lt_dlopen() API. */
 209 extern int lt_dlpreload LTDL_PARAMS((const lt_dlsymlist *preloaded));
 210 extern int lt_dlpreload_default LTDL_PARAMS((const lt_dlsymlist *preloaded));
 211
 212 #define LTDL_SET_PRELOADED_SYMBOLS()            LTDL_STMT_START{        \
 213         extern const lt_dlsymlist lt_preloaded_symbols[];               \
 214         lt_dlpreload_default(lt_preloaded_symbols);                     \
 215                                                 }LTDL_STMT_END
 216
 217 /* Managing user data associated with a loaded modules.  */
 218 extern const lt_dlinfo *lt_dlgetinfo LTDL_PARAMS((lt_dlhandle handle));
 219 extern int lt_dlforeach LTDL_PARAMS((
 220                 int (*func)(lt_dlhandle handle, lt_ptr_t data), lt_ptr_t data));
 221
 222 /* User module loader API. */
 223 struct lt_user_dlloader {
 224         const char *sym_prefix;
 225         lt_module_open_t *module_open;
 226         lt_module_close_t *module_close;
 227         lt_find_sym_t *find_sym;
 228         lt_dlloader_exit_t *dlloader_exit;
 229         lt_dlloader_data_t dlloader_data;
 230 };
 231
 232 extern lt_dlloader_t *lt_dlloader_next LTDL_PARAMS((lt_dlloader_t *place));
 233 extern lt_dlloader_t *lt_dlloader_find LTDL_PARAMS((const char *loader_name));
 234 extern const char *lt_dlloader_name LTDL_PARAMS((lt_dlloader_t *place));
 235 extern lt_dlloader_data_t *lt_dlloader_data LTDL_PARAMS((lt_dlloader_t *place));
 236 extern lt_dlloader_t *lt_find_dlloader LTDL_PARAMS((const char *loader_name));
 237 extern int lt_dlloader_add LTDL_PARAMS((lt_dlloader_t *place, const struct lt_user_dlloader *dlloader, const char *loader_name));
 238 extern int lt_dlloader_remove LTDL_PARAMS((const char *loader_name));
 239
 240 /* Integrated lt_dlerror() messages for user loaders. */
 241 extern int lt_dladderror LTDL_PARAMS((const char *diagnostic));
 242 extern int lt_dlseterror LTDL_PARAMS((int errorcode));
 243
 244 /* Pointers to memory management functions to be used by libltdl. */
 245 LTDL_SCOPE lt_ptr_t (*lt_dlmalloc)LTDL_PARAMS((size_t size));
 246 LTDL_SCOPE void (*lt_dlfree)LTDL_PARAMS((lt_ptr_t ptr));
 247
 248 __END_DECLS
 249
 250 #endif /* !_LTDL_H_ */