LLVM 20.0.0git
Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
llvm::sys::DynamicLibrary Class Reference

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"

Classes

class  HandleSet
 

Public Types

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

Public Member Functions

 DynamicLibrary (void *data=&Invalid)
 
void * getOSSpecificHandle () const
 Return the OS specific handle value.
 
bool isValid () const
 Returns true if the object refers to a valid library.
 
void * getAddressOfSymbol (const char *symbolName)
 Searches through the library for the symbol symbolName.
 

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 using the library load operation from the host operating system.
 
static DynamicLibrary addPermanentLibrary (void *handle, std::string *errMsg=nullptr)
 Registers an externally loaded library.
 
static bool LoadLibraryPermanently (const char *Filename, std::string *ErrMsg=nullptr)
 This function permanently loads the dynamic library at the given path.
 
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 host operating system.
 
static void closeLibrary (DynamicLibrary &Lib)
 This function closes the dynamic library at the given path, using the library close operation of the host operating system, and there is no guarantee if or when this will cause the library to be unloaded.
 
static void * SearchForAddressOfSymbol (const char *symbolName)
 This function will search through all previously loaded dynamic libraries for the symbol symbolName.
 
static void * SearchForAddressOfSymbol (const std::string &symbolName)
 Convenience function for C++ophiles.
 
static void AddSymbol (StringRef symbolName, void *symbolValue)
 This functions permanently adds the symbol symbolName with the value symbolValue.
 

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.

Definition at line 33 of file DynamicLibrary.h.

Member Enumeration Documentation

◆ 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 112 of file DynamicLibrary.h.

Constructor & Destructor Documentation

◆ DynamicLibrary()

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

Definition at line 43 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.

Definition at line 177 of file DynamicLibrary.cpp.

References G.

◆ 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 159 of file DynamicLibrary.cpp.

References G.

Referenced by LLVMAddSymbol().

◆ closeLibrary()

void DynamicLibrary::closeLibrary ( DynamicLibrary Lib)
static

This function closes the dynamic library at the given path, using the library close operation of the host operating system, and there is no guarantee if or when this will cause the library to be unloaded.

This function should be called only if the library was loaded using the getLibrary() function.

Definition at line 203 of file DynamicLibrary.cpp.

References G, and llvm::Lib.

◆ 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 212 of file DynamicLibrary.cpp.

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

Referenced by llvm::PassPlugin::Load(), llvm::orc::SelfExecutorProcessControl::lookupSymbolsAsync(), and llvm::orc::DynamicLibrarySearchGenerator::tryToGenerate().

◆ getLibrary()

DynamicLibrary DynamicLibrary::getLibrary ( const char FileName,
std::string *  Err = nullptr 
)
static

This function loads the dynamic library at the given path, using the library load operation from the host operating system.

The library instance will be closed when closeLibrary is called or global destructors are run, but there is no guarantee when the library will be unloaded.

This returns a valid DynamicLibrary instance on success and an invalid instance on failure (see isValid()). *Err will only be modified if the library fails to load.

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

Definition at line 189 of file DynamicLibrary.cpp.

References assert(), llvm::sys::DynamicLibrary::HandleSet::DLOpen(), and G.

◆ getOSSpecificHandle()

void * llvm::sys::DynamicLibrary::getOSSpecificHandle ( ) const
inline

Return the OS specific handle value.

Definition at line 46 of file DynamicLibrary.h.

◆ getPermanentLibrary()

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

This function permanently loads the dynamic library at the given path using the library load operation from the host operating system.

The library instance will only be closed when global destructors run, and there is no guarantee when the library will be unloaded.

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 165 of file DynamicLibrary.cpp.

References llvm::sys::DynamicLibrary::HandleSet::DLOpen(), and G.

Referenced by llvm::orc::DynamicLibrarySearchGenerator::Load(), llvm::PassPlugin::Load(), llvm::orc::SelfExecutorProcessControl::loadDylib(), LoadLibraryPermanently(), and llvm::orc::rt_bootstrap::SimpleExecutorDylibManager::open().

◆ isValid()

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

Returns true if the object refers to a valid library.

Definition at line 49 of file DynamicLibrary.h.

References llvm::Invalid.

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(), and llvm::PluginLoader::operator=().

◆ 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::stringon error. Search through libraries for address of a symbol

Definition at line 218 of file DynamicLibrary.cpp.

References G, Ptr, llvm::SearchForAddressOfSpecialSymbol(), and SearchOrder.

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

◆ SearchForAddressOfSymbol() [2/2]

static void * llvm::sys::DynamicLibrary::SearchForAddressOfSymbol ( const std::string &  symbolName)
inlinestatic

Convenience function for C++ophiles.

Definition at line 138 of file DynamicLibrary.h.

References SearchForAddressOfSymbol().

Member Data Documentation

◆ SearchOrder

DynamicLibrary::SearchOrdering DynamicLibrary::SearchOrder
static
Initial value:
=
@ SO_Linker
SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when DynamicLibrary::getPermanentLibrary(NU...

Definition at line 126 of file DynamicLibrary.h.

Referenced by SearchForAddressOfSymbol().


The documentation for this class was generated from the following files: