Class shared_library

boost::dll::shared_library — This class can be used to load a Dynamic link libraries (DLL's) or Shared Libraries, also know as dynamic shared objects (DSO's) and get their exported symbols (functions and variables).

Synopsis

// In header: <boost/dll/shared_library.hpp>


class shared_library {
public:
  // types
  typedef platform_specific native_handle_t;

  // construct/copy/destruct
  shared_library() noexcept;
  shared_library(const shared_library &);
  shared_library(const shared_library &, boost::dll::fs::error_code &);
  shared_library(shared_library &&) noexcept;
  explicit shared_library(const boost::dll::fs::path &, 
                          load_mode::type = load_mode::default_mode);
  shared_library(const boost::dll::fs::path &, boost::dll::fs::error_code &, 
                 load_mode::type = load_mode::default_mode);
  shared_library(const boost::dll::fs::path &, load_mode::type, 
                 boost::dll::fs::error_code &);
  shared_library & operator=(const shared_library &);
  shared_library & operator=(shared_library &&) noexcept;
  ~shared_library() noexcept;

  // public member functions
  shared_library & 
  assign(const shared_library &, boost::dll::fs::error_code &);
  shared_library & assign(const shared_library &);
  void load(const boost::dll::fs::path &, 
            load_mode::type = load_mode::default_mode);
  void load(const boost::dll::fs::path &, boost::dll::fs::error_code &, 
            load_mode::type = load_mode::default_mode);
  void load(const boost::dll::fs::path &, load_mode::type, 
            boost::dll::fs::error_code &);
  void unload() noexcept;
  bool is_loaded() const noexcept;
  bool operator!() const noexcept;
  explicit operator bool() const noexcept;
  bool has(const char *) const noexcept;
  bool has(const std::string &) const noexcept;
  template<typename T> 
    boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type 
    get(const std::string &) const;
  template<typename T> 
    boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type 
    get(const std::string &) const;
  template<typename T> 
    boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type 
    get(const char *) const;
  template<typename T> 
    boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type 
    get(const char *) const;
  template<typename T> T & get_alias(const char *) const;
  template<typename T> T & get_alias(const std::string &) const;
  native_handle_t native() const noexcept;
  boost::dll::fs::path location() const;
  boost::dll::fs::path location(boost::dll::fs::error_code &) const;
  void swap(shared_library &) noexcept;

  // public static functions
  static boost::dll::fs::path suffix();
  static boost::dll::fs::path decorate(const boost::dll::fs::path &);
};

Description

shared_library instances share reference count to an actual loaded DLL/DSO, so it is safe and memory efficient to have multiple instances of shared_library referencing the same DLL/DSO even if those instances were loaded using different paths (relative + absolute) referencing the same object.

On Linux/POSIX link with library "dl". "-fvisibility=hidden" flag is also recommended for use on Linux/POSIX.

`shared_library` public construct/copy/destruct

```
shared_library() noexcept;
```
Creates in anstance that does not reference any DLL/DSO.

Postconditions:

this->is_loaded() returns false.

Throws:
Nothing.
```
shared_library(const shared_library & lib);
```
Copy constructor that increments the reference count of an underlying shared library. Same as calling constructor with lib.location() parameter.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

lib

A library to copy.

Postconditions:

lib == *this

Throws:

shared_library(const shared_library & lib, boost::dll::fs::error_code & ec);

Copy constructor that increments the reference count of an underlying shared library. Same as calling constructor with lib.location(), ec parameters.

Parameters:

`ec`	Variable that will be set to the result of the operation.
`lib`	A shared library to copy.

Postconditions:

lib == *this

Throws:

std::bad_alloc in case of insufficient memory.

```
shared_library(shared_library && lib) noexcept;
```
Move constructor. Does not invalidate existing symbols and functions loaded from lib.

Parameters:

lib

A shared library to move from.

Postconditions:

lib.is_loaded() returns false, this->is_loaded() return true.

Throws:
Nothing.

explicit shared_library(const boost::dll::fs::path & lib_path, 
                        load_mode::type mode = load_mode::default_mode);

Loads a library by specified path with a specified mode.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

Throws:

shared_library(const boost::dll::fs::path & lib_path, 
               boost::dll::fs::error_code & ec, 
               load_mode::type mode = load_mode::default_mode);

Loads a library by specified path with a specified mode.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

`ec`	Variable that will be set to the result of the operation.
`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

Throws:

std::bad_alloc in case of insufficient memory.

shared_library(const boost::dll::fs::path & lib_path, load_mode::type mode, 
               boost::dll::fs::error_code & ec);

```
shared_library & operator=(const shared_library & lib);
```
Assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

lib

A shared library to assign from.

Postconditions:

lib == *this

Throws:
```
shared_library & operator=(shared_library && lib) noexcept;
```
Move assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.

Parameters:

lib

A library to move from.

Postconditions:

lib.is_loaded() returns false.

Throws:
Nothing.
```
~shared_library() noexcept;
```
Destroys the object by calling unload(). If library was loaded multiple times by different instances, the actual DLL/DSO won't be unloaded until there is at least one instance that references the DLL/DSO.

Throws:
Nothing.

`shared_library` public member functions

shared_library & 
assign(const shared_library & lib, boost::dll::fs::error_code & ec);

Makes *this share the same shared object as lib. If *this is loaded, then unloads it.

Parameters:

`ec`	Variable that will be set to the result of the operation.
`lib`	A library to copy.

Postconditions:

lib.location() == this->location(), lib == *this

Throws:

std::bad_alloc in case of insufficient memory.

```
shared_library & assign(const shared_library & lib);
```
Makes *this share the same shared object as lib. If *this is loaded, then unloads it.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

lib

A library instance to assign from.

Postconditions:

lib.location() == this->location()

Throws:

void load(const boost::dll::fs::path & lib_path, 
          load_mode::type mode = load_mode::default_mode);

Loads a library by specified path with a specified mode.

Note that if some library is already loaded in this instance, load will call unload() and then load the new provided library.

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc in case of insufficient memory.

Parameters:

`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

Throws:

void load(const boost::dll::fs::path & lib_path, 
          boost::dll::fs::error_code & ec, 
          load_mode::type mode = load_mode::default_mode);

Loads a library by specified path with a specified mode.

Note that if some library is already loaded in this instance, load will call unload() and then load the new provided library.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

`ec`	Variable that will be set to the result of the operation.
`lib_path`	Library file name. Can handle std::string, const char, std::wstring, const wchar_t or boost::dll::fs::path.
`mode`	A mode that will be used on library load.

Throws:

std::bad_alloc in case of insufficient memory.

void load(const boost::dll::fs::path & lib_path, load_mode::type mode, 
          boost::dll::fs::error_code & ec);

```
void unload() noexcept;
```
Unloads a shared library. If library was loaded multiple times by different instances, the actual DLL/DSO won't be unloaded until there is at least one instance that references the DLL/DSO.

Postconditions:

this->is_loaded() returns false.

Throws:
Nothing.
```
bool is_loaded() const noexcept;
```
Check if an library is loaded.

Returns:

true if a library has been loaded.

Throws:
Nothing.
```
bool operator!() const noexcept;
```
Check if an library is not loaded.

Returns:

true if a library has not been loaded.

Throws:
Nothing.
```
explicit operator bool() const noexcept;
```
Check if an library is loaded.

Returns:

true if a library has been loaded.

Throws:
Nothing.

bool has(const char * symbol_name) const noexcept;

Search for a given symbol on loaded library. Works for all symbols, including alias names.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

symbol_name

Null-terminated symbol name. Can handle std::string, char*, const char*.

Returns:

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

Throws:

Nothing.

bool has(const std::string & symbol_name) const noexcept;

template<typename T> 
  boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type 
  get(const std::string & symbol_name) const;

Returns reference to the symbol (function or variable) with the given name from the loaded library. This call will always succeed and throw nothing if call to has(const char* ) member function with the same symbol name returned true.

Example:

int& i0 = lib.get<int>("integer_name");
int& i1 = *lib.get<int*>("integer_alias_name");

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

symbol_name

Null-terminated symbol name. Can handle std::string, char*, const char*.

Template Parameters:

`T`	Type of the symbol that we are going to import. Must be explicitly specified.

Returns:

Reference to the symbol.

Throws:

template<typename T> 
  boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type 
  get(const std::string & symbol_name) const;

template<typename T> 
  boost::enable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T >::type 
  get(const char * symbol_name) const;

template<typename T> 
  boost::disable_if_c< boost::is_member_pointer< T >::value||boost::is_reference< T >::value, T & >::type 
  get(const char * symbol_name) const;

template<typename T> T & get_alias(const char * alias_name) const;

Returns a symbol (function or variable) from a shared library by alias name of the symbol.

Example:

int& i = lib.get_alias<int>("integer_alias_name");

xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link> if symbol does not exist or if the DLL/DSO was not loaded.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:

alias_name

Null-terminated alias symbol name. Can handle std::string, char*, const char*.

Template Parameters:

`T`	Type of the symbol that we are going to import. Must be explicitly specified..

Throws:

template<typename T> T & get_alias(const std::string & alias_name) const;

```
native_handle_t native() const noexcept;
```
Returns the native handler of the loaded library.

Returns:

Platform-specific handle.
```
boost::dll::fs::path location() const;
```
Returns full path and name of this shared object.

Example:
```
shared_library lib("test_lib.dll");
filesystem::path full_path = lib.location(); // C:\Windows\System32\test_lib.dll
```
xmlonly <link linkend='boost.dll.fs.system_error'>boost::dll::fs::system_error</link>, std::bad_alloc.

Returns:

Full path to the shared library.

Throws:

boost::dll::fs::path location(boost::dll::fs::error_code & ec) const;

Returns full path and name of shared module.

Example:

shared_library lib("test_lib.dll");
filesystem::path full_path = lib.location(); // C:\Windows\System32\test_lib.dll

Parameters:

`ec`	Variable that will be set to the result of the operation.

Returns:

Full path to the shared library.

Throws:

std::bad_alloc.

```
void swap(shared_library & rhs) noexcept;
```
Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.

Parameters:

rhs

Library to swap with.

Throws:
Nothing.

`shared_library` public static functions

```
static boost::dll::fs::path suffix();
```
Returns suffix of shared module: in a call to load() or the constructor/load.

Returns:

The suffix od shared module: ".dll" (Windows), ".so" (Unix/Linux/BSD), ".dylib" (MacOS/IOS)

static boost::dll::fs::path decorate(const boost::dll::fs::path & sl);

Returns the decorated path to a shared module name, i.e. with needed prefix/suffix added.

Recommendations: Use load with load_mode::append_decorations instead of constructing the decorated path via decorate() and loading by it.

For instance, for a path like "path/to/boost" it returns :

path/to/libboost.so on posix platforms
path/to/libboost.dylib on OSX
path/to/boost.dll on Windows

Method handles both relative and absolute paths.

Windows note: decorate() does not prepend "lib" to the decorated path. Use load with load_mode::append_decorations for MinGW compatibility purpose.
Posix note: if the initial module name is already prepended with lib, only the suffix() is appended to the path

Parameters:

`sl`	the module name and path to decorate - for instance : /usr/lib/boost

Returns:

The decorated unportable path that may not exists in the filesystem or could be wrong due to platform specifics.

Postconditions:	this->is_loaded() returns false.
Throws:	Nothing.

Returns:	true if a library has not been loaded.
Throws:	Nothing.

Boost C++ Libraries