# Poco

# class SharedLibrary

Library: Foundation
Package: SharedLibrary
Header: Poco/SharedLibrary.h

## Description

The SharedLibrary class dynamically loads shared libraries at run-time.

## Inheritance

Direct Base Classes: SharedLibraryImpl

All Base Classes: SharedLibraryImpl

## Member Summary

Member Functions: findMissingDependencies, getPath, getSymbol, hasSymbol, isLoaded, load, setSearchPath, suffix, unload

Inherited Functions: findMissingDependenciesImpl, findSymbolImpl, getPathImpl, isLoadedImpl, loadImpl, setSearchPathImpl, suffixImpl, unloadImpl

## Enumerations

### Flags

SHLIB_GLOBAL = 1

On platforms that use dlopen(), use RTLD_GLOBAL. This is the default if no flags are given.

This flag is ignored on platforms that do not use dlopen().

SHLIB_LOCAL = 2

On platforms that use dlopen(), use RTLD_LOCAL instead of RTLD_GLOBAL.

Note that if this flag is specified, RTTI (including dynamic_cast and throw) will not work for types defined in the shared library with GCC and possibly other compilers as well. See http://gcc.gnu.org/faq.html#dso for more information.

This flag is ignored on platforms that do not use dlopen().

## Constructors

### SharedLibrary

SharedLibrary();

Creates a SharedLibrary object.

### SharedLibrary

SharedLibrary(
const std::string & path
);

Creates a SharedLibrary object and loads a library from the given path.

### SharedLibrary

SharedLibrary(
const std::string & path,
int flags
);

Creates a SharedLibrary object and loads a library from the given path, using the given flags. See the Flags enumeration for valid values.

## Destructor

### ~SharedLibrary

virtual ~SharedLibrary();

Destroys the SharedLibrary. The actual library remains loaded.

## Member Functions

### findMissingDependencies

static std::vector < std::string > findMissingDependencies(
const std::string & path
);

Parses the shared library at the given path and returns a list of dependent libraries that cannot be found. If the library itself whose dependencies are checked is not found, it returns the library itself.

Useful for diagnosing why a library fails to load. On Windows, parses the PE import table. On Linux, parses the ELF dynamic section. On macOS, parses the Mach-O load commands.

Returns an empty vector if the file cannot be parsed or on unsupported platforms.

### getPath

const std::string & getPath() const;

Returns the path of the library, as specified in a call to load() or the constructor.

### getSymbol

void * getSymbol(
const std::string & name
);

Returns the address of the symbol with the given name. For functions, this is the entry point of the function. Throws a NotFoundException if the symbol does not exist.

### hasSymbol

bool hasSymbol(
const std::string & name
);

Returns true if and only if the loaded library contains a symbol with the given name.

### isLoaded

bool isLoaded() const;

Returns true if and only if a library has been loaded.

### load

void load(
const std::string & path
);

Loads a shared library from the given path. Throws a LibraryAlreadyLoadedException if a library has already been loaded. Throws a LibraryLoadException if the library cannot be loaded.

### load

void load(
const std::string & path,
int flags
);

Loads a shared library from the given path, using the given flags. See the Flags enumeration for valid values. Throws a LibraryAlreadyLoadedException if a library has already been loaded. Throws a LibraryLoadException if the library cannot be loaded.

### setSearchPath

static bool setSearchPath(
const std::string & path
);

Adds the given path to the list of paths shared libraries are searched in.

Returns true if the path was set, otherwise false.

Currently only supported on Windows, where it calls SetDllDirectory(). On all other platforms, does not do anything and returns false.

### suffix

static std::string suffix();

Returns the platform-specific filename suffix for shared libraries (including the period). In debug mode, the suffix also includes a "d" to specify the debug version of a library (e.g., "d.so", "d.dll") unless the library has been compiled with -DPOCO_NO_SHARED_LIBRARY_DEBUG_SUFFIX.

### unload

void unload();

Unloads a shared library.