include/llvm/System/DynamicLibrary.h

   1 //===-- llvm/System/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This file declares the sys::DynamicLibrary class.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H
  15 #define LLVM_SYSTEM_DYNAMIC_LIBRARY_H
  16
  17 #include "llvm/System/Path.h"
  18 #include "llvm/System/IncludeFile.h"
  19 #include <string>
  20
  21 namespace llvm {
  22 namespace sys {
  23
  24   /// This class provides a portable interface to dynamic libraries which also
  25   /// might be known as shared libraries, shared objects, dynamic shared
  26   /// objects, or dynamic link libraries. Regardless of the terminology or the
  27   /// operating system interface, this class provides a portable interface that
  28   /// allows dynamic libraries to be loaded and and searched for externally
  29   /// defined symbols. This is typically used to provide "plug-in" support.
  30   /// It also allows for symbols to be defined which don't live in any library,
  31   /// but rather the main program itself, useful on Windows where the main
  32   /// executable cannot be searched.
  33   /// @since 1.4
  34   /// @brief Portable dynamic library abstraction.
  35   class DynamicLibrary {
  36     /// @name Constructors
  37     /// @{
  38     public:
  39       /// Construct a DynamicLibrary that represents the currently executing
  40       /// program. The program must have been linked with -export-dynamic or
  41       /// -dlopen self for this to work. Any symbols retrieved with the
  42       /// GetAddressOfSymbol function will refer to the program not to any
  43       /// library.
  44       /// @throws std::string indicating why the program couldn't be opened.
  45       /// @brief Open program as dynamic library.
  46       DynamicLibrary();
  47
  48       /// After destruction, the symbols of the library will no longer be
  49       /// available to the program. It is important to make sure the lifespan
  50       /// of a DynamicLibrary exceeds the lifetime of the pointers returned
  51       /// by the GetAddressOfSymbol otherwise the program may walk off into
  52       /// uncharted territory.
  53       /// @see GetAddressOfSymbol.
  54       /// @brief Closes the DynamicLibrary
  55       ~DynamicLibrary();
  56
  57     /// @}
  58     /// @name Functions
  59     /// @{
  60     public:
  61       /// This function allows a library to be loaded without instantiating a
  62       /// DynamicLibrary object. Consequently, it is marked as being permanent
  63       /// and will only be unloaded when the program terminates.  This returns
  64       /// false on success or returns true and fills in *ErrMsg on failure.
  65       /// @brief Open a dynamic library permanently.
  66       static bool LoadLibraryPermanently(const char* filename,
  67                                          std::string *ErrMsg = 0);
  68
  69       /// This function will search through all previously loaded dynamic
  70       /// libraries for the symbol \p symbolName. If it is found, the addressof
  71       /// that symbol is returned. If not, null is returned. Note that this will
  72       /// search permanently loaded libraries (LoadLibraryPermanently) as well
  73       /// as ephemerally loaded libraries (constructors).
  74       /// @throws std::string on error.
  75       /// @brief Search through libraries for address of a symbol
  76       static void* SearchForAddressOfSymbol(const char* symbolName);
  77
  78       /// @brief Convenience function for C++ophiles.
  79       static void* SearchForAddressOfSymbol(const std::string& symbolName) {
  80         return SearchForAddressOfSymbol(symbolName.c_str());
  81       }
  82
  83       /// This functions permanently adds the symbol \p symbolName with the
  84       /// value \p symbolValue.  These symbols are searched before any
  85       /// libraries.
  86       /// @brief Add searchable symbol/value pair.
  87       static void AddSymbol(const char* symbolName, void *symbolValue);
  88
  89       /// @brief Convenience function for C++ophiles.
  90       static void AddSymbol(const std::string& symbolName, void *symbolValue) {
  91         AddSymbol(symbolName.c_str(), symbolValue);
  92       }
  93
  94     /// @}
  95     /// @name Accessors
  96     /// @{
  97     public:
  98       /// Looks up a \p symbolName in the DynamicLibrary and returns its address
  99       /// if it exists. If the symbol does not exist, returns (void*)0.
 100       /// @returns the address of the symbol or 0.
 101       /// @brief Get the address of a symbol in the DynamicLibrary.
 102       void* GetAddressOfSymbol(const char* symbolName);
 103
 104       /// @brief Convenience function for C++ophiles.
 105       void* GetAddressOfSymbol(const std::string& symbolName) {
 106         return GetAddressOfSymbol(symbolName.c_str());
 107       }
 108
 109     /// @}
 110     /// @name Implementation
 111     /// @{
 112     protected:
 113       void* handle;  // Opaque handle for information about the library
 114
 115       DynamicLibrary(const DynamicLibrary&); ///< Do not implement
 116       DynamicLibrary& operator=(const DynamicLibrary&); ///< Do not implement
 117     /// @}
 118   };
 119
 120 } // End sys namespace
 121 } // End llvm namespace
 122
 123 FORCE_DEFINING_FILE_TO_BE_LINKED(SystemDynamicLibrary)
 124
 125 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H