LLVM API Documentation
00001 /* ltdl.h -- generic dlopen functions 00002 Copyright (C) 1998-2000 Free Software Foundation, Inc. 00003 Originally by Thomas Tanner <tanner@ffii.org> 00004 This file is part of GNU Libtool. 00005 00006 This library is free software; you can redistribute it and/or 00007 modify it under the terms of the GNU Lesser General Public 00008 License as published by the Free Software Foundation; either 00009 version 2 of the License, or (at your option) any later version. 00010 00011 As a special exception to the GNU Lesser General Public License, 00012 if you distribute this file as part of a program or library that 00013 is built using GNU libtool, you may include it under the same 00014 distribution terms that you use for the rest of that program. 00015 00016 This library is distributed in the hope that it will be useful, 00017 but WITHOUT ANY WARRANTY; without even the implied warranty of 00018 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 00019 Lesser General Public License for more details. 00020 00021 You should have received a copy of the GNU Lesser General Public 00022 License along with this library; if not, write to the Free 00023 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 00024 02111-1307 USA 00025 */ 00026 00027 /* Only include this header file once. */ 00028 #ifndef LTDL_H 00029 #define LTDL_H 1 00030 00031 #include <sys/types.h> /* for size_t declaration */ 00032 00033 00034 /* --- MACROS FOR PORTABILITY --- */ 00035 00036 00037 /* Saves on those hard to debug '\0' typos.... */ 00038 #define LT_EOS_CHAR '\0' 00039 00040 /* LTDL_BEGIN_C_DECLS should be used at the beginning of your declarations, 00041 so that C++ compilers don't mangle their names. Use LTDL_END_C_DECLS at 00042 the end of C declarations. */ 00043 #ifdef __cplusplus 00044 # define LT_BEGIN_C_DECLS extern "C" { 00045 # define LT_END_C_DECLS } 00046 #else 00047 # define LT_BEGIN_C_DECLS /* empty */ 00048 # define LT_END_C_DECLS /* empty */ 00049 #endif 00050 00051 LT_BEGIN_C_DECLS 00052 00053 00054 /* LT_PARAMS is a macro used to wrap function prototypes, so that compilers 00055 that don't understand ANSI C prototypes still work, and ANSI C 00056 compilers can issue warnings about type mismatches. */ 00057 #if defined (__STDC__) || defined (_AIX) || (defined (__mips) && defined (_SYSTYPE_SVR4)) || defined(WIN32) || defined(__cplusplus) 00058 # define LT_PARAMS(protos) protos 00059 # define lt_ptr void* 00060 #else 00061 # define LT_PARAMS(protos) () 00062 # define lt_ptr char* 00063 #endif 00064 00065 /* LT_STMT_START/END are used to create macros which expand to a 00066 a single compound statement in a portable way. */ 00067 #if defined (__GNUC__) && !defined (__STRICT_ANSI__) && !defined (__cplusplus) 00068 # define LT_STMT_START (void)( 00069 # define LT_STMT_END ) 00070 #else 00071 # if (defined (sun) || defined (__sun__)) 00072 # define LT_STMT_START if (1) 00073 # define LT_STMT_END else (void)0 00074 # else 00075 # define LT_STMT_START do 00076 # define LT_STMT_END while (0) 00077 # endif 00078 #endif 00079 00080 /* LT_CONC creates a new concatenated symbol for the compiler 00081 in a portable way. */ 00082 #if defined(__STDC__) || defined(__cplusplus) || defined(_MSC_VER) 00083 # define LT_CONC(s,t) s##t 00084 #else 00085 # define LT_CONC(s,t) s/**/t 00086 #endif 00087 00088 /* LT_STRLEN can be used safely on NULL pointers. */ 00089 #define LT_STRLEN(s) (((s) && (s)[0]) ? strlen (s) : 0) 00090 00091 00092 00093 /* --- WINDOWS SUPPORT --- */ 00094 00095 00096 /* Canonicalise Windows and Cygwin recognition macros. */ 00097 #ifdef __CYGWIN32__ 00098 # ifndef __CYGWIN__ 00099 # define __CYGWIN__ __CYGWIN32__ 00100 # endif 00101 #endif 00102 #if defined(_WIN32) || defined(WIN32) 00103 # ifndef __WINDOWS__ 00104 # ifdef _WIN32 00105 # define __WINDOWS__ _WIN32 00106 # else 00107 # ifdef WIN32 00108 # define __WINDOWS__ WIN32 00109 # endif 00110 # endif 00111 # endif 00112 #endif 00113 00114 00115 #ifdef __WINDOWS__ 00116 # ifndef __CYGWIN__ 00117 /* LT_DIRSEP_CHAR is accepted *in addition* to '/' as a directory 00118 separator when it is set. */ 00119 # define LT_DIRSEP_CHAR '\\' 00120 # define LT_PATHSEP_CHAR ';' 00121 # endif 00122 #endif 00123 #ifndef LT_PATHSEP_CHAR 00124 # define LT_PATHSEP_CHAR ':' 00125 #endif 00126 00127 /* DLL building support on win32 hosts; mostly to workaround their 00128 ridiculous implementation of data symbol exporting. */ 00129 #ifndef LT_SCOPE 00130 # ifdef __WINDOWS__ 00131 # ifdef DLL_EXPORT /* defined by libtool (if required) */ 00132 # define LT_SCOPE __declspec(dllexport) 00133 # endif 00134 # ifdef LIBLTDL_DLL_IMPORT /* define if linking with this dll */ 00135 # define LT_SCOPE extern __declspec(dllimport) 00136 # endif 00137 # endif 00138 # ifndef LT_SCOPE /* static linking or !__WINDOWS__ */ 00139 # define LT_SCOPE extern 00140 # endif 00141 #endif 00142 00143 00144 #if defined(_MSC_VER) /* Visual Studio */ 00145 # define R_OK 4 00146 #endif 00147 00148 00149 00150 /* --- DYNAMIC MODULE LOADING API --- */ 00151 00152 00153 typedef struct lt_dlhandle_struct *lt_dlhandle; /* A loaded module. */ 00154 00155 /* Initialisation and finalisation functions for libltdl. */ 00156 LT_SCOPE int lt_dlinit LT_PARAMS((void)); 00157 LT_SCOPE int lt_dlexit LT_PARAMS((void)); 00158 00159 /* Module search path manipulation. */ 00160 LT_SCOPE int lt_dladdsearchdir LT_PARAMS((const char *search_dir)); 00161 LT_SCOPE int lt_dlinsertsearchdir LT_PARAMS((const char *before, 00162 const char *search_dir)); 00163 LT_SCOPE int lt_dlsetsearchpath LT_PARAMS((const char *search_path)); 00164 LT_SCOPE const char *lt_dlgetsearchpath LT_PARAMS((void)); 00165 LT_SCOPE int lt_dlforeachfile LT_PARAMS(( 00166 const char *search_path, 00167 int (*func) (const char *filename, lt_ptr data), 00168 lt_ptr data)); 00169 00170 /* Portable libltdl versions of the system dlopen() API. */ 00171 LT_SCOPE lt_dlhandle lt_dlopen LT_PARAMS((const char *filename)); 00172 LT_SCOPE lt_dlhandle lt_dlopenext LT_PARAMS((const char *filename)); 00173 LT_SCOPE lt_ptr lt_dlsym LT_PARAMS((lt_dlhandle handle, 00174 const char *name)); 00175 LT_SCOPE const char *lt_dlerror LT_PARAMS((void)); 00176 LT_SCOPE int lt_dlclose LT_PARAMS((lt_dlhandle handle)); 00177 00178 /* Module residency management. */ 00179 LT_SCOPE int lt_dlmakeresident LT_PARAMS((lt_dlhandle handle)); 00180 LT_SCOPE int lt_dlisresident LT_PARAMS((lt_dlhandle handle)); 00181 00182 00183 00184 00185 /* --- MUTEX LOCKING --- */ 00186 00187 00188 typedef void lt_dlmutex_lock LT_PARAMS((void)); 00189 typedef void lt_dlmutex_unlock LT_PARAMS((void)); 00190 typedef void lt_dlmutex_seterror LT_PARAMS((const char *errmsg)); 00191 typedef const char *lt_dlmutex_geterror LT_PARAMS((void)); 00192 00193 LT_SCOPE int lt_dlmutex_register LT_PARAMS((lt_dlmutex_lock *lock, 00194 lt_dlmutex_unlock *unlock, 00195 lt_dlmutex_seterror *seterror, 00196 lt_dlmutex_geterror *geterror)); 00197 00198 00199 00200 00201 /* --- MEMORY HANDLING --- */ 00202 00203 00204 /* By default, the realloc function pointer is set to our internal 00205 realloc implementation which iself uses lt_dlmalloc and lt_dlfree. 00206 libltdl relies on a featureful realloc, but if you are sure yours 00207 has the right semantics then you can assign it directly. Generally, 00208 it is safe to assign just a malloc() and a free() function. */ 00209 LT_SCOPE lt_ptr (*lt_dlmalloc) LT_PARAMS((size_t size)); 00210 LT_SCOPE lt_ptr (*lt_dlrealloc) LT_PARAMS((lt_ptr ptr, size_t size)); 00211 LT_SCOPE void (*lt_dlfree) LT_PARAMS((lt_ptr ptr)); 00212 00213 00214 00215 00216 /* --- PRELOADED MODULE SUPPORT --- */ 00217 00218 00219 /* A preopened symbol. Arrays of this type comprise the exported 00220 symbols for a dlpreopened module. */ 00221 typedef struct { 00222 const char *name; 00223 lt_ptr address; 00224 } lt_dlsymlist; 00225 00226 LT_SCOPE int lt_dlpreload LT_PARAMS((const lt_dlsymlist *preloaded)); 00227 LT_SCOPE int lt_dlpreload_default 00228 LT_PARAMS((const lt_dlsymlist *preloaded)); 00229 00230 #define LTDL_SET_PRELOADED_SYMBOLS() LT_STMT_START{ \ 00231 extern const lt_dlsymlist lt_preloaded_symbols[]; \ 00232 lt_dlpreload_default(lt_preloaded_symbols); \ 00233 }LT_STMT_END 00234 00235 00236 00237 00238 /* --- MODULE INFORMATION --- */ 00239 00240 00241 /* Read only information pertaining to a loaded module. */ 00242 typedef struct { 00243 char *filename; /* file name */ 00244 char *name; /* module name */ 00245 int ref_count; /* number of times lt_dlopened minus 00246 number of times lt_dlclosed. */ 00247 } lt_dlinfo; 00248 00249 LT_SCOPE const lt_dlinfo *lt_dlgetinfo LT_PARAMS((lt_dlhandle handle)); 00250 LT_SCOPE lt_dlhandle lt_dlhandle_next LT_PARAMS((lt_dlhandle place)); 00251 LT_SCOPE int lt_dlforeach LT_PARAMS(( 00252 int (*func) (lt_dlhandle handle, lt_ptr data), 00253 lt_ptr data)); 00254 00255 /* Associating user data with loaded modules. */ 00256 typedef unsigned lt_dlcaller_id; 00257 00258 LT_SCOPE lt_dlcaller_id lt_dlcaller_register LT_PARAMS((void)); 00259 LT_SCOPE lt_ptr lt_dlcaller_set_data LT_PARAMS((lt_dlcaller_id key, 00260 lt_dlhandle handle, 00261 lt_ptr data)); 00262 LT_SCOPE lt_ptr lt_dlcaller_get_data LT_PARAMS((lt_dlcaller_id key, 00263 lt_dlhandle handle)); 00264 00265 00266 00267 /* --- USER MODULE LOADER API --- */ 00268 00269 00270 typedef struct lt_dlloader lt_dlloader; 00271 typedef lt_ptr lt_user_data; 00272 typedef lt_ptr lt_module; 00273 00274 /* Function pointer types for creating user defined module loaders. */ 00275 typedef lt_module lt_module_open LT_PARAMS((lt_user_data loader_data, 00276 const char *filename)); 00277 typedef int lt_module_close LT_PARAMS((lt_user_data loader_data, 00278 lt_module handle)); 00279 typedef lt_ptr lt_find_sym LT_PARAMS((lt_user_data loader_data, 00280 lt_module handle, 00281 const char *symbol)); 00282 typedef int lt_dlloader_exit LT_PARAMS((lt_user_data loader_data)); 00283 00284 struct lt_user_dlloader { 00285 const char *sym_prefix; 00286 lt_module_open *module_open; 00287 lt_module_close *module_close; 00288 lt_find_sym *find_sym; 00289 lt_dlloader_exit *dlloader_exit; 00290 lt_user_data dlloader_data; 00291 }; 00292 00293 LT_SCOPE lt_dlloader *lt_dlloader_next LT_PARAMS((lt_dlloader *place)); 00294 LT_SCOPE lt_dlloader *lt_dlloader_find LT_PARAMS(( 00295 const char *loader_name)); 00296 LT_SCOPE const char *lt_dlloader_name LT_PARAMS((lt_dlloader *place)); 00297 LT_SCOPE lt_user_data *lt_dlloader_data LT_PARAMS((lt_dlloader *place)); 00298 LT_SCOPE int lt_dlloader_add LT_PARAMS((lt_dlloader *place, 00299 const struct lt_user_dlloader *dlloader, 00300 const char *loader_name)); 00301 LT_SCOPE int lt_dlloader_remove LT_PARAMS(( 00302 const char *loader_name)); 00303 00304 00305 00306 /* --- ERROR MESSAGE HANDLING --- */ 00307 00308 00309 /* Defining error strings alongside their symbolic names in a macro in 00310 this way allows us to expand the macro in different contexts with 00311 confidence that the enumeration of symbolic names will map correctly 00312 onto the table of error strings. */ 00313 #define lt_dlerror_table \ 00314 LT_ERROR(UNKNOWN, "unknown error") \ 00315 LT_ERROR(DLOPEN_NOT_SUPPORTED, "dlopen support not available") \ 00316 LT_ERROR(INVALID_LOADER, "invalid loader") \ 00317 LT_ERROR(INIT_LOADER, "loader initialization failed") \ 00318 LT_ERROR(REMOVE_LOADER, "loader removal failed") \ 00319 LT_ERROR(FILE_NOT_FOUND, "file not found") \ 00320 LT_ERROR(DEPLIB_NOT_FOUND, "dependency library not found") \ 00321 LT_ERROR(NO_SYMBOLS, "no symbols defined") \ 00322 LT_ERROR(CANNOT_OPEN, "can't open the module") \ 00323 LT_ERROR(CANNOT_CLOSE, "can't close the module") \ 00324 LT_ERROR(SYMBOL_NOT_FOUND, "symbol not found") \ 00325 LT_ERROR(NO_MEMORY, "not enough memory") \ 00326 LT_ERROR(INVALID_HANDLE, "invalid module handle") \ 00327 LT_ERROR(BUFFER_OVERFLOW, "internal buffer overflow") \ 00328 LT_ERROR(INVALID_ERRORCODE, "invalid errorcode") \ 00329 LT_ERROR(SHUTDOWN, "library already shutdown") \ 00330 LT_ERROR(CLOSE_RESIDENT_MODULE, "can't close resident module") \ 00331 LT_ERROR(INVALID_MUTEX_ARGS, "invalid mutex handler registration") \ 00332 LT_ERROR(INVALID_POSITION, "invalid search path insert position") 00333 00334 /* Enumerate the symbolic error names. */ 00335 enum { 00336 #define LT_ERROR(name, diagnostic) LT_CONC(LT_ERROR_, name), 00337 lt_dlerror_table 00338 #undef LT_ERROR 00339 00340 LT_ERROR_MAX 00341 }; 00342 00343 /* These functions are only useful from inside custom module loaders. */ 00344 LT_SCOPE int lt_dladderror LT_PARAMS((const char *diagnostic)); 00345 LT_SCOPE int lt_dlseterror LT_PARAMS((int errorcode)); 00346 00347 00348 00349 00350 /* --- SOURCE COMPATIBILITY WITH OLD LIBLTDL --- */ 00351 00352 00353 #ifdef LT_NON_POSIX_NAMESPACE 00354 # define lt_ptr_t lt_ptr 00355 # define lt_module_t lt_module 00356 # define lt_module_open_t lt_module_open 00357 # define lt_module_close_t lt_module_close 00358 # define lt_find_sym_t lt_find_sym 00359 # define lt_dlloader_exit_t lt_dlloader_exit 00360 # define lt_dlloader_t lt_dlloader 00361 # define lt_dlloader_data_t lt_user_data 00362 #endif 00363 00364 LT_END_C_DECLS 00365 00366 #endif /* !LTDL_H */