1 //===-- llvm/System/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
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.
8 //===----------------------------------------------------------------------===//
10 // This file declares the sys::DynamicLibrary class.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H
15 #define LLVM_SYSTEM_DYNAMIC_LIBRARY_H
17 #include "llvm/System/Path.h"
23 /// This class provides a portable interface to dynamic libraries which also
24 /// might be known as shared libraries, shared objects, dynamic shared
25 /// objects, or dynamic link libraries. Regardless of the terminology or the
26 /// operating system interface, this class provides a portable interface that
27 /// allows dynamic libraries to be loaded and and searched for externally
28 /// defined symbols. This is typically used to provide "plug-in" support.
29 /// It also allows for symbols to be defined which don't live in any library,
30 /// but rather the main program itself, useful on Windows where the main
31 /// executable cannot be searched.
33 /// @brief Portable dynamic library abstraction.
34 class DynamicLibrary {
35 /// @name Constructors
38 /// Construct a DynamicLibrary that represents the currently executing
39 /// program. The program must have been linked with -export-dynamic or
40 /// -dlopen self for this to work. Any symbols retrieved with the
41 /// GetAddressOfSymbol function will refer to the program not to any
43 /// @throws std::string indicating why the program couldn't be opened.
44 /// @brief Open program as dynamic library.
47 /// This is the constructor for DynamicLibrary instances. It will open
48 /// the dynamic library specified by the filename Path.
49 /// @throws std::string indicating why the library couldn't be opened.
50 /// @brief Open a dynamic library.
51 DynamicLibrary(const char* filename);
53 /// After destruction, the symbols of the library will no longer be
54 /// available to the program. It is important to make sure the lifespan
55 /// of a DynamicLibrary exceeds the lifetime of the pointers returned
56 /// by the GetAddressOfSymbol otherwise the program may walk off into
57 /// uncharted territory.
58 /// @see GetAddressOfSymbol.
59 /// @brief Closes the DynamicLibrary
66 /// This function allows a library to be loaded without instantiating a
67 /// DynamicLibrary object. Consequently, it is marked as being permanent
68 /// and will only be unloaded when the program terminates. This returns
69 /// false on success or returns true and fills in *ErrMsg on failure.
70 /// @brief Open a dynamic library permanently.
71 static bool LoadLibraryPermanently(const char* filename,
72 std::string *ErrMsg = 0);
74 /// This function will search through all previously loaded dynamic
75 /// libraries for the symbol \p symbolName. If it is found, the addressof
76 /// that symbol is returned. If not, null is returned. Note that this will
77 /// search permanently loaded libraries (LoadLibraryPermanently) as well
78 /// as ephemerally loaded libraries (constructors).
79 /// @throws std::string on error.
80 /// @brief Search through libraries for address of a symbol
81 static void* SearchForAddressOfSymbol(const char* symbolName);
83 /// @brief Convenience function for C++ophiles.
84 static void* SearchForAddressOfSymbol(const std::string& symbolName) {
85 return SearchForAddressOfSymbol(symbolName.c_str());
88 /// This functions permanently adds the symbol \p symbolName with the
89 /// value \p symbolValue. These symbols are searched before any
91 /// @brief Add searchable symbol/value pair.
92 static void AddSymbol(const char* symbolName, void *symbolValue);
94 /// @brief Convenience function for C++ophiles.
95 static void AddSymbol(const std::string& symbolName, void *symbolValue) {
96 AddSymbol(symbolName.c_str(), symbolValue);
103 /// Looks up a \p symbolName in the DynamicLibrary and returns its address
104 /// if it exists. If the symbol does not exist, returns (void*)0.
105 /// @returns the address of the symbol or 0.
106 /// @brief Get the address of a symbol in the DynamicLibrary.
107 void* GetAddressOfSymbol(const char* symbolName);
109 /// @brief Convenience function for C++ophiles.
110 void* GetAddressOfSymbol(const std::string& symbolName) {
111 return GetAddressOfSymbol(symbolName.c_str());
115 /// @name Implementation
118 void* handle; // Opaque handle for information about the library
120 DynamicLibrary(const DynamicLibrary&); ///< Do not implement
121 DynamicLibrary& operator=(const DynamicLibrary&); ///< Do not implement
125 } // End sys namespace
126 } // End llvm namespace
128 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H