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 /// @since 1.4 00030 /// @brief Portable dynamic library abstraction. 00031 class DynamicLibrary { 00032 /// @name Constructors 00033 /// @{ 00034 public: 00035 /// Construct a DynamicLibrary that represents the currently executing 00036 /// program. The program must have been linked with -export-dynamic or 00037 /// -dlopen self for this to work. Any symbols retrieved with the 00038 /// GetAddressOfSymbol function will refer to the program not to any 00039 /// library. 00040 /// @throws std::string indicating why the program couldn't be opened. 00041 /// @brief Open program as dynamic library. 00042 DynamicLibrary(); 00043 00044 /// This is the constructor for DynamicLibrary instances. It will open 00045 /// the dynamic library specified by the \filename Path. 00046 /// @throws std::string indicating why the library couldn't be opened. 00047 /// @brief Open a dynamic library. 00048 DynamicLibrary(const char* filename); 00049 00050 /// After destruction, the symbols of the library will no longer be 00051 /// available to the program. It is important to make sure the lifespan 00052 /// of a DynamicLibrary exceeds the lifetime of the pointers returned 00053 /// by the GetAddressOfSymbol otherwise the program may walk off into 00054 /// uncharted territory. 00055 /// @see GetAddressOfSymbol. 00056 /// @brief Closes the DynamicLibrary 00057 ~DynamicLibrary(); 00058 00059 /// @} 00060 /// @name Functions 00061 /// @{ 00062 public: 00063 /// This function allows a library to be loaded without instantiating a 00064 /// DynamicLibrary object. Consequently, it is marked as being permanent 00065 /// and will only be unloaded when the program terminates. 00066 /// @throws std::string on error. 00067 /// @brief Open a dynamic library permanently. 00068 static void LoadLibraryPermanently(const char* filename); 00069 00070 /// This function will search through all previously loaded dynamic 00071 /// libraries for the symbol \p symbolName. If it is found, the addressof 00072 /// that symbol is returned. If not, null is returned. Note that this will 00073 /// search permanently loaded libraries (LoadLibraryPermanently) as well 00074 /// as ephemerally loaded libraries (constructors). 00075 /// @throws std::string on error. 00076 /// @brief Search through libraries for address of a symbol 00077 static void* SearchForAddressOfSymbol(const char* symbolName); 00078 00079 /// @brief Convenience function for C++ophiles. 00080 static void* SearchForAddressOfSymbol(const std::string& symbolName) { 00081 return SearchForAddressOfSymbol(symbolName.c_str()); 00082 } 00083 00084 /// @} 00085 /// @name Accessors 00086 /// @{ 00087 public: 00088 /// Looks up a \p symbolName in the DynamicLibrary and returns its address 00089 /// if it exists. If the symbol does not exist, returns (void*)0. 00090 /// @returns the address of the symbol or 0. 00091 /// @brief Get the address of a symbol in the DynamicLibrary. 00092 void* GetAddressOfSymbol(const char* symbolName); 00093 00094 /// @brief Convenience function for C++ophiles. 00095 void* GetAddressOfSymbol(const std::string& symbolName) { 00096 return GetAddressOfSymbol(symbolName.c_str()); 00097 } 00098 00099 /// @} 00100 /// @name Implementation 00101 /// @{ 00102 protected: 00103 void* handle; // Opaque handle for information about the library 00104 00105 DynamicLibrary(const DynamicLibrary&); ///< Do not implement 00106 DynamicLibrary& operator=(const DynamicLibrary&); ///< Do not implement 00107 /// @} 00108 }; 00109 00110 } // End sys namespace 00111 } // End llvm namespace 00112 00113 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H