source/include/ltdl.h

0001 /* ltdl.h -- generic dlopen functions
0002
0003    Copyright (C) 1998-2000, 2004-2005, 2007-2008, 2011-2019, 2021-2022
0004    Free Software Foundation, Inc.
0005    Written by Thomas Tanner, 1998
0006
0007    NOTE: The canonical source of this file is maintained with the
0008    GNU Libtool package.  Report bugs to bug-libtool@gnu.org.
0009
0010 GNU Libltdl is free software; you can redistribute it and/or
0011 modify it under the terms of the GNU Lesser General Public
0012 License as published by the Free Software Foundation; either
0013 version 2 of the License, or (at your option) any later version.
0014
0015 As a special exception to the GNU Lesser General Public License,
0016 if you distribute this file as part of a program or library that
0017 is built using GNU Libtool, you may include this file under the
0018 same distribution terms that you use for the rest of that program.
0019
0020 GNU Libltdl is distributed in the hope that it will be useful,
0021 but WITHOUT ANY WARRANTY; without even the implied warranty of
0022 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
0023 GNU Lesser General Public License for more details.
0024
0025 You should have received a copy of the GNU Lesser General Public
0026 License along with GNU Libltdl; see the file COPYING.LIB.  If not, a
0027 copy can be downloaded from  http://www.gnu.org/licenses/lgpl.html,
0028 or obtained by writing to the Free Software Foundation, Inc.,
0029 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
0030 */
0031
0032 /* Only include this header file once. */
0033 #if !defined LTDL_H
0034 #define LTDL_H 1
0035
0036 #include <libltdl/lt_system.h>
0037 #include <libltdl/lt_error.h>
0038 #include <libltdl/lt_dlloader.h>
0039
0040 LT_BEGIN_C_DECLS
0041
0042
0043 /* LT_STRLEN can be used safely on NULL pointers.  */
0044 #define LT_STRLEN(s)    (((s) && (s)[0]) ? strlen (s) : 0)
0045
0046
0047 /* --- DYNAMIC MODULE LOADING API --- */
0048
0049
0050 typedef struct lt__handle *lt_dlhandle; /* A loaded module.  */
0051
0052 /* Initialisation and finalisation functions for libltdl. */
0053 LT_SCOPE int        lt_dlinit       (void);
0054 LT_SCOPE int        lt_dlexit       (void);
0055
0056 /* Module search path manipulation.  */
0057 LT_SCOPE int        lt_dladdsearchdir    (const char *search_dir);
0058 LT_SCOPE int        lt_dlinsertsearchdir (const char *before,
0059                           const char *search_dir);
0060 LT_SCOPE int        lt_dlsetsearchpath   (const char *search_path);
0061 LT_SCOPE const char *lt_dlgetsearchpath  (void);
0062 LT_SCOPE int        lt_dlforeachfile     (
0063             const char *search_path,
0064             int (*func) (const char *filename, void *data),
0065             void *data);
0066
0067 /* User module loading advisors.  */
0068 LT_SCOPE int        lt_dladvise_init     (lt_dladvise *advise);
0069 LT_SCOPE int        lt_dladvise_destroy  (lt_dladvise *advise);
0070 LT_SCOPE int        lt_dladvise_ext  (lt_dladvise *advise);
0071 LT_SCOPE int        lt_dladvise_resident (lt_dladvise *advise);
0072 LT_SCOPE int        lt_dladvise_local    (lt_dladvise *advise);
0073 LT_SCOPE int        lt_dladvise_global   (lt_dladvise *advise);
0074 LT_SCOPE int        lt_dladvise_preload  (lt_dladvise *advise);
0075
0076 /* Portable libltdl versions of the system dlopen() API. */
0077 LT_SCOPE lt_dlhandle lt_dlopen      (const char *filename);
0078 LT_SCOPE lt_dlhandle lt_dlopenext   (const char *filename);
0079 LT_SCOPE lt_dlhandle lt_dlopenadvise    (const char *filename,
0080                      lt_dladvise advise);
0081 LT_SCOPE void *     lt_dlsym        (lt_dlhandle handle, const char *name);
0082 LT_SCOPE const char *lt_dlerror     (void);
0083 LT_SCOPE int        lt_dlclose      (lt_dlhandle handle);
0084
0085
0086
0087 /* --- PRELOADED MODULE SUPPORT --- */
0088
0089
0090 /* A preopened symbol. Arrays of this type comprise the exported
0091    symbols for a dlpreopened module. */
0092 typedef struct {
0093   const char *name;
0094   void       *address;
0095 } lt_dlsymlist;
0096
0097 typedef int lt_dlpreload_callback_func (lt_dlhandle handle);
0098
0099 LT_SCOPE int    lt_dlpreload         (const lt_dlsymlist *preloaded);
0100 LT_SCOPE int    lt_dlpreload_default (const lt_dlsymlist *preloaded);
0101 LT_SCOPE int    lt_dlpreload_open    (const char *originator,
0102                       lt_dlpreload_callback_func *func);
0103
0104 #define lt_preloaded_symbols    lt__PROGRAM__LTX_preloaded_symbols
0105 /* Ensure C linkage.  */
0106 extern LT_DLSYM_CONST lt_dlsymlist lt__PROGRAM__LTX_preloaded_symbols[];
0107
0108 #define LTDL_SET_PRELOADED_SYMBOLS() \
0109     lt_dlpreload_default(lt_preloaded_symbols)
0110
0111
0112
0113
0114 /* --- MODULE INFORMATION --- */
0115
0116
0117 /* Associating user data with loaded modules. */
0118 typedef void * lt_dlinterface_id;
0119 typedef int lt_dlhandle_interface (lt_dlhandle handle, const char *id_string);
0120
0121 LT_SCOPE lt_dlinterface_id lt_dlinterface_register (const char *id_string,
0122                       lt_dlhandle_interface *iface);
0123 LT_SCOPE void   lt_dlinterface_free (lt_dlinterface_id key);
0124 LT_SCOPE void * lt_dlcaller_set_data  (lt_dlinterface_id key,
0125                       lt_dlhandle handle, void *data);
0126 LT_SCOPE void * lt_dlcaller_get_data  (lt_dlinterface_id key,
0127                       lt_dlhandle handle);
0128
0129
0130 /* Read only information pertaining to a loaded module. */
0131 typedef struct {
0132   char *    filename;   /* file name */
0133   char *    name;       /* module name */
0134   int       ref_count;  /* number of times lt_dlopened minus
0135                    number of times lt_dlclosed. */
0136   unsigned int  is_resident:1;  /* module can't be unloaded. */
0137   unsigned int  is_symglobal:1; /* module symbols can satisfy
0138                    subsequently loaded modules.  */
0139   unsigned int  is_symlocal:1;  /* module symbols are only available
0140                    locally. */
0141 } lt_dlinfo;
0142
0143 LT_SCOPE const lt_dlinfo *lt_dlgetinfo      (lt_dlhandle handle);
0144
0145 LT_SCOPE lt_dlhandle    lt_dlhandle_iterate (lt_dlinterface_id iface,
0146                          lt_dlhandle place);
0147 LT_SCOPE lt_dlhandle    lt_dlhandle_fetch   (lt_dlinterface_id iface,
0148                          const char *module_name);
0149 LT_SCOPE int        lt_dlhandle_map     (lt_dlinterface_id iface,
0150                 int (*func) (lt_dlhandle handle, void *data),
0151                 void *data);
0152
0153
0154
0155 /* Deprecated module residency management API. */
0156 LT_SCOPE int        lt_dlmakeresident   (lt_dlhandle handle);
0157 LT_SCOPE int        lt_dlisresident (lt_dlhandle handle);
0158
0159 #define lt_ptr void *
0160
0161 LT_END_C_DECLS
0162
0163 #endif /*!defined LTDL_H*/