#include <Pt/System/Library.h>

Shared library loader. More...

Public Member Functions
	Library ()
	Default Constructor which does not load a library.
	Library (const Path &path)
	Loads a shared library.
	Library (const Library &other)
	Copy constructor.
Library &	operator= (const Library &other)
	Assignment operator.
	~Library ()
	The destructor unloads the shared library from memory.
Library &	open (const Path &path)
	Loads a shared library.
void	close ()
	Closes the shared library.
void *	operator[] (const char *symbol) const
	Resolves the symbol symbol from the shared library Returns the address of the symbol or 0 if it was not found.
void *	resolve (const char *symbol) const
	Resolves the symbol symbol from the shared library Returns the address of the symbol or 0 if it was not found.
	operator const void * () const
	Returns null if invalid.
Symbol	getSymbol (const char *symbol) const
	Resolves the symbol symbol from the shared library.
bool	operator! () const
	Returns true if invalid.
const Path &	path () const
	Returns the path to the shared library image.

Static Public Member Functions
static const char *	suffix ()
	Returns the extension for shared libraries.
static const char *	prefix ()
	Returns the prefix for shared libraries.

Detailed Description

A process can load a shared library after it has started and resolve symbols from it. Library is the portable loader. It opens a library image and returns symbols by name.

typedef int (*MyFunc)();
 
Pt::System::Path libPath = "MyLib";
Pt::System::Library library(libPath);
 
Pt::System::Symbol symbol = library.getSymbol("myFunction");
 
MyFunc func = reinterpret_cast<MyFunc>(symbol.sym());
int result = func();

The path "MyLib" is a basename. Construction and open() look for a file at the given path. If none is there, the path is extended by the platform suffix, then by the shared-library prefix. A basename is enough. An AccessFailed exception is thrown when no image is found. A second open() may close the image loaded before.

prefix() and suffix() return the platform naming pieces so a portable library name can be built without relying on that search. suffix() is ".so" on Linux and ".dll" on Windows. prefix() is "lib" on Linux and empty on Windows.

Pt::System::Path libPath = Pt::System::Library::prefix();
libPath += "MyLib";
libPath += Pt::System::Library::suffix();

getSymbol() returns a Symbol when the name exists. It throws SymbolNotFound otherwise. The address is Symbol::sym(). A Symbol holds the Library that produced it, so the image stays loaded while the symbol exists.

The index operator and resolve() return a void pointer, or a null pointer when the name is missing. They do not throw. getSymbol() treats a missing name as an error. The index operator leaves that test to the caller.

Standard C++ does not allow a cast from a void pointer to a function pointer. Nearly all runtimes implement that as an extension. The caller casts Symbol::sym() to a function pointer to call it.

Constructor & Destructor Documentation

◆ Library()

Library ( const Path & path )

explicit

If a file could not be found at the given path, the path will be extended by the platform-specific shared library extension first and then also by the shared library prefix. If still no file can be found an exception of type AccessFailed is thrown. Otherwise, the library is loaded immediately.

Member Function Documentation

◆ open()

Library & open ( const Path & path )

If a file could not be found at the given path, the path will be extended by the platform-specific shared library extension first and then also by the shared library prefix. If still no file can be found an exception of type AccessFailed is thrown. Otherwise, the library is loaded immediately. Calling this method twice might close the previously loaded library.

◆ getSymbol()

Symbol getSymbol ( const char * symbol ) const

Throws SymbolNotFound if the symbol could not be resolved.

◆ suffix()

const char * suffix ( )

static

Returns ".so" on Linux, ".dll" on Windows.

◆ prefix()

const char * prefix ( )