1 //===-- llvm/Support/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===// 2 // 3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4 // See https://llvm.org/LICENSE.txt for license information. 5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6 // 7 //===----------------------------------------------------------------------===// 8 // 9 // This file declares the sys::DynamicLibrary class. 10 // 11 //===----------------------------------------------------------------------===// 12 13 #ifndef LLVM_SUPPORT_DYNAMICLIBRARY_H 14 #define LLVM_SUPPORT_DYNAMICLIBRARY_H 15 16 #include <string> 17 18 namespace llvm { 19 20 class StringRef; 21 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 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 /// 34 /// Note: there is currently no interface for temporarily loading a library, 35 /// or for unloading libraries when the LLVM library is unloaded. 36 class DynamicLibrary { 37 // Placeholder whose address represents an invalid library. 38 // We use this instead of NULL or a pointer-int pair because the OS library 39 // might define 0 or 1 to be "special" handles, such as "search all". 40 static char Invalid; 41 42 // Opaque data used to interface with OS-specific dynamic library handling. 43 void *Data; 44 45 public: 46 explicit DynamicLibrary(void *data = &Invalid) : Data(data) {} 47 48 /// Returns true if the object refers to a valid library. 49 bool isValid() const { return Data != &Invalid; } 50 51 /// Searches through the library for the symbol \p symbolName. If it is 52 /// found, the address of that symbol is returned. If not, NULL is returned. 53 /// Note that NULL will also be returned if the library failed to load. 54 /// Use isValid() to distinguish these cases if it is important. 55 /// Note that this will \e not search symbols explicitly registered by 56 /// AddSymbol(). 57 void *getAddressOfSymbol(const char *symbolName); 58 59 /// This function permanently loads the dynamic library at the given path. 60 /// The library will only be unloaded when llvm_shutdown() is called. 61 /// This returns a valid DynamicLibrary instance on success and an invalid 62 /// instance on failure (see isValid()). \p *errMsg will only be modified 63 /// if the library fails to load. 64 /// 65 /// It is safe to call this function multiple times for the same library. 66 /// Open a dynamic library permanently. 67 static DynamicLibrary getPermanentLibrary(const char *filename, 68 std::string *errMsg = nullptr); 69 70 /// Registers an externally loaded library. The library will be unloaded 71 /// when the program terminates. 72 /// 73 /// It is safe to call this function multiple times for the same library, 74 /// though ownership is only taken if there was no error. 75 /// 76 /// \returns An empty \p DynamicLibrary if the library was already loaded. 77 static DynamicLibrary addPermanentLibrary(void *handle, 78 std::string *errMsg = nullptr); 79 80 /// This function permanently loads the dynamic library at the given path. 81 /// Use this instead of getPermanentLibrary() when you won't need to get 82 /// symbols from the library itself. 83 /// 84 /// It is safe to call this function multiple times for the same library. 85 static bool LoadLibraryPermanently(const char *Filename, 86 std::string *ErrMsg = nullptr) { 87 return !getPermanentLibrary(Filename, ErrMsg).isValid(); 88 } 89 90 enum SearchOrdering { 91 /// SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when 92 /// DynamicLibrary::getPermanentLibrary(NULL) has been called or 93 /// search the list of explcitly loaded symbols if not. 94 SO_Linker, 95 /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would. 96 SO_LoadedFirst, 97 /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries. 98 /// Only useful to search if libraries with RTLD_LOCAL have been added. 99 SO_LoadedLast, 100 /// SO_LoadOrder - Or this in to search libraries in the ordered loaded. 101 /// The default bahaviour is to search loaded libraries in reverse. 102 SO_LoadOrder = 4 103 }; 104 static SearchOrdering SearchOrder; // = SO_Linker 105 106 /// This function will search through all previously loaded dynamic 107 /// libraries for the symbol \p symbolName. If it is found, the address of 108 /// that symbol is returned. If not, null is returned. Note that this will 109 /// search permanently loaded libraries (getPermanentLibrary()) as well 110 /// as explicitly registered symbols (AddSymbol()). 111 /// @throws std::string on error. 112 /// Search through libraries for address of a symbol 113 static void *SearchForAddressOfSymbol(const char *symbolName); 114 115 /// Convenience function for C++ophiles. 116 static void *SearchForAddressOfSymbol(const std::string &symbolName) { 117 return SearchForAddressOfSymbol(symbolName.c_str()); 118 } 119 120 /// This functions permanently adds the symbol \p symbolName with the 121 /// value \p symbolValue. These symbols are searched before any 122 /// libraries. 123 /// Add searchable symbol/value pair. 124 static void AddSymbol(StringRef symbolName, void *symbolValue); 125 126 class HandleSet; 127 }; 128 129 } // End sys namespace 130 } // End llvm namespace 131 132 #endif 133