blob: 8bf255b308bde22f67565cdc49adc251b3a847fd [file] [log] [blame]
Reid Spencer9c16ed52004-11-29 12:02:48 +00001/* 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., 59 Temple Place, Suite 330, Boston, MA
2402111-1307 USA
25*/
26
27/* Only include this header file once. */
28#ifndef LTDL_H
29#define LTDL_H 1
30
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000031#include <sys/types.h> /* for size_t declaration */
Reid Spencer9c16ed52004-11-29 12:02:48 +000032
33
34/* --- MACROS FOR PORTABILITY --- */
35
36
37/* Saves on those hard to debug '\0' typos.... */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000038#define LT_EOS_CHAR '\0'
Reid Spencer9c16ed52004-11-29 12:02:48 +000039
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
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000044# define LT_BEGIN_C_DECLS extern "C" {
45# define LT_END_C_DECLS }
Reid Spencer9c16ed52004-11-29 12:02:48 +000046#else
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000047# define LT_BEGIN_C_DECLS /* empty */
48# define LT_END_C_DECLS /* empty */
Reid Spencer9c16ed52004-11-29 12:02:48 +000049#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)
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000058# define LT_PARAMS(protos) protos
59# define lt_ptr void*
Reid Spencer9c16ed52004-11-29 12:02:48 +000060#else
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000061# define LT_PARAMS(protos) ()
62# define lt_ptr char*
Reid Spencer9c16ed52004-11-29 12:02:48 +000063#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)
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000083# define LT_CONC(s,t) s##t
Reid Spencer9c16ed52004-11-29 12:02:48 +000084#else
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000085# define LT_CONC(s,t) s/**/t
Reid Spencer9c16ed52004-11-29 12:02:48 +000086#endif
87
88/* LT_STRLEN can be used safely on NULL pointers. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +000089#define LT_STRLEN(s) (((s) && (s)[0]) ? strlen (s) : 0)
Reid Spencer9c16ed52004-11-29 12:02:48 +000090
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. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000119# define LT_DIRSEP_CHAR '\\'
120# define LT_PATHSEP_CHAR ';'
Reid Spencer9c16ed52004-11-29 12:02:48 +0000121# endif
122#endif
123#ifndef LT_PATHSEP_CHAR
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000124# define LT_PATHSEP_CHAR ':'
Reid Spencer9c16ed52004-11-29 12:02:48 +0000125#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__
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000131# ifdef DLL_EXPORT /* defined by libtool (if required) */
132# define LT_SCOPE __declspec(dllexport)
Reid Spencer9c16ed52004-11-29 12:02:48 +0000133# endif
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000134# ifdef LIBLTDL_DLL_IMPORT /* define if linking with this dll */
135# define LT_SCOPE extern __declspec(dllimport)
Reid Spencer9c16ed52004-11-29 12:02:48 +0000136# endif
137# endif
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000138# ifndef LT_SCOPE /* static linking or !__WINDOWS__ */
139# define LT_SCOPE extern
Reid Spencer9c16ed52004-11-29 12:02:48 +0000140# 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
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000153typedef struct lt_dlhandle_struct *lt_dlhandle; /* A loaded module. */
Reid Spencer9c16ed52004-11-29 12:02:48 +0000154
155/* Initialisation and finalisation functions for libltdl. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000156LT_SCOPE int lt_dlinit LT_PARAMS((void));
157LT_SCOPE int lt_dlexit LT_PARAMS((void));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000158
159/* Module search path manipulation. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000160LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000169
170/* Portable libltdl versions of the system dlopen() API. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000171LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000177
178/* Module residency management. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000179LT_SCOPE int lt_dlmakeresident LT_PARAMS((lt_dlhandle handle));
180LT_SCOPE int lt_dlisresident LT_PARAMS((lt_dlhandle handle));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000181
182
183
184
185/* --- MUTEX LOCKING --- */
186
187
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000188typedef 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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000192
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000193LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000197
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. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000209LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000212
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
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000226LT_SCOPE int lt_dlpreload LT_PARAMS((const lt_dlsymlist *preloaded));
227LT_SCOPE int lt_dlpreload_default
228 LT_PARAMS((const lt_dlsymlist *preloaded));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000229
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000230#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
Reid Spencer9c16ed52004-11-29 12:02:48 +0000234
235
236
237
238/* --- MODULE INFORMATION --- */
239
240
241/* Read only information pertaining to a loaded module. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000242typedef 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. */
Reid Spencer9c16ed52004-11-29 12:02:48 +0000247} lt_dlinfo;
248
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000249LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000254
255/* Associating user data with loaded modules. */
256typedef unsigned lt_dlcaller_id;
257
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000258LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000264
265
266
267/* --- USER MODULE LOADER API --- */
268
269
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000270typedef struct lt_dlloader lt_dlloader;
271typedef lt_ptr lt_user_data;
272typedef lt_ptr lt_module;
Reid Spencer9c16ed52004-11-29 12:02:48 +0000273
274/* Function pointer types for creating user defined module loaders. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000275typedef 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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000283
284struct lt_user_dlloader {
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000285 const char *sym_prefix;
Reid Spencer9c16ed52004-11-29 12:02:48 +0000286 lt_module_open *module_open;
287 lt_module_close *module_close;
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000288 lt_find_sym *find_sym;
Reid Spencer9c16ed52004-11-29 12:02:48 +0000289 lt_dlloader_exit *dlloader_exit;
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000290 lt_user_data dlloader_data;
Reid Spencer9c16ed52004-11-29 12:02:48 +0000291};
292
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000293LT_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));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000303
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. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000313#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") \
Reid Spencer9c16ed52004-11-29 12:02:48 +0000331 LT_ERROR(INVALID_MUTEX_ARGS, "invalid mutex handler registration") \
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000332 LT_ERROR(INVALID_POSITION, "invalid search path insert position")
Reid Spencer9c16ed52004-11-29 12:02:48 +0000333
334/* Enumerate the symbolic error names. */
335enum {
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000336#define LT_ERROR(name, diagnostic) LT_CONC(LT_ERROR_, name),
337 lt_dlerror_table
Reid Spencer9c16ed52004-11-29 12:02:48 +0000338#undef LT_ERROR
339
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000340 LT_ERROR_MAX
Reid Spencer9c16ed52004-11-29 12:02:48 +0000341};
342
343/* These functions are only useful from inside custom module loaders. */
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000344LT_SCOPE int lt_dladderror LT_PARAMS((const char *diagnostic));
345LT_SCOPE int lt_dlseterror LT_PARAMS((int errorcode));
Reid Spencer9c16ed52004-11-29 12:02:48 +0000346
347
348
349
350/* --- SOURCE COMPATIBILITY WITH OLD LIBLTDL --- */
351
352
353#ifdef LT_NON_POSIX_NAMESPACE
Jeff Cohen9eb59ec2005-07-27 05:53:44 +0000354# 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
Reid Spencer9c16ed52004-11-29 12:02:48 +0000362#endif
363
364LT_END_C_DECLS
365
366#endif /* !LTDL_H */