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 #include <sys/types.h> /* for size_t declaration */ 32 33 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) 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 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 #ifdef __WINDOWS__ 115 # ifndef __CYGWIN__ 116 /* LT_DIRSEP_CHAR is accepted *in addition* to '/' as a directory 117 separator when it is set. */ 118 # define LT_DIRSEP_CHAR '\\' 119 # define LT_PATHSEP_CHAR ';' 120 # endif 121 #endif 122 #ifndef LT_PATHSEP_CHAR 123 # define LT_PATHSEP_CHAR ':' 124 #endif 125 126 /* DLL building support on win32 hosts; mostly to workaround their 127 ridiculous implementation of data symbol exporting. */ 128 #ifndef LT_SCOPE 129 # ifdef __WINDOWS__ 130 # ifdef DLL_EXPORT /* defined by libtool (if required) */ 131 # define LT_SCOPE __declspec(dllexport) 132 # endif 133 # ifdef LIBLTDL_DLL_IMPORT /* define if linking with this dll */ 134 # define LT_SCOPE extern __declspec(dllimport) 135 # endif 136 # endif 137 # ifndef LT_SCOPE /* static linking or !__WINDOWS__ */ 138 # define LT_SCOPE extern 139 # endif 140 #endif 141 142 143 144 145 /* --- DYNAMIC MODULE LOADING API --- */ 146 147 148 typedef struct lt_dlhandle_struct *lt_dlhandle; /* A loaded module. */ 149 150 /* Initialisation and finalisation functions for libltdl. */ 151 extern int lt_dlinit LT_PARAMS((void)); 152 extern int lt_dlexit LT_PARAMS((void)); 153 154 /* Module search path manipulation. */ 155 extern int lt_dladdsearchdir LT_PARAMS((const char *search_dir)); 156 extern int lt_dlinsertsearchdir LT_PARAMS((const char *before, 157 const char *search_dir)); 158 extern int lt_dlsetsearchpath LT_PARAMS((const char *search_path)); 159 extern const char *lt_dlgetsearchpath LT_PARAMS((void)); 160 extern int lt_dlforeachfile LT_PARAMS(( 161 const char *search_path, 162 int (*func) (const char *filename, lt_ptr data), 163 lt_ptr data)); 164 165 /* Portable libltdl versions of the system dlopen() API. */ 166 extern lt_dlhandle lt_dlopen LT_PARAMS((const char *filename)); 167 extern lt_dlhandle lt_dlopenext LT_PARAMS((const char *filename)); 168 extern lt_ptr lt_dlsym LT_PARAMS((lt_dlhandle handle, 169 const char *name)); 170 extern const char *lt_dlerror LT_PARAMS((void)); 171 extern int lt_dlclose LT_PARAMS((lt_dlhandle handle)); 172 173 /* Module residency management. */ 174 extern int lt_dlmakeresident LT_PARAMS((lt_dlhandle handle)); 175 extern int lt_dlisresident LT_PARAMS((lt_dlhandle handle)); 176 177 178 179 180 /* --- MUTEX LOCKING --- */ 181 182 183 typedef void lt_dlmutex_lock LT_PARAMS((void)); 184 typedef void lt_dlmutex_unlock LT_PARAMS((void)); 185 typedef void lt_dlmutex_seterror LT_PARAMS((const char *errmsg)); 186 typedef const char *lt_dlmutex_geterror LT_PARAMS((void)); 187 188 extern int lt_dlmutex_register LT_PARAMS((lt_dlmutex_lock *lock, 189 lt_dlmutex_unlock *unlock, 190 lt_dlmutex_seterror *seterror, 191 lt_dlmutex_geterror *geterror)); 192 193 194 195 196 /* --- MEMORY HANDLING --- */ 197 198 199 /* By default, the realloc function pointer is set to our internal 200 realloc implementation which iself uses lt_dlmalloc and lt_dlfree. 201 libltdl relies on a featureful realloc, but if you are sure yours 202 has the right semantics then you can assign it directly. Generally, 203 it is safe to assign just a malloc() and a free() function. */ 204 LT_SCOPE lt_ptr (*lt_dlmalloc) LT_PARAMS((size_t size)); 205 LT_SCOPE lt_ptr (*lt_dlrealloc) LT_PARAMS((lt_ptr ptr, size_t size)); 206 LT_SCOPE void (*lt_dlfree) LT_PARAMS((lt_ptr ptr)); 207 208 209 210 211 /* --- PRELOADED MODULE SUPPORT --- */ 212 213 214 /* A preopened symbol. Arrays of this type comprise the exported 215 symbols for a dlpreopened module. */ 216 typedef struct { 217 const char *name; 218 lt_ptr address; 219 } lt_dlsymlist; 220 221 extern int lt_dlpreload LT_PARAMS((const lt_dlsymlist *preloaded)); 222 extern int lt_dlpreload_default 223 LT_PARAMS((const lt_dlsymlist *preloaded)); 224 225 #define LTDL_SET_PRELOADED_SYMBOLS() LT_STMT_START{ \ 226 extern const lt_dlsymlist lt_preloaded_symbols[]; \ 227 lt_dlpreload_default(lt_preloaded_symbols); \ 228 }LT_STMT_END 229 230 231 232 233 /* --- MODULE INFORMATION --- */ 234 235 236 /* Read only information pertaining to a loaded module. */ 237 typedef struct { 238 char *filename; /* file name */ 239 char *name; /* module name */ 240 int ref_count; /* number of times lt_dlopened minus 241 number of times lt_dlclosed. */ 242 } lt_dlinfo; 243 244 extern const lt_dlinfo *lt_dlgetinfo LT_PARAMS((lt_dlhandle handle)); 245 extern lt_dlhandle lt_dlhandle_next LT_PARAMS((lt_dlhandle place)); 246 extern int lt_dlforeach LT_PARAMS(( 247 int (*func) (lt_dlhandle handle, lt_ptr data), 248 lt_ptr data)); 249 250 /* Associating user data with loaded modules. */ 251 typedef unsigned lt_dlcaller_id; 252 253 extern lt_dlcaller_id lt_dlcaller_register LT_PARAMS((void)); 254 extern lt_ptr lt_dlcaller_set_data LT_PARAMS((lt_dlcaller_id key, 255 lt_dlhandle handle, 256 lt_ptr data)); 257 extern lt_ptr lt_dlcaller_get_data LT_PARAMS((lt_dlcaller_id key, 258 lt_dlhandle handle)); 259 260 261 262 /* --- USER MODULE LOADER API --- */ 263 264 265 typedef struct lt_dlloader lt_dlloader; 266 typedef lt_ptr lt_user_data; 267 typedef lt_ptr lt_module; 268 269 /* Function pointer types for creating user defined module loaders. */ 270 typedef lt_module lt_module_open LT_PARAMS((lt_user_data loader_data, 271 const char *filename)); 272 typedef int lt_module_close LT_PARAMS((lt_user_data loader_data, 273 lt_module handle)); 274 typedef lt_ptr lt_find_sym LT_PARAMS((lt_user_data loader_data, 275 lt_module handle, 276 const char *symbol)); 277 typedef int lt_dlloader_exit LT_PARAMS((lt_user_data loader_data)); 278 279 struct lt_user_dlloader { 280 const char *sym_prefix; 281 lt_module_open *module_open; 282 lt_module_close *module_close; 283 lt_find_sym *find_sym; 284 lt_dlloader_exit *dlloader_exit; 285 lt_user_data dlloader_data; 286 }; 287 288 extern lt_dlloader *lt_dlloader_next LT_PARAMS((lt_dlloader *place)); 289 extern lt_dlloader *lt_dlloader_find LT_PARAMS(( 290 const char *loader_name)); 291 extern const char *lt_dlloader_name LT_PARAMS((lt_dlloader *place)); 292 extern lt_user_data *lt_dlloader_data LT_PARAMS((lt_dlloader *place)); 293 extern int lt_dlloader_add LT_PARAMS((lt_dlloader *place, 294 const struct lt_user_dlloader *dlloader, 295 const char *loader_name)); 296 extern int lt_dlloader_remove LT_PARAMS(( 297 const char *loader_name)); 298 299 300 301 /* --- ERROR MESSAGE HANDLING --- */ 302 303 304 /* Defining error strings alongside their symbolic names in a macro in 305 this way allows us to expand the macro in different contexts with 306 confidence that the enumeration of symbolic names will map correctly 307 onto the table of error strings. */ 308 #define lt_dlerror_table \ 309 LT_ERROR(UNKNOWN, "unknown error") \ 310 LT_ERROR(DLOPEN_NOT_SUPPORTED, "dlopen support not available") \ 311 LT_ERROR(INVALID_LOADER, "invalid loader") \ 312 LT_ERROR(INIT_LOADER, "loader initialization failed") \ 313 LT_ERROR(REMOVE_LOADER, "loader removal failed") \ 314 LT_ERROR(FILE_NOT_FOUND, "file not found") \ 315 LT_ERROR(DEPLIB_NOT_FOUND, "dependency library not found") \ 316 LT_ERROR(NO_SYMBOLS, "no symbols defined") \ 317 LT_ERROR(CANNOT_OPEN, "can't open the module") \ 318 LT_ERROR(CANNOT_CLOSE, "can't close the module") \ 319 LT_ERROR(SYMBOL_NOT_FOUND, "symbol not found") \ 320 LT_ERROR(NO_MEMORY, "not enough memory") \ 321 LT_ERROR(INVALID_HANDLE, "invalid module handle") \ 322 LT_ERROR(BUFFER_OVERFLOW, "internal buffer overflow") \ 323 LT_ERROR(INVALID_ERRORCODE, "invalid errorcode") \ 324 LT_ERROR(SHUTDOWN, "library already shutdown") \ 325 LT_ERROR(CLOSE_RESIDENT_MODULE, "can't close resident module") \ 326 LT_ERROR(INVALID_MUTEX_ARGS, "invalid mutex handler registration") \ 327 LT_ERROR(INVALID_POSITION, "invalid search path insert position") 328 329 /* Enumerate the symbolic error names. */ 330 enum { 331 #define LT_ERROR(name, diagnostic) LT_CONC(LT_ERROR_, name), 332 lt_dlerror_table 333 #undef LT_ERROR 334 335 LT_ERROR_MAX 336 }; 337 338 /* These functions are only useful from inside custom module loaders. */ 339 extern int lt_dladderror LT_PARAMS((const char *diagnostic)); 340 extern int lt_dlseterror LT_PARAMS((int errorcode)); 341 342 343 344 345 /* --- SOURCE COMPATIBILITY WITH OLD LIBLTDL --- */ 346 347 348 #ifdef LT_NON_POSIX_NAMESPACE 349 # define lt_ptr_t lt_ptr 350 # define lt_module_t lt_module 351 # define lt_module_open_t lt_module_open 352 # define lt_module_close_t lt_module_close 353 # define lt_find_sym_t lt_find_sym 354 # define lt_dlloader_exit_t lt_dlloader_exit 355 # define lt_dlloader_t lt_dlloader 356 # define lt_dlloader_data_t lt_user_data 357 #endif 358 359 LT_END_C_DECLS 360 361 #endif /* !LTDL_H */ 362