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 6This library is free software; you can redistribute it and/or 7modify it under the terms of the GNU Lesser General Public 8License as published by the Free Software Foundation; either 9version 2 of the License, or (at your option) any later version. 10 11As a special exception to the GNU Lesser General Public License, 12if you distribute this file as part of a program or library that 13is built using GNU libtool, you may include it under the same 14distribution terms that you use for the rest of that program. 15 16This library is distributed in the hope that it will be useful, 17but WITHOUT ANY WARRANTY; without even the implied warranty of 18MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 19Lesser General Public License for more details. 20 21You should have received a copy of the GNU Lesser General Public 22License along with this library; if not, write to the Free 23Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 2402110-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 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 51LT_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) 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 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# ifdef __WINDOWS__ 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# define LT_SCOPE extern __declspec(dllimport) 136# endif 137# endif 138# ifndef LT_SCOPE /* static linking or !__WINDOWS__ */ 139# define LT_SCOPE extern 140# endif 141#endif 142 143 144#if defined(_MSC_VER) /* Visual Studio */ 145# define R_OK 4 146#endif 147 148 149 150/* --- DYNAMIC MODULE LOADING API --- */ 151 152 153typedef struct lt_dlhandle_struct *lt_dlhandle; /* A loaded module. */ 154 155/* Initialisation and finalisation functions for libltdl. */ 156LT_SCOPE int lt_dlinit LT_PARAMS((void)); 157LT_SCOPE int lt_dlexit LT_PARAMS((void)); 158 159/* Module search path manipulation. */ 160LT_SCOPE int lt_dladdsearchdir LT_PARAMS((const char *search_dir)); 161LT_SCOPE int lt_dlinsertsearchdir LT_PARAMS((const char *before, 162 const char *search_dir)); 163LT_SCOPE int lt_dlsetsearchpath LT_PARAMS((const char *search_path)); 164LT_SCOPE const char *lt_dlgetsearchpath LT_PARAMS((void)); 165LT_SCOPE int lt_dlforeachfile LT_PARAMS(( 166 const char *search_path, 167 int (*func) (const char *filename, lt_ptr data), 168 lt_ptr data)); 169 170/* Portable libltdl versions of the system dlopen() API. */ 171LT_SCOPE lt_dlhandle lt_dlopen LT_PARAMS((const char *filename)); 172LT_SCOPE lt_dlhandle lt_dlopenext LT_PARAMS((const char *filename)); 173LT_SCOPE lt_ptr lt_dlsym LT_PARAMS((lt_dlhandle handle, 174 const char *name)); 175LT_SCOPE const char *lt_dlerror LT_PARAMS((void)); 176LT_SCOPE int lt_dlclose LT_PARAMS((lt_dlhandle handle)); 177 178/* Module residency management. */ 179LT_SCOPE int lt_dlmakeresident LT_PARAMS((lt_dlhandle handle)); 180LT_SCOPE int lt_dlisresident LT_PARAMS((lt_dlhandle handle)); 181 182 183 184 185/* --- MUTEX LOCKING --- */ 186 187 188typedef void lt_dlmutex_lock LT_PARAMS((void)); 189typedef void lt_dlmutex_unlock LT_PARAMS((void)); 190typedef void lt_dlmutex_seterror LT_PARAMS((const char *errmsg)); 191typedef const char *lt_dlmutex_geterror LT_PARAMS((void)); 192 193LT_SCOPE int lt_dlmutex_register LT_PARAMS((lt_dlmutex_lock *lock, 194 lt_dlmutex_unlock *unlock, 195 lt_dlmutex_seterror *seterror, 196 lt_dlmutex_geterror *geterror)); 197 198 199 200 201/* --- MEMORY HANDLING --- */ 202 203 204/* By default, the realloc function pointer is set to our internal 205 realloc implementation which iself uses lt_dlmalloc and lt_dlfree. 206 libltdl relies on a featureful realloc, but if you are sure yours 207 has the right semantics then you can assign it directly. Generally, 208 it is safe to assign just a malloc() and a free() function. */ 209LT_SCOPE lt_ptr (*lt_dlmalloc) LT_PARAMS((size_t size)); 210LT_SCOPE lt_ptr (*lt_dlrealloc) LT_PARAMS((lt_ptr ptr, size_t size)); 211LT_SCOPE void (*lt_dlfree) LT_PARAMS((lt_ptr ptr)); 212 213 214 215 216/* --- PRELOADED MODULE SUPPORT --- */ 217 218 219/* A preopened symbol. Arrays of this type comprise the exported 220 symbols for a dlpreopened module. */ 221typedef struct { 222 const char *name; 223 lt_ptr address; 224} lt_dlsymlist; 225 226LT_SCOPE int lt_dlpreload LT_PARAMS((const lt_dlsymlist *preloaded)); 227LT_SCOPE int lt_dlpreload_default 228 LT_PARAMS((const lt_dlsymlist *preloaded)); 229 230#define LTDL_SET_PRELOADED_SYMBOLS() LT_STMT_START{ \ 231 extern const lt_dlsymlist lt_preloaded_symbols[]; \ 232 lt_dlpreload_default(lt_preloaded_symbols); \ 233 }LT_STMT_END 234 235 236 237 238/* --- MODULE INFORMATION --- */ 239 240 241/* Read only information pertaining to a loaded module. */ 242typedef struct { 243 char *filename; /* file name */ 244 char *name; /* module name */ 245 int ref_count; /* number of times lt_dlopened minus 246 number of times lt_dlclosed. */ 247} lt_dlinfo; 248 249LT_SCOPE const lt_dlinfo *lt_dlgetinfo LT_PARAMS((lt_dlhandle handle)); 250LT_SCOPE lt_dlhandle lt_dlhandle_next LT_PARAMS((lt_dlhandle place)); 251LT_SCOPE int lt_dlforeach LT_PARAMS(( 252 int (*func) (lt_dlhandle handle, lt_ptr data), 253 lt_ptr data)); 254 255/* Associating user data with loaded modules. */ 256typedef unsigned lt_dlcaller_id; 257 258LT_SCOPE lt_dlcaller_id lt_dlcaller_register LT_PARAMS((void)); 259LT_SCOPE lt_ptr lt_dlcaller_set_data LT_PARAMS((lt_dlcaller_id key, 260 lt_dlhandle handle, 261 lt_ptr data)); 262LT_SCOPE lt_ptr lt_dlcaller_get_data LT_PARAMS((lt_dlcaller_id key, 263 lt_dlhandle handle)); 264 265 266 267/* --- USER MODULE LOADER API --- */ 268 269 270typedef struct lt_dlloader lt_dlloader; 271typedef lt_ptr lt_user_data; 272typedef lt_ptr lt_module; 273 274/* Function pointer types for creating user defined module loaders. */ 275typedef lt_module lt_module_open LT_PARAMS((lt_user_data loader_data, 276 const char *filename)); 277typedef int lt_module_close LT_PARAMS((lt_user_data loader_data, 278 lt_module handle)); 279typedef lt_ptr lt_find_sym LT_PARAMS((lt_user_data loader_data, 280 lt_module handle, 281 const char *symbol)); 282typedef int lt_dlloader_exit LT_PARAMS((lt_user_data loader_data)); 283 284struct lt_user_dlloader { 285 const char *sym_prefix; 286 lt_module_open *module_open; 287 lt_module_close *module_close; 288 lt_find_sym *find_sym; 289 lt_dlloader_exit *dlloader_exit; 290 lt_user_data dlloader_data; 291}; 292 293LT_SCOPE lt_dlloader *lt_dlloader_next LT_PARAMS((lt_dlloader *place)); 294LT_SCOPE lt_dlloader *lt_dlloader_find LT_PARAMS(( 295 const char *loader_name)); 296LT_SCOPE const char *lt_dlloader_name LT_PARAMS((lt_dlloader *place)); 297LT_SCOPE lt_user_data *lt_dlloader_data LT_PARAMS((lt_dlloader *place)); 298LT_SCOPE int lt_dlloader_add LT_PARAMS((lt_dlloader *place, 299 const struct lt_user_dlloader *dlloader, 300 const char *loader_name)); 301LT_SCOPE int lt_dlloader_remove LT_PARAMS(( 302 const char *loader_name)); 303 304 305 306/* --- ERROR MESSAGE HANDLING --- */ 307 308 309/* Defining error strings alongside their symbolic names in a macro in 310 this way allows us to expand the macro in different contexts with 311 confidence that the enumeration of symbolic names will map correctly 312 onto the table of error strings. */ 313#define lt_dlerror_table \ 314 LT_ERROR(UNKNOWN, "unknown error") \ 315 LT_ERROR(DLOPEN_NOT_SUPPORTED, "dlopen support not available") \ 316 LT_ERROR(INVALID_LOADER, "invalid loader") \ 317 LT_ERROR(INIT_LOADER, "loader initialization failed") \ 318 LT_ERROR(REMOVE_LOADER, "loader removal failed") \ 319 LT_ERROR(FILE_NOT_FOUND, "file not found") \ 320 LT_ERROR(DEPLIB_NOT_FOUND, "dependency library not found") \ 321 LT_ERROR(NO_SYMBOLS, "no symbols defined") \ 322 LT_ERROR(CANNOT_OPEN, "can't open the module") \ 323 LT_ERROR(CANNOT_CLOSE, "can't close the module") \ 324 LT_ERROR(SYMBOL_NOT_FOUND, "symbol not found") \ 325 LT_ERROR(NO_MEMORY, "not enough memory") \ 326 LT_ERROR(INVALID_HANDLE, "invalid module handle") \ 327 LT_ERROR(BUFFER_OVERFLOW, "internal buffer overflow") \ 328 LT_ERROR(INVALID_ERRORCODE, "invalid errorcode") \ 329 LT_ERROR(SHUTDOWN, "library already shutdown") \ 330 LT_ERROR(CLOSE_RESIDENT_MODULE, "can't close resident module") \ 331 LT_ERROR(INVALID_MUTEX_ARGS, "invalid mutex handler registration") \ 332 LT_ERROR(INVALID_POSITION, "invalid search path insert position") 333 334/* Enumerate the symbolic error names. */ 335enum { 336#define LT_ERROR(name, diagnostic) LT_CONC(LT_ERROR_, name), 337 lt_dlerror_table 338#undef LT_ERROR 339 340 LT_ERROR_MAX 341}; 342 343/* These functions are only useful from inside custom module loaders. */ 344LT_SCOPE int lt_dladderror LT_PARAMS((const char *diagnostic)); 345LT_SCOPE int lt_dlseterror LT_PARAMS((int errorcode)); 346 347 348 349 350/* --- SOURCE COMPATIBILITY WITH OLD LIBLTDL --- */ 351 352 353#ifdef LT_NON_POSIX_NAMESPACE 354# define lt_ptr_t lt_ptr 355# define lt_module_t lt_module 356# define lt_module_open_t lt_module_open 357# define lt_module_close_t lt_module_close 358# define lt_find_sym_t lt_find_sym 359# define lt_dlloader_exit_t lt_dlloader_exit 360# define lt_dlloader_t lt_dlloader 361# define lt_dlloader_data_t lt_user_data 362#endif 363 364LT_END_C_DECLS 365 366#endif /* !LTDL_H */ 367