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
18namespace llvm {
19
20class StringRef;
21
22namespace 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.
33class DynamicLibrary {
34 // Placeholder whose address represents an invalid library.
35 // We use this instead of NULL or a pointer-int pair because the OS library
36 // might define 0 or 1 to be "special" handles, such as "search all".
37 static char Invalid;
38
39 // Opaque data used to interface with OS-specific dynamic library handling.
40 void *Data;
41
42public:
43 explicit DynamicLibrary(void *data = &Invalid) : Data(data) {}
44
45 /// Return the OS specific handle value.
46 void *getOSSpecificHandle() const { return 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 /// using the library load operation from the host operating system. The
61 /// library instance will only be closed when global destructors run, and
62 /// there is no guarantee when the library will be unloaded.
63 ///
64 /// This returns a valid DynamicLibrary instance on success and an invalid
65 /// instance on failure (see isValid()). \p *errMsg will only be modified if
66 /// the library fails to load.
67 ///
68 /// It is safe to call this function multiple times for the same library.
69 /// Open a dynamic library permanently.
70 static DynamicLibrary getPermanentLibrary(const char *filename,
71 std::string *errMsg = nullptr);
72
73 /// Registers an externally loaded library. The library will be unloaded
74 /// when the program terminates.
75 ///
76 /// It is safe to call this function multiple times for the same library,
77 /// though ownership is only taken if there was no error.
78 static DynamicLibrary addPermanentLibrary(void *handle,
79 std::string *errMsg = nullptr);
80
81 /// This function permanently loads the dynamic library at the given path.
82 /// Use this instead of getPermanentLibrary() when you won't need to get
83 /// symbols from the library itself.
84 ///
85 /// It is safe to call this function multiple times for the same library.
86 static bool LoadLibraryPermanently(const char *Filename,
87 std::string *ErrMsg = nullptr) {
88 return !getPermanentLibrary(filename: Filename, errMsg: ErrMsg).isValid();
89 }
90
91 /// This function loads the dynamic library at the given path, using the
92 /// library load operation from the host operating system. The library
93 /// instance will be closed when closeLibrary is called or global destructors
94 /// are run, but there is no guarantee when the library will be unloaded.
95 ///
96 /// This returns a valid DynamicLibrary instance on success and an invalid
97 /// instance on failure (see isValid()). \p *Err will only be modified if the
98 /// library fails to load.
99 ///
100 /// It is safe to call this function multiple times for the same library.
101 static DynamicLibrary getLibrary(const char *FileName,
102 std::string *Err = nullptr);
103
104 /// This function closes the dynamic library at the given path, using the
105 /// library close operation of the host operating system, and there is no
106 /// guarantee if or when this will cause the the library to be unloaded.
107 ///
108 /// This function should be called only if the library was loaded using the
109 /// getLibrary() function.
110 static void closeLibrary(DynamicLibrary &Lib);
111
112 enum SearchOrdering {
113 /// SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when
114 /// DynamicLibrary::getPermanentLibrary(NULL) has been called or
115 /// search the list of explcitly loaded symbols if not.
116 SO_Linker,
117 /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
118 SO_LoadedFirst,
119 /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
120 /// Only useful to search if libraries with RTLD_LOCAL have been added.
121 SO_LoadedLast,
122 /// SO_LoadOrder - Or this in to search libraries in the ordered loaded.
123 /// The default bahaviour is to search loaded libraries in reverse.
124 SO_LoadOrder = 4
125 };
126 static SearchOrdering SearchOrder; // = SO_Linker
127
128 /// This function will search through all previously loaded dynamic
129 /// libraries for the symbol \p symbolName. If it is found, the address of
130 /// that symbol is returned. If not, null is returned. Note that this will
131 /// search permanently loaded libraries (getPermanentLibrary()) as well
132 /// as explicitly registered symbols (AddSymbol()).
133 /// @throws std::string on error.
134 /// Search through libraries for address of a symbol
135 static void *SearchForAddressOfSymbol(const char *symbolName);
136
137 /// Convenience function for C++ophiles.
138 static void *SearchForAddressOfSymbol(const std::string &symbolName) {
139 return SearchForAddressOfSymbol(symbolName: symbolName.c_str());
140 }
141
142 /// This functions permanently adds the symbol \p symbolName with the
143 /// value \p symbolValue. These symbols are searched before any
144 /// libraries.
145 /// Add searchable symbol/value pair.
146 static void AddSymbol(StringRef symbolName, void *symbolValue);
147
148 class HandleSet;
149};
150
151} // End sys namespace
152} // End llvm namespace
153
154#endif
155

source code of include/llvm-17/llvm/Support/DynamicLibrary.h