LLVM  10.0.0svn
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.
33  ///
34  /// Note: there is currently no interface for temporarily loading a library,
35  /// or for unloading libraries when the LLVM library is unloaded.
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 
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.
95  /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
97  /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
98  /// Only useful to search if libraries with RTLD_LOCAL have been added.
100  /// SO_LoadOrder - Or this in to search libraries in the ordered loaded.
101  /// The default bahaviour is to search loaded libraries in reverse.
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
static void * SearchForAddressOfSymbol(const char *symbolName)
This function will search through all previously loaded dynamic libraries for the symbol symbolName...
This class represents lattice values for constants.
Definition: AllocatorList.h:23
DynamicLibrary(void *data=&Invalid)
static void * SearchForAddressOfSymbol(const std::string &symbolName)
Convenience function for C++ophiles.
void * getAddressOfSymbol(const char *symbolName)
Searches through the library for the symbol symbolName.
static bool LoadLibraryPermanently(const char *Filename, std::string *ErrMsg=nullptr)
This function permanently loads the dynamic library at the given path.
This class provides a portable interface to dynamic libraries which also might be known as shared lib...
static DynamicLibrary addPermanentLibrary(void *handle, std::string *errMsg=nullptr)
Registers an externally loaded library.
bool isValid() const
Returns true if the object refers to a valid library.
static DynamicLibrary getPermanentLibrary(const char *filename, std::string *errMsg=nullptr)
This function permanently loads the dynamic library at the given path.
SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
StringRef filename(StringRef path, Style style=Style::native)
Get filename.
Definition: Path.cpp:565
SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when DynamicLibrary::getPermanentLibrary(NU...
static void AddSymbol(StringRef symbolName, void *symbolValue)
This functions permanently adds the symbol symbolName with the value symbolValue. ...
static SearchOrdering SearchOrder
SO_LoadOrder - Or this in to search libraries in the ordered loaded.
StringRef - Represent a constant reference to a string, i.e.
Definition: StringRef.h:48