DynamicLibrary.h revision 226633
1218885Sdim//===-- llvm/Support/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===// 2218885Sdim// 3218885Sdim// The LLVM Compiler Infrastructure 4218885Sdim// 5218885Sdim// This file is distributed under the University of Illinois Open Source 6218885Sdim// License. See LICENSE.TXT for details. 7218885Sdim// 8218885Sdim//===----------------------------------------------------------------------===// 9218885Sdim// 10218885Sdim// This file declares the sys::DynamicLibrary class. 11218885Sdim// 12218885Sdim//===----------------------------------------------------------------------===// 13218885Sdim 14218885Sdim#ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H 15218885Sdim#define LLVM_SYSTEM_DYNAMIC_LIBRARY_H 16218885Sdim 17218885Sdim#include <string> 18218885Sdim 19218885Sdimnamespace llvm { 20218885Sdimnamespace sys { 21218885Sdim 22218885Sdim /// This class provides a portable interface to dynamic libraries which also 23218885Sdim /// might be known as shared libraries, shared objects, dynamic shared 24218885Sdim /// objects, or dynamic link libraries. Regardless of the terminology or the 25218885Sdim /// operating system interface, this class provides a portable interface that 26218885Sdim /// allows dynamic libraries to be loaded and searched for externally 27218885Sdim /// defined symbols. This is typically used to provide "plug-in" support. 28218885Sdim /// It also allows for symbols to be defined which don't live in any library, 29218885Sdim /// but rather the main program itself, useful on Windows where the main 30218885Sdim /// executable cannot be searched. 31226633Sdim /// 32226633Sdim /// Note: there is currently no interface for temporarily loading a library, 33226633Sdim /// or for unloading libraries when the LLVM library is unloaded. 34218885Sdim class DynamicLibrary { 35226633Sdim // Placeholder whose address represents an invalid library. 36226633Sdim // We use this instead of NULL or a pointer-int pair because the OS library 37226633Sdim // might define 0 or 1 to be "special" handles, such as "search all". 38226633Sdim static char Invalid; 39226633Sdim 40226633Sdim // Opaque data used to interface with OS-specific dynamic library handling. 41226633Sdim void *Data; 42226633Sdim 43226633Sdim explicit DynamicLibrary(void *data = &Invalid) : Data(data) {} 44218885Sdim public: 45226633Sdim /// Returns true if the object refers to a valid library. 46226633Sdim bool isValid() { return Data != &Invalid; } 47226633Sdim 48226633Sdim /// Searches through the library for the symbol \p symbolName. If it is 49226633Sdim /// found, the address of that symbol is returned. If not, NULL is returned. 50226633Sdim /// Note that NULL will also be returned if the library failed to load. 51226633Sdim /// Use isValid() to distinguish these cases if it is important. 52226633Sdim /// Note that this will \e not search symbols explicitly registered by 53226633Sdim /// AddSymbol(). 54226633Sdim void *getAddressOfSymbol(const char *symbolName); 55226633Sdim 56226633Sdim /// This function permanently loads the dynamic library at the given path. 57226633Sdim /// The library will only be unloaded when the program terminates. 58226633Sdim /// This returns a valid DynamicLibrary instance on success and an invalid 59226633Sdim /// instance on failure (see isValid()). \p *errMsg will only be modified 60226633Sdim /// if the library fails to load. 61226633Sdim /// 62226633Sdim /// It is safe to call this function multiple times for the same library. 63218885Sdim /// @brief Open a dynamic library permanently. 64226633Sdim static DynamicLibrary getPermanentLibrary(const char *filename, 65226633Sdim std::string *errMsg = 0); 66226633Sdim 67226633Sdim /// This function permanently loads the dynamic library at the given path. 68226633Sdim /// Use this instead of getPermanentLibrary() when you won't need to get 69226633Sdim /// symbols from the library itself. 70218885Sdim /// 71226633Sdim /// It is safe to call this function multiple times for the same library. 72226633Sdim static bool LoadLibraryPermanently(const char *Filename, 73226633Sdim std::string *ErrMsg = 0) { 74226633Sdim return !getPermanentLibrary(Filename, ErrMsg).isValid(); 75226633Sdim } 76218885Sdim 77218885Sdim /// This function will search through all previously loaded dynamic 78226633Sdim /// libraries for the symbol \p symbolName. If it is found, the address of 79218885Sdim /// that symbol is returned. If not, null is returned. Note that this will 80226633Sdim /// search permanently loaded libraries (getPermanentLibrary()) as well 81226633Sdim /// as explicitly registered symbols (AddSymbol()). 82218885Sdim /// @throws std::string on error. 83218885Sdim /// @brief Search through libraries for address of a symbol 84218885Sdim static void *SearchForAddressOfSymbol(const char *symbolName); 85218885Sdim 86218885Sdim /// @brief Convenience function for C++ophiles. 87218885Sdim static void *SearchForAddressOfSymbol(const std::string &symbolName) { 88218885Sdim return SearchForAddressOfSymbol(symbolName.c_str()); 89218885Sdim } 90218885Sdim 91218885Sdim /// This functions permanently adds the symbol \p symbolName with the 92218885Sdim /// value \p symbolValue. These symbols are searched before any 93218885Sdim /// libraries. 94218885Sdim /// @brief Add searchable symbol/value pair. 95226633Sdim static void AddSymbol(StringRef symbolName, void *symbolValue); 96218885Sdim }; 97218885Sdim 98218885Sdim} // End sys namespace 99218885Sdim} // End llvm namespace 100218885Sdim 101218885Sdim#endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H 102