Low level secure dynamic linker access. More...

#include <dyn_linker.hpp>

Inheritance diagram for jau::os::DynamicLinker:

Collaboration diagram for jau::os::DynamicLinker:

Public Types
typedef void *	libhandle_t
	library handle

typedef void *	symhandle_t
	symbol handle within a library

Public Member Functions
virtual	~DynamicLinker () noexcept=default

void	closeLibrary (libhandle_t handle) noexcept
	Security checks are implicit by previous call of `openLibraryLocal(const std::string_view&, boolean)` or `openLibraryGlobal(const std::string_view&, boolean)` retrieving the `librarHandle`.

std::string	getLastError () noexcept
	Returns a string containing the last error.

const char *	lookupLibraryPathname (libhandle_t handle, const std::string &symbolName) noexcept

symhandle_t	lookupSymbol (libhandle_t handle, const std::string &symbolName) noexcept

symhandle_t	lookupSymbolGlobal (const std::string &symbolName) noexcept

libhandle_t	openLibraryGlobal (const std::string &pathname) noexcept
	Opens the named library, allowing system wide access for other users.

libhandle_t	openLibraryLocal (const std::string &pathname) noexcept
	Opens the named library, restricting access to this process.

Static Public Member Functions
static std::vector< std::string >	enumerateLibraryPaths (const std::string &libName, bool searchSystemPath=false, bool searchSystemPathFirst=false) noexcept
	Returns list of potential absolute library filenames.

static DynamicLinker &	get () noexcept
	Returns static singleton instance of DynamicLinker.

static std::string	getBaseName (const std::string &filename, const bool isBasename=false, const bool caseInsensitive=jau::os::is_windows()) noexcept
	Returns the library basename, i.e.

static constexpr_cxx20 std::string	getCanonicalName (const std::string &basename, const bool checkIsCanonical=true) noexcept
	Returns canonical library name for this system from given library-basename, e.g.

static constexpr_cxx20 std::string	getDefaultPrefix () noexcept
	Returns the native library prefix, e.g.

static constexpr_cxx20 std::string	getDefaultSuffix () noexcept
	Returns the native library suffix including the dot, e.g.

static constexpr_cxx20 std::string	getEnvLibPathVarName () noexcept
	Returns the environment library path variable name, e.g.

static std::vector< std::string >	getSystemEnvLibraryPaths ()
	Returns a list of system paths, from the `getSystemEnvLibraryPathVarname()` variable.

static bool	isCanonicalName (const std::string &filename, const bool isBasename=false, const bool caseInsensitive=jau::os::is_windows()) noexcept
	Returns true if the given filename contains the canonical prefix and suffix, otherwise returns false.

Protected Member Functions
	DynamicLinker () noexcept=default

virtual void	closeLibraryImpl (libhandle_t handle) noexcept=0

LibRef_ref	decrLibRefCount (const libhandle_t handle) noexcept

virtual std::string	getLastErrorImpl () noexcept=0

LibRef_ref	incrLibRefCount (const libhandle_t handle, const std::string &libName) noexcept

virtual const char *	lookupLibraryPathnameImpl (libhandle_t libraryHandle, const std::string &symbolName) noexcept=0

virtual symhandle_t	lookupSymbolGlobalImpl (const std::string &symbolName) noexcept=0

virtual symhandle_t	lookupSymbolLocalImpl (libhandle_t handle, const std::string &symbolName) noexcept=0

virtual libhandle_t	openLibraryGlobalImpl (const std::string &pathname) noexcept=0

virtual libhandle_t	openLibraryLocalImpl (const std::string &pathname) noexcept=0

Static Protected Attributes
static constexpr const bool	DEBUG_LOOKUP = false

Detailed Description

Low level secure dynamic linker access.

Definition at line 45 of file dyn_linker.hpp.

Member Typedef Documentation

◆ libhandle_t

typedef void* jau::os::DynamicLinker::libhandle_t

library handle

Definition at line 48 of file dyn_linker.hpp.

◆ symhandle_t

typedef void* jau::os::DynamicLinker::symhandle_t

symbol handle within a library

Definition at line 50 of file dyn_linker.hpp.

Constructor & Destructor Documentation

◆ DynamicLinker()

jau::os::DynamicLinker::DynamicLinker ( )

protecteddefaultnoexcept

Here is the caller graph for this function:

◆ ~DynamicLinker()

virtual jau::os::DynamicLinker::~DynamicLinker ( )

virtualdefaultnoexcept

Member Function Documentation

◆ openLibraryGlobalImpl()

virtual libhandle_t jau::os::DynamicLinker::openLibraryGlobalImpl ( const std::string & pathname )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ openLibraryLocalImpl()

virtual libhandle_t jau::os::DynamicLinker::openLibraryLocalImpl ( const std::string & pathname )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ lookupLibraryPathnameImpl()

virtual const char * jau::os::DynamicLinker::lookupLibraryPathnameImpl	(	libhandle_t	libraryHandle,
		const std::string &	symbolName )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ lookupSymbolGlobalImpl()

virtual symhandle_t jau::os::DynamicLinker::lookupSymbolGlobalImpl ( const std::string & symbolName )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ lookupSymbolLocalImpl()

virtual symhandle_t jau::os::DynamicLinker::lookupSymbolLocalImpl	(	libhandle_t	handle,
		const std::string &	symbolName )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ closeLibraryImpl()

virtual void jau::os::DynamicLinker::closeLibraryImpl ( libhandle_t handle )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ getLastErrorImpl()

virtual std::string jau::os::DynamicLinker::getLastErrorImpl ( )

protectedpure virtualnoexcept

Implemented in jau::os::impl::UnixDynamicLinker.

Here is the caller graph for this function:

◆ incrLibRefCount()

LibRef_ref jau::os::DynamicLinker::incrLibRefCount	(	const libhandle_t	handle,
		const std::string &	libName )

inlineprotectednoexcept

Definition at line 102 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ decrLibRefCount()

LibRef_ref jau::os::DynamicLinker::decrLibRefCount ( const libhandle_t handle )

inlineprotectednoexcept

Definition at line 121 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ getEnvLibPathVarName()

static constexpr_cxx20 std::string jau::os::DynamicLinker::getEnvLibPathVarName ( )

inlinestaticnoexcept

Returns the environment library path variable name, e.g.

LD_LIBRARY_PATH

Definition at line 143 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ getSystemEnvLibraryPaths()

static std::vector< std::string > jau::os::DynamicLinker::getSystemEnvLibraryPaths ( )

inlinestatic

Returns a list of system paths, from the getSystemEnvLibraryPathVarname() variable.

Definition at line 155 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ getDefaultPrefix()

static constexpr_cxx20 std::string jau::os::DynamicLinker::getDefaultPrefix ( )

inlinestaticnoexcept

Returns the native library prefix, e.g.

lib

Definition at line 160 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ getDefaultSuffix()

static constexpr_cxx20 std::string jau::os::DynamicLinker::getDefaultSuffix ( )

inlinestaticnoexcept

Returns the native library suffix including the dot, e.g.

.so

Definition at line 168 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ getCanonicalName()

static constexpr_cxx20 std::string jau::os::DynamicLinker::getCanonicalName	(	const std::string &	basename,
		const bool	checkIsCanonical = true )

inlinestaticnoexcept

Returns canonical library name for this system from given library-basename, e.g.

‘tool’ -> libtool.so if it is not yet canonical, see isCanonicalName().

Parameters

basename	the library basename
checkIsCanonical	pass true to first check is basename is already canonical, defaults to true

See also: isCanonicalName(); getBaseName(); jau::fs::basename()

Definition at line 186 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ isCanonicalName()

bool jau::os::DynamicLinker::isCanonicalName	(	const std::string &	filename,
		const bool	isBasename = false,
		const bool	caseInsensitive = jau::os::is_windows() )

staticnoexcept

Returns true if the given filename contains the canonical prefix and suffix, otherwise returns false.

Validation is performed case insensitive if caseInsensitive == true

Parameters

filename	the filename to test
isBasename	pass true if filename is a basename, otherwise false. Defaults to false. See jau::fs::basename().
caseInsensitive	perform prefix and suffix comparison case-insensitive, defaults to true on Windows otherwise false

See also: getCanonicalName(); getBaseName(); jau::fs::basename()

Definition at line 225 of file os_support.cpp.

Here is the caller graph for this function:

◆ getBaseName()

std::string jau::os::DynamicLinker::getBaseName	(	const std::string &	filename,
		const bool	isBasename = false,
		const bool	caseInsensitive = jau::os::is_windows() )

staticnoexcept

Returns the library basename, i.e.

the file basename without prefix nor suffix, performed case insensitive if caseInsensitive == true

Parameters

filename	the filename to process
isBasename	pass true if filename is a basename, otherwise false. Defaults to false. See jau::fs::basename().
caseInsensitive	perform prefix and suffix comparison case-insensitive, defaults to true on Windows otherwise false

Returns: basename of filename w/o path nor prefix or suffix, ie. /usr/lib/libDrinkBeer.so -> DrinkBeer on Unix systems

See also: getCanonicalName(); isCanonicalName(); jau::fs::basename()

Definition at line 221 of file os_support.cpp.

Here is the caller graph for this function:

◆ enumerateLibraryPaths()

std::vector< std::string > jau::os::DynamicLinker::enumerateLibraryPaths	(	const std::string &	libName,
		bool	searchSystemPath = false,
		bool	searchSystemPathFirst = false )

staticnoexcept

Returns list of potential absolute library filenames.

Parameters

libName	library basename (implies file-basename) or canonical-library-name as file-basename or absolute-path
searchSystemPath
searchSystemPathFirst

Definition at line 280 of file os_support.cpp.

Here is the caller graph for this function:

◆ get()

static DynamicLinker & jau::os::DynamicLinker::get ( )

inlinestaticnoexcept

Returns static singleton instance of DynamicLinker.

Definition at line 235 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ openLibraryGlobal()

libhandle_t jau::os::DynamicLinker::openLibraryGlobal ( const std::string & pathname )

inlinenoexcept

Opens the named library, allowing system wide access for other users.

Parameters

pathname the full pathname for the library to open

Returns: the library handle, maybe 0 if not found.

Definition at line 256 of file dyn_linker.hpp.

◆ openLibraryLocal()

libhandle_t jau::os::DynamicLinker::openLibraryLocal ( const std::string & pathname )

inlinenoexcept

Opens the named library, restricting access to this process.

Parameters

pathname the full pathname for the library to open

Returns: the library handle, maybe 0 if not found.

Definition at line 275 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ lookupLibraryPathname()

const char * jau::os::DynamicLinker::lookupLibraryPathname	(	libhandle_t	handle,
		const std::string &	symbolName )

inlinenoexcept

Parameters

libraryHandle	a library handle previously retrieved via `openLibraryLocal(const std::string_view&, boolean)` or `openLibraryGlobal(const std::string_view&, boolean)`.
symbolName	optional symbol name for an OS which requires the symbol's address to retrieve the path of the containing library

Returns: the library pathname if found and supported by OS or null.

Definition at line 293 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ lookupSymbolGlobal()

symhandle_t jau::os::DynamicLinker::lookupSymbolGlobal ( const std::string & symbolName )

inlinenoexcept

Parameters

symbolName global symbol name to lookup up system wide.

Returns: the symbol handle, maybe nullptr if not found.

Definition at line 306 of file dyn_linker.hpp.

◆ lookupSymbol()

symhandle_t jau::os::DynamicLinker::lookupSymbol	(	libhandle_t	handle,
		const std::string &	symbolName )

inlinenoexcept

Parameters

libraryHandle	a library handle previously retrieved via `openLibraryLocal(const std::string_view&, boolean)` or `openLibraryGlobal(const std::string_view&, boolean)`.
symbolName	global symbol name to lookup up system wide.

Returns: the symbol handle, maybe nullptr if not found.

Definition at line 320 of file dyn_linker.hpp.

Here is the caller graph for this function:

◆ closeLibrary()

void jau::os::DynamicLinker::closeLibrary ( libhandle_t handle )

inlinenoexcept

Security checks are implicit by previous call of openLibraryLocal(const std::string_view&, boolean) or openLibraryGlobal(const std::string_view&, boolean) retrieving the librarHandle.

Parameters

libraryHandle a library handle previously retrieved via openLibraryLocal(const std::string_view&, boolean) or openLibraryGlobal(const std::string_view&, boolean).

Definition at line 336 of file dyn_linker.hpp.

◆ getLastError()

std::string jau::os::DynamicLinker::getLastError ( )

inlinenoexcept

Returns a string containing the last error.

Maybe called for debugging purposed if any method fails.

Returns: error string, maybe null. A null or non-null value has no semantics.

Definition at line 353 of file dyn_linker.hpp.

Here is the caller graph for this function:

Member Data Documentation

◆ DEBUG_LOOKUP

const bool jau::os::DynamicLinker::DEBUG_LOOKUP = false

staticconstexprprotected

Definition at line 53 of file dyn_linker.hpp.

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

jaulib/include/jau/os/dyn_linker.hpp
jaulib/src/os_support.cpp
jaulib/src/unix/unix_dyn_linker.cpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ libhandle_t

◆ symhandle_t

Constructor & Destructor Documentation

◆ DynamicLinker()

◆ ~DynamicLinker()

Member Function Documentation

◆ openLibraryGlobalImpl()

◆ openLibraryLocalImpl()

◆ lookupLibraryPathnameImpl()

◆ lookupSymbolGlobalImpl()

◆ lookupSymbolLocalImpl()

◆ closeLibraryImpl()

◆ getLastErrorImpl()

◆ incrLibRefCount()

◆ decrLibRefCount()

◆ getEnvLibPathVarName()

◆ getSystemEnvLibraryPaths()

◆ getDefaultPrefix()

◆ getDefaultSuffix()

◆ getCanonicalName()

◆ isCanonicalName()

◆ getBaseName()

◆ enumerateLibraryPaths()

◆ get()

◆ openLibraryGlobal()

◆ openLibraryLocal()

◆ lookupLibraryPathname()

◆ lookupSymbolGlobal()

◆ lookupSymbol()

◆ closeLibrary()

◆ getLastError()

Member Data Documentation

◆ DEBUG_LOOKUP