LLVM  16.0.0git
DynamicLibrary.h
Go to the documentation of this file.
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.
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 
42 public:
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.
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, 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 
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.
117  /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
119  /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
120  /// Only useful to search if libraries with RTLD_LOCAL have been added.
122  /// SO_LoadOrder - Or this in to search libraries in the ordered loaded.
123  /// The default bahaviour is to search loaded libraries in reverse.
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.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
llvm
This is an optimization pass for GlobalISel generic memory operations.
Definition: AddressRanges.h:18
llvm::sys::DynamicLibrary::getAddressOfSymbol
void * getAddressOfSymbol(const char *symbolName)
Searches through the library for the symbol symbolName.
Definition: DynamicLibrary.cpp:212
llvm::sys::DynamicLibrary::AddSymbol
static void AddSymbol(StringRef symbolName, void *symbolValue)
This functions permanently adds the symbol symbolName with the value symbolValue.
Definition: DynamicLibrary.cpp:159
llvm::sys::DynamicLibrary::getLibrary
static DynamicLibrary getLibrary(const char *FileName, std::string *Err=nullptr)
This function loads the dynamic library at the given path, using the library load operation from the ...
Definition: DynamicLibrary.cpp:189
llvm::sys::DynamicLibrary::getOSSpecificHandle
void * getOSSpecificHandle() const
Return the OS specific handle value.
Definition: DynamicLibrary.h:46
llvm::sys::DynamicLibrary::closeLibrary
static void closeLibrary(DynamicLibrary &Lib)
This function closes the dynamic library at the given path, using the library close operation of the ...
Definition: DynamicLibrary.cpp:203
llvm::sys::DynamicLibrary::DynamicLibrary
DynamicLibrary(void *data=&Invalid)
Definition: DynamicLibrary.h:43
llvm::sys::DynamicLibrary::SO_LoadedFirst
@ SO_LoadedFirst
SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
Definition: DynamicLibrary.h:118
handle
then ret i32 result Tail recursion elimination should handle
Definition: README.txt:355
llvm::Data
@ Data
Definition: SIMachineScheduler.h:55
llvm::sys::DynamicLibrary::addPermanentLibrary
static DynamicLibrary addPermanentLibrary(void *handle, std::string *errMsg=nullptr)
Registers an externally loaded library.
Definition: DynamicLibrary.cpp:177
llvm::sys::DynamicLibrary
This class provides a portable interface to dynamic libraries which also might be known as shared lib...
Definition: DynamicLibrary.h:33
llvm::sys::DynamicLibrary::getPermanentLibrary
static DynamicLibrary getPermanentLibrary(const char *filename, std::string *errMsg=nullptr)
This function permanently loads the dynamic library at the given path using the library load operatio...
Definition: DynamicLibrary.cpp:165
llvm::sys::DynamicLibrary::SO_LoadOrder
@ SO_LoadOrder
SO_LoadOrder - Or this in to search libraries in the ordered loaded.
Definition: DynamicLibrary.h:124
llvm::sys::DynamicLibrary::SearchForAddressOfSymbol
static void * SearchForAddressOfSymbol(const std::string &symbolName)
Convenience function for C++ophiles.
Definition: DynamicLibrary.h:138
llvm::sys::DynamicLibrary::SearchForAddressOfSymbol
static void * SearchForAddressOfSymbol(const char *symbolName)
This function will search through all previously loaded dynamic libraries for the symbol symbolName.
Definition: DynamicLibrary.cpp:218
llvm::sys::DynamicLibrary::isValid
bool isValid() const
Returns true if the object refers to a valid library.
Definition: DynamicLibrary.h:49
llvm::sys::DynamicLibrary::SO_LoadedLast
@ SO_LoadedLast
SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
Definition: DynamicLibrary.h:121
llvm::sys::DynamicLibrary::SO_Linker
@ SO_Linker
SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when DynamicLibrary::getPermanentLibrary(NU...
Definition: DynamicLibrary.h:116
llvm::sys::DynamicLibrary::SearchOrder
static SearchOrdering SearchOrder
Definition: DynamicLibrary.h:126
llvm::StringRef
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:50
llvm::sys::path::filename
StringRef filename(StringRef path, Style style=Style::native)
Get filename.
Definition: Path.cpp:577
llvm::sys::DynamicLibrary::SearchOrdering
SearchOrdering
Definition: DynamicLibrary.h:112
llvm::sys::DynamicLibrary::LoadLibraryPermanently
static bool LoadLibraryPermanently(const char *Filename, std::string *ErrMsg=nullptr)
This function permanently loads the dynamic library at the given path.
Definition: DynamicLibrary.h:86