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
22 /// This class provides a portable interface to dynamic libraries which also
23 /// might be known as shared libraries, shared objects, dynamic shared
24 /// objects, or dynamic link libraries. Regardless of the terminology or the
25 /// operating system interface, this class provides a portable interface that
26 /// allows dynamic libraries to be loaded and searched for externally
27 /// defined symbols. This is typically used to provide "plug-in" support.
28 /// It also allows for symbols to be defined which don't live in any library,
29 /// but rather the main program itself, useful on Windows where the main
30 /// executable cannot be searched.
31 class DynamicLibrary {
32 DynamicLibrary(); // DO NOT IMPLEMENT
34 /// This function allows a library to be loaded without instantiating a
35 /// DynamicLibrary object. Consequently, it is marked as being permanent
36 /// and will only be unloaded when the program terminates. This returns
37 /// false on success or returns true and fills in *ErrMsg on failure.
38 /// @brief Open a dynamic library permanently.
40 /// NOTE: This function is not thread safe.
42 static bool LoadLibraryPermanently(const char *filename,
43 std::string *ErrMsg = 0);
45 /// This function will search through all previously loaded dynamic
46 /// libraries for the symbol \p symbolName. If it is found, the addressof
47 /// that symbol is returned. If not, null is returned. Note that this will
48 /// search permanently loaded libraries (LoadLibraryPermanently) as well
49 /// as ephemerally loaded libraries (constructors).
50 /// @throws std::string on error.
51 /// @brief Search through libraries for address of a symbol
53 /// NOTE: This function is not thread safe.
55 static void *SearchForAddressOfSymbol(const char *symbolName);
57 /// @brief Convenience function for C++ophiles.
59 /// NOTE: This function is not thread safe.
61 static void *SearchForAddressOfSymbol(const std::string &symbolName) {
62 return SearchForAddressOfSymbol(symbolName.c_str());
65 /// This functions permanently adds the symbol \p symbolName with the
66 /// value \p symbolValue. These symbols are searched before any
68 /// @brief Add searchable symbol/value pair.
70 /// NOTE: This function is not thread safe.
72 static void AddSymbol(const char *symbolName, void *symbolValue);
74 /// @brief Convenience function for C++ophiles.
76 /// NOTE: This function is not thread safe.
78 static void AddSymbol(const std::string &symbolName, void *symbolValue) {
79 AddSymbol(symbolName.c_str(), symbolValue);
83 } // End sys namespace
84 } // End llvm namespace
86 #endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H