1 //===-- llvm/System/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // 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"
18 #include "llvm/System/IncludeFile.h"
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 class DynamicLibrary {
34 /// @name Constructors
37 /// Construct a DynamicLibrary that represents the currently executing
38 /// program. The program must have been linked with -export-dynamic or
39 /// -dlopen self for this to work.
40 /// @throws std::string indicating why the program couldn't be opened.
41 /// @brief Open program as dynamic library.
44 /// After destruction, the symbols of the library will no longer be
45 /// available to the program.
46 /// @brief Closes the DynamicLibrary
53 /// This function allows a library to be loaded without instantiating a
54 /// DynamicLibrary object. Consequently, it is marked as being permanent
55 /// and will only be unloaded when the program terminates. This returns
56 /// false on success or returns true and fills in *ErrMsg on failure.
57 /// @brief Open a dynamic library permanently.
58 static bool LoadLibraryPermanently(const char* filename,
59 std::string *ErrMsg = 0);
61 /// This function will search through all previously loaded dynamic
62 /// libraries for the symbol \p symbolName. If it is found, the addressof
63 /// that symbol is returned. If not, null is returned. Note that this will
64 /// search permanently loaded libraries (LoadLibraryPermanently) as well
65 /// as ephemerally loaded libraries (constructors).
66 /// @throws std::string on error.
67 /// @brief Search through libraries for address of a symbol
68 static void* SearchForAddressOfSymbol(const char* symbolName);
70 /// @brief Convenience function for C++ophiles.
71 static void* SearchForAddressOfSymbol(const std::string& symbolName) {
72 return SearchForAddressOfSymbol(symbolName.c_str());
75 /// This functions permanently adds the symbol \p symbolName with the
76 /// value \p symbolValue. These symbols are searched before any
78 /// @brief Add searchable symbol/value pair.
79 static void AddSymbol(const char* symbolName, void *symbolValue);
81 /// @brief Convenience function for C++ophiles.
82 static void AddSymbol(const std::string& symbolName, void *symbolValue) {
83 AddSymbol(symbolName.c_str(), symbolValue);
87 /// @name Implementation
90 void* handle; // Opaque handle for information about the library
91 DynamicLibrary(const DynamicLibrary&); ///< Do not implement
92 DynamicLibrary& operator=(const DynamicLibrary&); ///< Do not implement
96 } // End sys namespace
97 } // End llvm namespace
99 FORCE_DEFINING_FILE_TO_BE_LINKED(SystemDynamicLibrary)
101 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H