Coverage Report

Created: 2017-10-03 07:32

/Users/buildslave/jenkins/sharedspace/clang-stage2-coverage-R@2/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
//                     The LLVM Compiler Infrastructure
4
//
5
// This file is distributed under the University of Illinois Open Source
6
// License. See LICENSE.TXT for details.
7
//
8
//===----------------------------------------------------------------------===//
9
//
10
// This file declares the sys::DynamicLibrary class.
11
//
12
//===----------------------------------------------------------------------===//
13
14
#ifndef LLVM_SUPPORT_DYNAMICLIBRARY_H
15
#define LLVM_SUPPORT_DYNAMICLIBRARY_H
16
17
#include <string>
18
19
namespace llvm {
20
21
class StringRef;
22
23
namespace sys {
24
25
  /// This class provides a portable interface to dynamic libraries which also
26
  /// might be known as shared libraries, shared objects, dynamic shared
27
  /// objects, or dynamic link libraries. Regardless of the terminology or the
28
  /// operating system interface, this class provides a portable interface that
29
  /// allows dynamic libraries to be loaded and searched for externally
30
  /// defined symbols. This is typically used to provide "plug-in" support.
31
  /// It also allows for symbols to be defined which don't live in any library,
32
  /// but rather the main program itself, useful on Windows where the main
33
  /// executable cannot be searched.
34
  ///
35
  /// Note: there is currently no interface for temporarily loading a library,
36
  /// or for unloading libraries when the LLVM library is unloaded.
37
  class DynamicLibrary {
38
    // Placeholder whose address represents an invalid library.
39
    // We use this instead of NULL or a pointer-int pair because the OS library
40
    // might define 0 or 1 to be "special" handles, such as "search all".
41
    static char Invalid;
42
43
    // Opaque data used to interface with OS-specific dynamic library handling.
44
    void *Data;
45
46
  public:
47
474
    explicit DynamicLibrary(void *data = &Invalid) : Data(data) {}
48
49
    /// Returns true if the object refers to a valid library.
50
477
    bool isValid() const { return Data != &Invalid; }
51
52
    /// Searches through the library for the symbol \p symbolName. If it is
53
    /// found, the address of that symbol is returned. If not, NULL is returned.
54
    /// Note that NULL will also be returned if the library failed to load.
55
    /// Use isValid() to distinguish these cases if it is important.
56
    /// Note that this will \e not search symbols explicitly registered by
57
    /// AddSymbol().
58
    void *getAddressOfSymbol(const char *symbolName);
59
60
    /// This function permanently loads the dynamic library at the given path.
61
    /// The library will only be unloaded when llvm_shutdown() is called.
62
    /// This returns a valid DynamicLibrary instance on success and an invalid
63
    /// instance on failure (see isValid()). \p *errMsg will only be modified
64
    /// if the library fails to load.
65
    ///
66
    /// It is safe to call this function multiple times for the same library.
67
    /// @brief Open a dynamic library permanently.
68
    static DynamicLibrary getPermanentLibrary(const char *filename,
69
                                              std::string *errMsg = nullptr);
70
71
    /// Registers an externally loaded library. The library will be unloaded
72
    /// when the program terminates.
73
    ///
74
    /// It is safe to call this function multiple times for the same library,
75
    /// though ownership is only taken if there was no error.
76
    ///
77
    /// \returns An empty \p DynamicLibrary if the library was already loaded.
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
470
                                       std::string *ErrMsg = nullptr) {
88
470
      return !getPermanentLibrary(Filename, ErrMsg).isValid();
89
470
    }
90
91
    enum SearchOrdering {
92
      /// SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when
93
      /// DynamicLibrary::getPermanentLibrary(NULL) has been called or
94
      /// search the list of explcitly loaded symbols if not.
95
      SO_Linker,
96
      /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
97
      SO_LoadedFirst,
98
      /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
99
      /// Only useful to search if libraries with RTLD_LOCAL have been added.
100
      SO_LoadedLast,
101
      /// SO_LoadOrder - Or this in to search libraries in the ordered loaded.
102
      /// The default bahaviour is to search loaded libraries in reverse.
103
      SO_LoadOrder = 4
104
    };
105
    static SearchOrdering SearchOrder; // = SO_Linker
106
107
    /// This function will search through all previously loaded dynamic
108
    /// libraries for the symbol \p symbolName. If it is found, the address of
109
    /// that symbol is returned. If not, null is returned. Note that this will
110
    /// search permanently loaded libraries (getPermanentLibrary()) as well
111
    /// as explicitly registered symbols (AddSymbol()).
112
    /// @throws std::string on error.
113
    /// @brief Search through libraries for address of a symbol
114
    static void *SearchForAddressOfSymbol(const char *symbolName);
115
116
    /// @brief Convenience function for C++ophiles.
117
0
    static void *SearchForAddressOfSymbol(const std::string &symbolName) {
118
0
      return SearchForAddressOfSymbol(symbolName.c_str());
119
0
    }
120
121
    /// This functions permanently adds the symbol \p symbolName with the
122
    /// value \p symbolValue.  These symbols are searched before any
123
    /// libraries.
124
    /// @brief Add searchable symbol/value pair.
125
    static void AddSymbol(StringRef symbolName, void *symbolValue);
126
127
    class HandleSet;
128
  };
129
130
} // End sys namespace
131
} // End llvm namespace
132
133
#endif