This class provides a portable interface to dynamic libraries which also might be known as shared libraries, shared objects, dynamic shared objects, or dynamic link libraries. More...

#include "llvm/Support/DynamicLibrary.h"

Collaboration diagram for llvm::sys::DynamicLibrary:

[legend]

Classes
class	HandleSet

Public Types
enum	SearchOrdering { SO_Linker, SO_LoadedFirst, SO_LoadedLast, SO_LoadOrder = 4 }

Public Member Functions
	DynamicLibrary (void *data=&Invalid)

bool	isValid () const
	Returns true if the object refers to a valid library. More...

void *	getAddressOfSymbol (const char *symbolName)
	Searches through the library for the symbol `symbolName`. More...

Static Public Member Functions
static DynamicLibrary	getPermanentLibrary (const char filename, std::string errMsg=nullptr)
	This function permanently loads the dynamic library at the given path. More...

static DynamicLibrary	addPermanentLibrary (void handle, std::string errMsg=nullptr)
	Registers an externally loaded library. More...

static bool	LoadLibraryPermanently (const char Filename, std::string ErrMsg=nullptr)
	This function permanently loads the dynamic library at the given path. More...

static void *	SearchForAddressOfSymbol (const char *symbolName)
	This function will search through all previously loaded dynamic libraries for the symbol `symbolName`. More...

static void *	SearchForAddressOfSymbol (const std::string &symbolName)
	Convenience function for C++ophiles. More...

static void	AddSymbol (StringRef symbolName, void *symbolValue)
	This functions permanently adds the symbol `symbolName` with the value `symbolValue`. More...

Static Public Attributes
static SearchOrdering	SearchOrder

Detailed Description

This class provides a portable interface to dynamic libraries which also might be known as shared libraries, shared objects, dynamic shared objects, or dynamic link libraries.

Regardless of the terminology or the operating system interface, this class provides a portable interface that allows dynamic libraries to be loaded and searched for externally defined symbols. This is typically used to provide "plug-in" support. It also allows for symbols to be defined which don't live in any library, but rather the main program itself, useful on Windows where the main executable cannot be searched.

Note: there is currently no interface for temporarily loading a library, or for unloading libraries when the LLVM library is unloaded.

Definition at line 37 of file DynamicLibrary.h.

Member Enumeration Documentation

◆ SearchOrdering

enum llvm::sys::DynamicLibrary::SearchOrdering

Enumerator
SO_Linker	SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when DynamicLibrary::getPermanentLibrary(NULL) has been called or search the list of explcitly loaded symbols if not.
SO_LoadedFirst	SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
SO_LoadedLast	SO_LoadedLast - Search as SO_Linker would, then loaded libraries. Only useful to search if libraries with RTLD_LOCAL have been added.
SO_LoadOrder	SO_LoadOrder - Or this in to search libraries in the ordered loaded. The default bahaviour is to search loaded libraries in reverse.

Definition at line 91 of file DynamicLibrary.h.

Constructor & Destructor Documentation

◆ DynamicLibrary()

llvm::sys::DynamicLibrary::DynamicLibrary ( void * data = &Invalid )

inlineexplicit

Definition at line 47 of file DynamicLibrary.h.

Member Function Documentation

◆ addPermanentLibrary()

DynamicLibrary DynamicLibrary::addPermanentLibrary	(	void *	handle,
		std::string *	errMsg = `nullptr`
	)

static

Registers an externally loaded library.

The library will be unloaded when the program terminates.

It is safe to call this function multiple times for the same library, though ownership is only taken if there was no error.

Returns: An empty DynamicLibrary if the library was already loaded.

Definition at line 164 of file DynamicLibrary.cpp.

Referenced by isValid().

◆ AddSymbol()

void DynamicLibrary::AddSymbol	(	StringRef	symbolName,
		void *	symbolValue
	)

static

This functions permanently adds the symbol symbolName with the value symbolValue.

These symbols are searched before any libraries. Add searchable symbol/value pair.

Definition at line 144 of file DynamicLibrary.cpp.

References llvm::Lock, and llvm::AMDGPU::HSAMD::Kernel::Key::SymbolName.

Referenced by LLVMAddSymbol(), and SearchForAddressOfSymbol().

◆ getAddressOfSymbol()

void * DynamicLibrary::getAddressOfSymbol ( const char * symbolName )

Searches through the library for the symbol symbolName.

If it is found, the address of that symbol is returned. If not, NULL is returned. Note that NULL will also be returned if the library failed to load. Use isValid() to distinguish these cases if it is important. Note that this will not search symbols explicitly registered by AddSymbol().

Definition at line 174 of file DynamicLibrary.cpp.

References llvm::Data, llvm::sys::DynamicLibrary::HandleSet::DLSym(), and isValid().

Referenced by isValid(), and llvm::orc::DynamicLibrarySearchGenerator::operator()().

◆ getPermanentLibrary()

DynamicLibrary DynamicLibrary::getPermanentLibrary	(	const char *	filename,
		std::string *	errMsg = `nullptr`
	)

static

This function permanently loads the dynamic library at the given path.

The library will only be unloaded when llvm_shutdown() is called. This returns a valid DynamicLibrary instance on success and an invalid instance on failure (see isValid()). *errMsg will only be modified if the library fails to load.

It is safe to call this function multiple times for the same library. Open a dynamic library permanently.

Definition at line 149 of file DynamicLibrary.cpp.

Referenced by isValid(), llvm::PassPlugin::Load(), llvm::orc::DynamicLibrarySearchGenerator::Load(), and LoadLibraryPermanently().

◆ isValid()

bool llvm::sys::DynamicLibrary::isValid ( ) const

inline

Returns true if the object refers to a valid library.

Definition at line 50 of file DynamicLibrary.h.

References addPermanentLibrary(), llvm::sys::path::filename(), getAddressOfSymbol(), and getPermanentLibrary().

Referenced by getAddressOfSymbol(), llvm::PassPlugin::Load(), and LoadLibraryPermanently().

◆ LoadLibraryPermanently()

static bool llvm::sys::DynamicLibrary::LoadLibraryPermanently	(	const char *	Filename,
		std::string *	ErrMsg = `nullptr`
	)

inlinestatic

This function permanently loads the dynamic library at the given path.

Use this instead of getPermanentLibrary() when you won't need to get symbols from the library itself.

It is safe to call this function multiple times for the same library.

Definition at line 86 of file DynamicLibrary.h.

References getPermanentLibrary(), and isValid().

Referenced by llvm::EngineBuilder::create(), llvm::MCJIT::createJIT(), LLVMLoadLibraryPermanently(), llvm::PluginLoader::operator=(), and llvm::OProfileWrapper::OProfileWrapper().

◆ SearchForAddressOfSymbol() [1/2]

void * DynamicLibrary::SearchForAddressOfSymbol ( const char * symbolName )

static

This function will search through all previously loaded dynamic libraries for the symbol symbolName.

If it is found, the address of that symbol is returned. If not, null is returned. Note that this will search permanently loaded libraries (getPermanentLibrary()) as well as explicitly registered symbols (AddSymbol()).

Exceptions

std::string on error. Search through libraries for address of a symbol

Definition at line 180 of file DynamicLibrary.cpp.

References llvm::Lock, llvm::SearchForAddressOfSpecialSymbol(), and SearchOrder.

Referenced by llvm::__deregister_frame(), llvm::__register_frame(), llvm::Interpreter::callExternalFunction(), llvm::ExecutionEngine::emitGlobals(), llvm::RTDyldMemoryManager::getSymbolAddressInProcess(), LLVMSearchForAddressOfSymbol(), lookupFunction(), llvm::OProfileWrapper::OProfileWrapper(), and SearchForAddressOfSymbol().