LLVM API Documentation

DynamicLibrary.h

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