Coverage Report

Created: 2019-07-24 05:18

/Users/buildslave/jenkins/workspace/clang-stage2-coverage-R/llvm/include/llvm/Support/DynamicLibrary.h
Line
Count
Source (jump to first uncovered line)
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
532
    explicit DynamicLibrary(void *data = &Invalid) : Data(data) {}
47
48
    /// Returns true if the object refers to a valid library.
49
577
    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
493
                                       std::string *ErrMsg = nullptr) {
87
493
      return !getPermanentLibrary(Filename, ErrMsg).isValid();
88
493
    }
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
0
    static void *SearchForAddressOfSymbol(const std::string &symbolName) {
117
0
      return SearchForAddressOfSymbol(symbolName.c_str());
118
0
    }
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