LLVM API Documentation
00001 //===-- llvm/System/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by Reid Spencer and is distributed under the 00006 // University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This file declares the sys::DynamicLibrary class. 00011 // 00012 //===----------------------------------------------------------------------===// 00013 00014 #ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H 00015 #define LLVM_SYSTEM_DYNAMIC_LIBRARY_H 00016 00017 #include "llvm/System/Path.h" 00018 #include <string> 00019 00020 namespace llvm { 00021 namespace sys { 00022 00023 /// This class provides a portable interface to dynamic libraries which also 00024 /// might be known as shared libraries, shared objects, dynamic shared 00025 /// objects, or dynamic link libraries. Regardless of the terminology or the 00026 /// operating system interface, this class provides a portable interface that 00027 /// allows dynamic libraries to be loaded and and searched for externally 00028 /// defined symbols. This is typically used to provide "plug-in" support. 00029 /// It also allows for symbols to be defined which don't live in any library, 00030 /// but rather the main program itself, useful on Windows where the main 00031 /// executable cannot be searched. 00032 /// @since 1.4 00033 /// @brief Portable dynamic library abstraction. 00034 class DynamicLibrary { 00035 /// @name Constructors 00036 /// @{ 00037 public: 00038 /// Construct a DynamicLibrary that represents the currently executing 00039 /// program. The program must have been linked with -export-dynamic or 00040 /// -dlopen self for this to work. Any symbols retrieved with the 00041 /// GetAddressOfSymbol function will refer to the program not to any 00042 /// library. 00043 /// @throws std::string indicating why the program couldn't be opened. 00044 /// @brief Open program as dynamic library. 00045 DynamicLibrary(); 00046 00047 /// This is the constructor for DynamicLibrary instances. It will open 00048 /// the dynamic library specified by the \filename Path. 00049 /// @throws std::string indicating why the library couldn't be opened. 00050 /// @brief Open a dynamic library. 00051 DynamicLibrary(const char* filename); 00052 00053 /// After destruction, the symbols of the library will no longer be 00054 /// available to the program. It is important to make sure the lifespan 00055 /// of a DynamicLibrary exceeds the lifetime of the pointers returned 00056 /// by the GetAddressOfSymbol otherwise the program may walk off into 00057 /// uncharted territory. 00058 /// @see GetAddressOfSymbol. 00059 /// @brief Closes the DynamicLibrary 00060 ~DynamicLibrary(); 00061 00062 /// @} 00063 /// @name Functions 00064 /// @{ 00065 public: 00066 /// This function allows a library to be loaded without instantiating a 00067 /// DynamicLibrary object. Consequently, it is marked as being permanent 00068 /// and will only be unloaded when the program terminates. 00069 /// @throws std::string on error. 00070 /// @brief Open a dynamic library permanently. 00071 static void LoadLibraryPermanently(const char* filename); 00072 00073 /// This function will search through all previously loaded dynamic 00074 /// libraries for the symbol \p symbolName. If it is found, the addressof 00075 /// that symbol is returned. If not, null is returned. Note that this will 00076 /// search permanently loaded libraries (LoadLibraryPermanently) as well 00077 /// as ephemerally loaded libraries (constructors). 00078 /// @throws std::string on error. 00079 /// @brief Search through libraries for address of a symbol 00080 static void* SearchForAddressOfSymbol(const char* symbolName); 00081 00082 /// @brief Convenience function for C++ophiles. 00083 static void* SearchForAddressOfSymbol(const std::string& symbolName) { 00084 return SearchForAddressOfSymbol(symbolName.c_str()); 00085 } 00086 00087 /// This functions permanently adds the symbol \p symbolName with the 00088 /// value \p symbolValue. These symbols are searched before any 00089 /// libraries. 00090 /// @brief Add searchable symbol/value pair. 00091 static void AddSymbol(const char* symbolName, void *symbolValue); 00092 00093 /// @brief Convenience function for C++ophiles. 00094 static void AddSymbol(const std::string& symbolName, void *symbolValue) { 00095 AddSymbol(symbolName.c_str(), symbolValue); 00096 } 00097 00098 /// @} 00099 /// @name Accessors 00100 /// @{ 00101 public: 00102 /// Looks up a \p symbolName in the DynamicLibrary and returns its address 00103 /// if it exists. If the symbol does not exist, returns (void*)0. 00104 /// @returns the address of the symbol or 0. 00105 /// @brief Get the address of a symbol in the DynamicLibrary. 00106 void* GetAddressOfSymbol(const char* symbolName); 00107 00108 /// @brief Convenience function for C++ophiles. 00109 void* GetAddressOfSymbol(const std::string& symbolName) { 00110 return GetAddressOfSymbol(symbolName.c_str()); 00111 } 00112 00113 /// @} 00114 /// @name Implementation 00115 /// @{ 00116 protected: 00117 void* handle; // Opaque handle for information about the library 00118 00119 DynamicLibrary(const DynamicLibrary&); ///< Do not implement 00120 DynamicLibrary& operator=(const DynamicLibrary&); ///< Do not implement 00121 /// @} 00122 }; 00123 00124 } // End sys namespace 00125 } // End llvm namespace 00126 00127 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H