![]() |
Home | Libraries | People | FAQ | More |
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).
// In header: <boost/dll/shared_library.hpp> class shared_library { public: // types typedef ; // construct/copy/destruct () ; (shared_library &); (shared_library &, ); (shared_library &&) ; (, = ); (, , = ); (, , ); shared_library & (shared_library &); shared_library & (shared_library &&) ; ~(); // public member functions shared_library & (shared_library &, ); shared_library & (shared_library &); (, = ); (, , = ); (, , ); () ; () ; () ; () ; () ; () ; template<typename T> () ; template<typename T> () ; template<typename T> () ; template<typename T> () ; template<typename T> () ; template<typename T> () ; () ; () ; () ; (shared_library &) ; // public static functions (); (); };
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() ;
Creates in anstance that does not reference any DLL/DSO.
Postconditions: |
this->is_loaded() returns false. |
Throws: |
Nothing. |
(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: |
|
||
Postconditions: |
lib == *this |
||
Throws: |
(shared_library & lib, ec);
Copy constructor that increments the reference count of an underlying shared library. Same as calling constructor with lib.location(), ec
parameters.
Parameters: |
|
||||
Postconditions: |
lib == *this |
||||
Throws: |
std::bad_alloc in case of insufficient memory. |
(shared_library && lib) ;
Move constructor. Does not invalidate existing symbols and functions loaded from lib.
Parameters: |
|
||
Postconditions: |
lib.is_loaded() returns false, this->is_loaded() return true. |
||
Throws: |
Nothing. |
( lib_path, 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: |
|
||||
Throws: |
( lib_path, ec, 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: |
|
||||||
Throws: |
std::bad_alloc in case of insufficient memory. |
( lib_path, mode, ec);
shared_library & (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: |
|
||
Postconditions: |
lib == *this |
||
Throws: |
shared_library & (shared_library && lib) ;
Move assignment operator. If this->is_loaded() then calls this->unload(). Does not invalidate existing symbols and functions loaded from lib.
Parameters: |
|
||
Postconditions: |
lib.is_loaded() returns false. |
||
Throws: |
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.
Throws: |
Nothing. |
shared_library
public member functionsshared_library & (shared_library & lib, ec);
Makes *this share the same shared object as lib. If *this is loaded, then unloads it.
Parameters: |
|
||||
Postconditions: |
lib.location() == this->location(), lib == *this |
||||
Throws: |
std::bad_alloc in case of insufficient memory. |
shared_library & (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: |
|
||
Postconditions: |
lib.location() == this->location() |
||
Throws: |
( lib_path, 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: |
|
||||
Throws: |
( lib_path, ec, 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: |
|
||||||
Throws: |
std::bad_alloc in case of insufficient memory. |
( lib_path, mode, ec);
() ;
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. |
() ;
Check if an library is loaded.
Returns: |
true if a library has been loaded. |
Throws: |
Nothing. |
() ;
Check if an library is not loaded.
Returns: |
true if a library has not been loaded. |
Throws: |
Nothing. |
() ;
Check if an library is loaded.
Returns: |
true if a library has been loaded. |
Throws: |
Nothing. |
( symbol_name) ;
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: |
|
||
Returns: |
|
||
Throws: |
Nothing. |
( symbol_name) ;
template<typename T> ( symbol_name) ;
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:
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: |
|
||
Template Parameters: |
|
||
Returns: |
Reference to the symbol. |
||
Throws: |
template<typename T> ( symbol_name) ;
template<typename T> ( symbol_name) ;
template<typename T> ( symbol_name) ;
template<typename T> ( alias_name) ;
Returns a symbol (function or variable) from a shared library by alias name of the symbol.
Example:
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: |
|
||
Template Parameters: |
|
||
Throws: |
template<typename T> ( alias_name) ;
() ;
Returns the native handler of the loaded library.
Returns: |
Platform-specific handle. |
() ;
Returns full path and name of this shared object.
Example:
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: |
( ec) ;
Returns full path and name of shared module.
Example:
Parameters: |
|
||
Returns: |
Full path to the shared library. |
||
Throws: |
std::bad_alloc. |
(shared_library & rhs) ;
Swaps two libraries. Does not invalidate existing symbols and functions loaded from libraries.
Parameters: |
|
||
Throws: |
Nothing. |
shared_library
public static functions();
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) |
( 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: |
|
||
Returns: |
The decorated unportable path that may not exists in the filesystem or could be wrong due to platform specifics. |