1 /* ///////////////////////////////////////////////////////////////////////// 2 * File: dlfcn.h 3 * 4 * Purpose: Declaration of the dlopen, dlclose(), dlsym() and dlerror() API 5 * functions. 6 * 7 * Created: 1st January 2004 8 * Updated: 13th August 2010 9 * 10 * Home: http://synesis.com.au/software/ 11 * 12 * Copyright (c) 2004-2010, Matthew Wilson and Synesis Software 13 * All rights reserved. 14 * 15 * Redistribution and use in source and binary forms, with or without 16 * modification, are permitted provided that the following conditions are met: 17 * 18 * - Redistributions of source code must retain the above copyright notice, this 19 * list of conditions and the following disclaimer. 20 * - Redistributions in binary form must reproduce the above copyright notice, 21 * this list of conditions and the following disclaimer in the documentation 22 * and/or other materials provided with the distribution. 23 * - Neither the names of Matthew Wilson and Synesis Software nor the names of 24 * any contributors may be used to endorse or promote products derived from 25 * this software without specific prior written permission. 26 * 27 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 28 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 29 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 30 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 31 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 32 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 33 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 34 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 35 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 36 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 37 * POSSIBILITY OF SUCH DAMAGE. 38 * 39 * ////////////////////////////////////////////////////////////////////// */ 40 41 42 /** \file dlfcn.h 43 * 44 * Contains the declarations for the dlopen() API. 45 */ 46 47 #ifndef SYNSOFT_UNIXEM_INCL_H_DLFCN 48 #define SYNSOFT_UNIXEM_INCL_H_DLFCN 49 50 #ifndef UNIXEM_DOCUMENTATION_SKIP_SECTION 51 # define SYNSOFT_UNIXEM_VER_H_DLFCN_MAJOR 3 52 # define SYNSOFT_UNIXEM_VER_H_DLFCN_MINOR 0 53 # define SYNSOFT_UNIXEM_VER_H_DLFCN_REVISION 1 54 # define SYNSOFT_UNIXEM_VER_H_DLFCN_EDIT 18 55 #endif /* !UNIXEM_DOCUMENTATION_SKIP_SECTION */ 56 57 /* ///////////////////////////////////////////////////////////////////////// 58 * Includes 59 */ 60 61 #include <unixem/dlfcn.h> 62 63 /* ////////////////////////////////////////////////////////////////////// */ 64 65 /** \weakgroup unixem Synesis Software UNIX Emulation for Win32 66 * \brief The UNIX emulation library 67 */ 68 69 /** \weakgroup unixem_dlopen dlopen() API 70 * \ingroup UNIXem unixem 71 * \brief This API provides facilities for manipulating dynamically loaded 72 * executable modules 73 * @{ 74 */ 75 76 /* ////////////////////////////////////////////////////////////////////// */ 77 78 #ifndef _WIN32 79 # error This file is only currently defined for compilation on Win32 systems 80 #endif /* _WIN32 */ 81 82 /* ///////////////////////////////////////////////////////////////////////// 83 * Constants and definitions 84 */ 85 86 #define RTLD_LAZY (UNIXEM_RTLD_LAZY) /*!< Lazy function call binding. */ 87 #define RTLD_NOW (UNIXEM_RTLD_NOW) /*!< Immediate function call binding. */ 88 89 /* ///////////////////////////////////////////////////////////////////////// 90 * API functions 91 */ 92 93 #ifdef __cplusplus 94 extern "C" 95 { 96 #endif /* __cplusplus */ 97 98 /** Loads the given module, 99 * 100 * \param moduleName The name of the module. The name is passed through to Win32's 101 * LoadLibrary(), so the value of this parameter is interpreted according to Win32's 102 * loading rules. 103 * \param mode The loading mode. This is ignored on Win32 platforms, and the function 104 * always behaves as if RTLD_NOW was specified 105 * 106 * \note This is a macro, which resolves to unixem_dlopen() 107 */ 108 #ifdef UNIXEM_DOCUMENTATION_SKIP_SECTION 109 void* dlopen( 110 char const* moduleName 111 , int mode 112 ); 113 #else /* ? UNIXEM_DOCUMENTATION_SKIP_SECTION */ 114 # define dlopen unixem_dlopen 115 #endif /* UNIXEM_DOCUMENTATION_SKIP_SECTION */ 116 117 /** Closes the given module 118 * 119 * \param hModule The handle of the executable module to close 120 * \retval 0 success 121 * \retval !0 failure. dlerror() will return an error string 122 * 123 * \note This is a macro, which resolves to unixem_dlclose() 124 */ 125 #ifdef UNIXEM_DOCUMENTATION_SKIP_SECTION 126 void dlclose(void* hModule); 127 #else /* ? UNIXEM_DOCUMENTATION_SKIP_SECTION */ 128 # define dlclose unixem_dlclose 129 #endif /* UNIXEM_DOCUMENTATION_SKIP_SECTION */ 130 131 /** Looks up a symbol 132 * 133 * \param hModule The handle of the executable module in which to search for the symbol 134 * \param symbolName The name of the symbol 135 * \return The pointer to the symbol, or NULL if no matching symbol was found 136 * \retval NULL The symbol was not found 137 * 138 * \note This is a macro, which resolves to unixem_dlsym() 139 */ 140 #ifdef UNIXEM_DOCUMENTATION_SKIP_SECTION 141 void* dlsym( 142 void* hModule 143 , char const* symbolName 144 ); 145 #else /* ? UNIXEM_DOCUMENTATION_SKIP_SECTION */ 146 # define dlsym unixem_dlsym 147 #endif /* UNIXEM_DOCUMENTATION_SKIP_SECTION */ 148 149 /** Returns a descriptive string for the last error 150 * 151 * \return A pointer to a string describing the last error, or NULL. 152 * \retval NULL No error occured, or dlerror() already called 153 * \note Each call to this function resets it, so that a second call will always return NULL 154 * 155 * \note This is a macro, which resolves to unixem_dlerror() 156 */ 157 #ifdef UNIXEM_DOCUMENTATION_SKIP_SECTION 158 char const* dlerror(void); 159 #else /* ? UNIXEM_DOCUMENTATION_SKIP_SECTION */ 160 # define dlerror unixem_dlerror 161 #endif /* UNIXEM_DOCUMENTATION_SKIP_SECTION */ 162 163 #ifndef UNIXEM_DOCUMENTATION_SKIP_SECTION 164 165 #endif /* !UNIXEM_DOCUMENTATION_SKIP_SECTION */ 166 167 #ifdef __cplusplus 168 } /* extern "C" */ 169 #endif /* __cplusplus */ 170 171 /* ////////////////////////////////////////////////////////////////////// */ 172 173 /** @} // end of group unixem_dlopen */ 174 175 /* ////////////////////////////////////////////////////////////////////// */ 176 177 #endif /* SYNSOFT_UNIXEM_INCL_H_DLFCN */ 178 179 /* ///////////////////////////// end of file //////////////////////////// */ 180