# Shared Library Reference

Includes alias methods and macro. You can include this header or boost/dll/shared_library.hpp to reduce dependencies in case you do not use the refcountable functions.

Define this macro to explicitly specify translation unit in which alias must be instantiated. See section 'Limitations' for more info. You may find usage examples in source codes of almost each tutorial. Must be used in code, when BOOST_DLL_FORCE_NO_WEAK_EXPORTS is defined

Define this macro to disable exporting weak symbols and start using the BOOST_DLL_FORCE_ALIAS_INSTANTIATION. This may be useful for working around linker problems or to test your program for compatibility with linkers that do not support export of weak symbols.

Macro that allows linker to select any occurrence of this symbol instead of failing with 'multiple definitions' error at linktime.

This macro does not work on Android, IBM XL C/C++ and MinGW+Windows because of linker problems with exporting weak symbols (See https://code.google.com/p/android/issues/detail?id=70206, https://sourceware.org/bugzilla/show_bug.cgi?id=17480)

Name of the section. Must be a valid C identifier without quotes not longer than 8 bytes.

Can be "read" or "write" (without quotes!).

Macro that puts symbol to a specific section. On MacOS all the sections are put into "__DATA" segment.

Function or variable for which an alias must be made.

Name of the alias. Must be a valid C identifier.

Makes an alias name for exported function or variable.

This macro is useful in cases of long mangled C++ names. For example some `void boost::foo(std::string)` function name will change to something like `N5boostN3foosE` after mangling. Importing function by `N5boostN3foosE` name does not looks user friendly, especially assuming the fact that different compilers have different mangling schemes. AliasName is the name that won't be mangled and can be used as a portable import name.

Can be used in any namespace, including global. FunctionOrVar must be fully qualified, so that address of it could be taken. Multiple different aliases for a single variable/function are allowed.

Make sure that AliasNames are unique per library/executable. Functions or variables in global namespace must not have names same as AliasNames.

Same AliasName in different translation units must point to the same FunctionOrVar.

Puts all the aliases into the "boostdll" read only section of the binary. Equal to BOOST_DLL_ALIAS_SECTIONED(FunctionOrVar, AliasName, boostdll).

Example:

    namespace foo {
      void bar(std::string&);

      BOOST_DLL_ALIAS(foo::bar, foo_bar)
    }

    BOOST_DLL_ALIAS(foo::bar, foo_bar_another_alias_name)

See: BOOST_DLL_ALIAS_SECTIONED for making alias in a specific section.

Function or variable for which an alias must be made.

Name of the alias. Must be a valid C identifier.

Name of the section. Must be a valid C identifier without quotes not longer than 8 bytes.

Same as BOOST_DLL_ALIAS but puts alias name into the user specified section.

Example:

    namespace foo {
      void bar(std::string&);

      BOOST_DLL_ALIAS_SECTIONED(foo::bar, foo_bar, sect_1) // section "sect_1" now exports "foo_bar"
    }

Function or variable for which an unmangled alias must be made.

Exports variable or function with unmangled alias name.

This macro is useful in cases of long mangled C++ names. For example some `void boost::foo(std::string)` function name will change to something like `N5boostN3foosE` after mangling. Importing function by `N5boostN3foosE` name does not looks user friendly, especially assuming the fact that different compilers have different mangling schemes.*

Must be used in scope where FunctionOrVar declared. FunctionOrVar must be a valid C name, which means that it must not contain `::`.

Functions or variables in global namespace must not have names same as FunctionOrVar.

Puts all the aliases into the "boostdll" read only section of the binary. Almost same as BOOST_DLL_ALIAS(FunctionOrVar, FunctionOrVar).

Example:

    namespace foo {
      void bar(std::string&);
      BOOST_DLL_AUTO_ALIAS(bar)
    }

See: BOOST_DLL_ALIAS for making an alias with different names.

Imports filesystem, error_code, errc, system_error, make_error_code from Boost or C++17 into `boost::dll::fs` namespace.

Alias to `std::filesystem::path` if BOOST_DLL_USE_STD_FS is defined by user. Alias to `boost::filesystem::path` otherwise.

std::conditional_t< BOOST_DLL_USE_STD_FS, std::filesystem::path, boost::filesystem::path >

Alias to `std::error_code` if BOOST_DLL_USE_STD_FS is defined by user. boost::system::error_code otherwise.

std::conditional_t< BOOST_DLL_USE_STD_FS, std::error_code, boost::system::error_code >

Alias to `std::system_error` if BOOST_DLL_USE_STD_FS is defined by user. Alias to `boost::system::system_error` otherwise.

std::conditional_t< BOOST_DLL_USE_STD_FS, std::system_error, boost::system::system_error >
Define this macro to make Boost.DLL use C++17's std::filesystem::path and std::system_error.

Define this macro to make Boost.DLL use boost::shared_ptr instead of std::shared_ptr. This macro will be removed after a few releases, consider migrating to std::shared_ptr.

Contains only the boost::dll::library_info class that is capable of extracting different information from binaries.

noncopyable
Class that is capable of extracting different information from a library or binary file. Currently understands ELF, MACH-O and PE formats on all the platforms.
const boost::dll::fs::path &

Path to the binary file from which the info must be extracted.

bool
true

Throw an exception if this file format is not supported by OS.

Opens file with specified path and prepares for information extraction.

`std::exception` based exceptions.

std::vector< std::string >

List of sections that exist in binary file.

`std::exception` based exceptions.

std::vector< std::string >

List of all the exportable symbols from all the sections that exist in binary file.

`std::exception` based exceptions.

std::vector< std::string > `const char *

Name of the section from which symbol names must be returned.

`

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

List of symbols from the specified section.

`std::exception` based exceptions.

std::vector< std::string > `const std::string &`

Provides methods for getting acceptable by boost::dll::shared_library location of symbol, source line or program.

boost::dll::fs::path `T

Pointer to symbol which location is to be determined.

` `std::error_code &

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

`

On success returns full path and name to the binary object that holds symbol pointed by ptr_to_symbol.

Examples:

    int main() {
       dll::symbol_location_ptr(std::set_terminate(0));       // returns "/some/path/libmy_terminate_handler.so"
       dll::symbol_location_ptr(::signal(SIGSEGV, SIG_DFL));  // returns "/some/path/libmy_symbol_handler.so"
    }

Path to the binary object that holds symbol or empty path in case error.

`std::bad_alloc` in case of insufficient memory. Overload that does not accept boost::dll::fs::error_code also throws boost::dll::fs::system_error.

boost::dll::fs::path `T`
boost::dll::fs::path

Type of the symbol, must not be explicitly specified.

const T &

Symbol which location is to be determined.

std::error_code &

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

On success returns full path and name of the binary object that holds symbol.

Examples:

    int var;
    void foo() {}

    int main() {
       dll::symbol_location(var);                     // returns program location
       dll::symbol_location(foo);                     // returns program location
       dll::symbol_location(std::cerr);               // returns location of libstdc++: "/usr/lib/x86_64-linux-gnu/libstdc++.so.6"
       dll::symbol_location(std::placeholders::_1);   // returns location of libstdc++: "/usr/lib/x86_64-linux-gnu/libstdc++.so.6"
       dll::symbol_location(std::puts);               // returns location of libc: "/lib/x86_64-linux-gnu/libc.so.6"
    }

Path to the binary object that holds symbol or empty path in case error.

`std::bad_alloc` in case of insufficient memory. Overload that does not accept boost::dll::fs::error_code also throws boost::dll::fs::system_error.

boost::dll::fs::path `const T &`
boost::dll::fs::path `std::error_code &

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

`

On success returns full path and name of the binary object that holds the current line of code (the line in which the `this_line_location()` method was called).

`std::bad_alloc` in case of insufficient memory. Overload that does not accept boost::dll::fs::error_code also throws boost::dll::fs::system_error.

boost::dll::fs::path
boost::dll::fs::path `std::error_code &

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

`

On success returns full path and name of the currently running program (the one which contains the `main()` function).

Return value can be used as a parameter for shared_library. See Tutorial "Linking plugin into the executable" for usage example. Flag '-rdynamic' must be used when linking the plugin into the executable on Linux OS.

`std::bad_alloc` in case of insufficient memory. Overload that does not accept boost::dll::fs::error_code also throws boost::dll::fs::system_error.

boost::dll::fs::path

Contains the boost::dll::shared_library class, core class for all the DLL/DSO operations.

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).

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.

platform_specific

Creates in anstance that does not reference any DLL/DSO.

this->is_loaded() returns false.

`Nothing.`

const `shared_library` &

A library to copy.

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.

lib == *this

``

const `shared_library` &

A shared library to copy.

std::error_code &

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

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

lib == *this

`std::bad_alloc` in case of insufficient memory.

shared_library
&&

A shared library to move from.

Move constructor. Does not invalidate existing symbols and functions loaded from lib.

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

`Nothing.`

const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

load_mode::type
load_mode::default_mode

A mode that will be used on library load.

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.

``

const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

std::error_code &

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

load_mode::type
load_mode::default_mode

A mode that will be used on library load.

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.

`std::bad_alloc` in case of insufficient memory.

const boost::dll::fs::path &
load_mode::type
std::error_code &
native_handle_t

The native handle.

Takes ownership of a loaded library.

`shared_library` & `const `shared_library` &

A shared library to assign from.

`

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.

lib == *this

``

`shared_library` & ``shared_library` &&

A library to move from.

`

Move assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.

lib.is_loaded() returns false.

`Nothing.`

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.

`Nothing.`

`shared_library` & `const `shared_library` &

A library to copy.

` `std::error_code &

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

`

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

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

`std::bad_alloc` in case of insufficient memory.

`shared_library` & `const `shared_library` &

A library instance to assign from.

`

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.

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

``

void `const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

` `load_mode::typeload_mode::default_mode

A mode that will be used on library load.

`

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.

``

void `const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

` `std::error_code &

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

` `load_mode::typeload_mode::default_mode

A mode that will be used on library load.

`

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.

`std::bad_alloc` in case of insufficient memory.

void `const boost::dll::fs::path &` `load_mode::type` `std::error_code &`
void

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.

this->is_loaded() returns false.

`Nothing.`

bool

Check if an library is loaded.

true if a library has been loaded.

`Nothing.`

bool

Check if an library is loaded.

true if a library has been loaded.

`Nothing.`

bool `const char *

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

`

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.

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

`Nothing.`

bool `const std::string &`
std::enable_if< std::is_member_pointer< T >::value||std::is_reference< T >::value, T >::type

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

const std::string &

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

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.

Reference to the symbol.

``

std::enable_if<!(std::is_member_pointer< T >::value||std::is_reference< T >::value), T & >::type `const std::string &`

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

std::enable_if< std::is_member_pointer< T >::value||std::is_reference< T >::value, T >::type `const char *`
std::enable_if<!(std::is_member_pointer< T >::value||std::is_reference< T >::value), T & >::type `const char *`
T &

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

const char *

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

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.

``

T & `const std::string &`
native_handle_t

Returns the native handler of the loaded library.

Platform-specific handle.

boost::dll::fs::path

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.

Full path to the shared library.

``

boost::dll::fs::path `std::error_code &

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

`

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

Full path to the shared library.

`std::bad_alloc.`

void ``shared_library` &

Library to swap with.

`

Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.

`Nothing.`

boost::dll::fs::path

Returns suffix of shared module: in a call to load() or the constructor/load.

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

boost::dll::fs::path `const boost::dll::fs::path &

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

`

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

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

bool `const `shared_library` &` `const `shared_library` &` Very fast equality check that compares the actual DLL/DSO objects. Throws nothing.
bool `const `shared_library` &` `const `shared_library` &` Very fast inequality check that compares the actual DLL/DSO objects. Throws nothing.
bool `const `shared_library` &` `const `shared_library` &` Compare the actual DLL/DSO objects without any guarantee to be stable between runs. Throws nothing.
void ``shared_library` &` ``shared_library` &` Swaps two shared libraries. Does not invalidate symbols and functions loaded from libraries. Throws nothing.

Contains only the boost::dll::load_mode::type enum and operators related to it.

Default open mode. See the Default: comments below to find out the flags that are enabled by default.

Platforms: Windows

Default: disabled

If this value is used, and the executable module is a DLL, the system does not call DllMain for process and thread initialization and termination. Also, the system does not load additional executable modules that are referenced by the specified module.

Note Do not use this value; it is provided only for backward compatibility. If you are planning to access only data or resources in the DLL, use LOAD_LIBRARY_AS_DATAFILE_EXCLUSIVE or LOAD_LIBRARY_AS_IMAGE_RESOURCE or both.

Platforms: Windows

Default: disabled

If this value is used, the system does not check AppLocker rules or apply Software Restriction Policies for the DLL.

Platforms: Windows

Default: disabled

If this value is used and lpFileName specifies an absolute path, the system uses the alternate file search strategy.

This value cannot be combined with any LOAD_LIBRARY_SEARCH flag.

Platforms: POSIX

Default: enabled

Relocations shall be performed at an implementation-defined time, ranging from the time of the dlopen() call until the first reference to a given symbol occurs.

Specifying RTLD_LAZY should improve performance on implementations supporting dynamic symbol binding as a process may not reference all of the functions in any given object. And, for systems supporting dynamic symbol resolution for normal process execution, this behavior mimics the normal handling of process execution.

Platforms: POSIX

Default: disabled

All necessary relocations shall be performed when the object is first loaded. This may waste some processing if relocations are performed for functions that are never referenced. This behavior may be useful for plugins that need to know as soon as an object is loaded that all symbols referenced during execution are available.

Platforms: POSIX

Default: disabled

The object's symbols shall be made available for the relocation processing of any other object. In addition, symbol lookup using dlopen(0, mode) and an associated dlsym() allows objects loaded with this mode to be searched.

Platforms: POSIX

Default: enabled

The object's symbols shall not be made available for the relocation processing of any other object.

This is a default Windows behavior that can not be changed.

Platforms: POSIX (requires glibc >= 2.3.4)

Default: disabled

The object will use its own symbols in preference to global symbols with the same name contained in libraries that have already been loaded. This flag is not specified in POSIX.1-2001.

Platforms: Windows, POSIX

Default: disabled

Append a platform specific extension and prefix to shared library filename before trying to load it. If load attempt fails, try to load with exactly specified name.

Example:

    // Opens `./my_plugins/plugin1.dll` on Windows, `./my_plugins/libplugin1.so` on Linux, `./my_plugins/libplugin1.dylib` on MacOS.
    // If that fails, loads `./my_plugins/plugin1`
    boost::dll::shared_library lib("./my_plugins/plugin1", load_mode::append_decorations);

Platforms: Windows, POSIX

Default: disabled

Allow loading from system folders if path to library contains no parent path.

Library load modes.

Each of system family provides own modes. Flags not supported by a particular platform will be silently ignored.

For a detailed description of platform specific options see: Windows specific options, POSIX specific options.

BOOST_CONSTEXPR type `type` `type` Free operators for load_mode::type flag manipulation.
BOOST_CXX14_CONSTEXPR type & `type &` `type`
BOOST_CONSTEXPR type `type` `type`
BOOST_CXX14_CONSTEXPR type & `type &` `type`
BOOST_CONSTEXPR type `type` `type`
BOOST_CXX14_CONSTEXPR type & `type &` `type`
BOOST_CONSTEXPR type `type`

Contains the boost::dll::experimental::smart_library class for loading mangled symbols.

Experimental feature that relies on an incomplete implementation of platform specific C++ mangling. In case of an issue provide a PR with a fix and tests to https://github.com/boostorg/dll . boost/dll/smart_library.hpp is not included in boost/dll.hpp

This class is an extension of shared_library, which allows to load C++ symbols.

This class allows type safe loading of overloaded functions, member-functions, constructors and variables. It also allows to overwrite classes so they can be loaded, while being declared with different names.

Experimental feature that relies on an incomplete implementation of platform specific C++ mangling. In case of an issue provide a PR with a fix and tests to https://github.com/boostorg/dll

Currently known limitations:

Member functions must be defined outside of the class to be exported. That is:

    //not exported:
    struct BOOST_SYMBOL_EXPORT my_class { void func() {} };
    //exported
    struct BOOST_SYMBOL_EXPORT my_class { void func(); };
    void my_class::func() {}

With the current analysis, the first version does get exported in MSVC. MinGW also does export it, BOOST_SYMBOL_EXPORT is written before it. To allow this on windows one can use BOOST_DLL_MEMBER_EXPORT for this, so that MinGW and MSVC can provide those functions. This does however not work with gcc on linux.

Direct initialization of members. On linux the following member variable i will not be initialized when using the allocating constructor:

    struct BOOST_SYMBOL_EXPORT my_class { int i; my_class() : i(42) {} };

This does however not happen when the value is set inside the constructor function.

unspecified
const `shared_library` &

Get the underlying shared_library

const mangled_storage &

Access to the mangled storage, which is created on construction.

`Nothing.`

mangled_storage & Overload, for current development.

Creates in anstance that does not reference any DLL/DSO.

this->is_loaded() returns false.

`Nothing.`

const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

load_mode::type
load_mode::default_mode

A mode that will be used on library load.

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.

``

const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

boost::dll::fs::error_code &

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

load_mode::type
load_mode::default_mode

A mode that will be used on library load.

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.

`std::bad_alloc` in case of insufficient memory.

const boost::dll::fs::path &
load_mode::type
boost::dll::fs::error_code &
const `smart_library` &

A smart_library to move from.

copy a smart_library object.

`Nothing.`

smart_library
&&

A smart_library to move from.

Move a smart_library object.

`Nothing.`

const `shared_library` &

A shared_library to move from.

Construct from a shared_library object.

`Nothing.`

shared_library
&&

A shared_library to move from.

Construct from a shared_library object.

`Nothing.`

Destroys the smart_library. `unload()` is called if the DLL/DSO was loaded. If library was loaded multiple times by different instances of shared_library, the actual DLL/DSO won't be unloaded until there is at least one instance of shared_library.

`Nothing.`

void `const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

` `load_mode::typeload_mode::default_mode

A mode that will be used on library load.

`

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.

``

void `const boost::dll::fs::path &

Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.

` `boost::dll::fs::error_code &

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

` `load_mode::typeload_mode::default_mode

A mode that will be used on library load.

`

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.

`std::bad_alloc` in case of insufficient memory.

void `const boost::dll::fs::path &` `load_mode::type` `boost::dll::fs::error_code &`
T &

Type of the variable

const std::string &

Name of the variable

Load a variable from the referenced library.

Unlinke shared_library::get this function will also load scoped variables, which also includes static class members.

When mangled, MSVC will also check the type.

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.

A reference to the variable of type T.

``

Func &

Type of the function, required for determining the overload

const std::string &

Name of the function.

Load a function from the referenced library.

Example:

    smart_library lib("test_lib.so");
    typedef int      (&add_ints)(int, int);
    typedef double (&add_doubles)(double, double);
    add_ints     f1 = lib.get_function<int(int, int)>         ("func_name");
    add_doubles  f2 = lib.get_function<double(double, double)>("func_name");

When mangled, MSVC will also check the return type.

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.

A reference to the function of type F.

``

unspecified

The class the function is a member of. If Class is const, the function will be assumed as taking a const this-pointer. The same applies for volatile.

Signature of the function, required for determining the overload

const std::string &

Name of the function.

Load a member-function from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):

    smart_library lib("test_lib.so");

    typedef int      MyClass(*func)(int);
    typedef int   MyClass(*func_const)(int) const;

    add_ints     f1 = lib.get_mem_fn<MyClass, int(int)>              ("MyClass::function");
    add_doubles  f2 = lib.get_mem_fn<const MyClass, double(double)>("MyClass::function");

When mangled, MSVC will also check the return type.

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.

A pointer to the member-function with the signature provided

``

constructor< Signature >

Signature of the function, required for determining the overload. The return type is the class which this is the constructor of.

Load a constructor from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):

    smart_library lib("test_lib.so");

    constructor<MyClass(int)    f1 = lib.get_mem_fn<MyClass(int)>();

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.

A constructor object.

``

destructor< Class >

The class whose destructor shall be loaded

Load a destructor from the referenced library.

Example (import class is MyClass, which is available inside the library and the host):

    smart_library lib("test_lib.so");

    destructor<MyClass>     f1 = lib.get_mem_fn<MyClass>();

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.

A destructor object.

``

const std::type_info &

The class whose typeinfo shall be loaded

Load the typeinfo of the given type.

Example (import class is MyClass, which is available inside the library and the host):

    smart_library lib("test_lib.so");

    std::type_info &ti = lib.get_Type_info<MyClass>();

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.

A reference to a type_info object.

``

void `const std::string &

Name of the class the alias is for.

`

This function can be used to add a type alias.

This is to be used, when a class shall be imported, which is not declared on the host side.

Example:

    smart_library lib("test_lib.so");

    lib.add_type_alias<MyAlias>("MyClass"); //when using MyAlias, the library will look for MyClass

    //get the destructor of MyClass
    destructor<MyAlias> dtor = lib.get_destructor<MyAlias>();

If the alias-type is not large enough for the imported class, it will result in undefined behaviour.

The alias will only be applied for the type signature, it will not replace the token in the scoped name.

void

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.

this->is_loaded() returns false.

`Nothing.`

bool

Check if an library is loaded.

true if a library has been loaded.

`Nothing.`

bool bool() const

bool() const

bool `const char *

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

`

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.

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

`Nothing.`

bool `const std::string &`
`smart_library` & `const `smart_library` &

A library instance to assign from.

`

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.

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

``

void ``smart_library` &

Library to swap with.

`

Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.

`Nothing.`

bool `const `smart_library` &` `const `smart_library` &` Very fast equality check that compares the actual DLL/DSO objects. Throws nothing.
bool `const `smart_library` &` `const `smart_library` &` Very fast inequality check that compares the actual DLL/DSO objects. Throws nothing.
bool `const `smart_library` &` `const `smart_library` &` Compare the actual DLL/DSO objects without any guarantee to be stable between runs. Throws nothing.
void ``smart_library` &` ``smart_library` &` Swaps two shared libraries. Does not invalidate symbols and functions loaded from libraries. Throws nothing.
void `const `smart_library` &

A reference to the smart_library

` `const std::string &

The name of the entity to import

`

Helper functions for overloads.

Gets either a variable, function or member-function, depending on the signature.

    smart_library sm("lib.so");
    get<int>(sm, "space::value"); //import a variable
    get<void(int)>(sm, "space::func"); //import a function
    get<some_class, void(int)>(sm, "space::class_::mem_fn"); //import a member function

std::enable_if< std::is_object< T >::value, T & >::type `const `smart_library` &` `const std::string &`
std::enable_if< std::is_function< T >::value, T & >::type `const `smart_library` &` `const std::string &`
unspecified `const `smart_library` &

A reference to the smart_library

` `const std::string &

The name of the entity to import

`

Helper functions for overloads.

Gets either a variable, function or member-function, depending on the signature.

    smart_library sm("lib.so");
    get<int>(sm, "space::value"); //import a variable
    get<void(int)>(sm, "space::func"); //import a function
    get<some_class, void(int)>(sm, "space::class_::mem_fn"); //import a member function