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