| Home | Libraries | People | FAQ | More

## 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;

      // public member functions
      shared_library();
      shared_library(const shared_library &);
      shared_library(const shared_library &, std::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 &, std::error_code &,
                     load_mode::type = load_mode::default_mode);
      shared_library(const boost::dll::fs::path &, load_mode::type,
                     std::error_code &);
      explicit shared_library(native_handle_t) noexcept;
      shared_library & operator=(const shared_library &);
      shared_library & operator=(shared_library &&) noexcept;
      ~shared_library() = default;
      shared_library & assign(const shared_library &, std::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 &, std::error_code &,
                load_mode::type = load_mode::default_mode);
      void load(const boost::dll::fs::path &, load_mode::type, std::error_code &);
      void unload() noexcept;
      bool is_loaded() const noexcept;
      explicit operator bool() const noexcept;
      bool has(const char *) const noexcept;
      bool has(const std::string &) const noexcept;
      template<typename T>
        std::enable_if< std::is_member_pointer< T >::value||std::is_reference< T >::value, T >::type
        get(const std::string &) const;
      template<typename T>
        std::enable_if<!(std::is_member_pointer< T >::value||std::is_reference< T >::value), T & >::type
        get(const std::string &) const;
      template<typename T>
        std::enable_if< std::is_member_pointer< T >::value||std::is_reference< T >::value, T >::type
        get(const char *) const;
      template<typename T>
        std::enable_if<!(std::is_member_pointer< T >::value||std::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(std::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 member functions

1.     shared_library();

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

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

2.     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: |

3.     shared_library(const shared_library & lib, std::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: |
   `lib` | A shared library to copy.
   `ec` | Variable that will be set to the result of the operation.
   Postconditions: | lib == *this
   Throws: | std::bad_alloc in case of insufficient memory.

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

5.     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: |

6.     shared_library(const boost::dll::fs::path & lib_path, std::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: |
   `lib_path` | Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.
   `ec` | Variable that will be set to the result of the operation.
   `mode` | A mode that will be used on library load.
   Throws: | std::bad_alloc in case of insufficient memory.

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

8.     explicit shared_library(native_handle_t handle) noexcept;

   Takes ownership of a loaded library.

   Parameters: |
   `handle` | The native handle.

9.     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: |

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

11.     ~shared_library() = default;

    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.

12.     shared_library & assign(const shared_library & lib, std::error_code & ec);

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

    Parameters: |
    `lib` | A library to copy.
    `ec` | Variable that will be set to the result of the operation.
    Postconditions: | lib.location() == this->location(), lib == *this
    Throws: | std::bad_alloc in case of insufficient memory.

13.     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: |

14.     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: |

15.     void load(const boost::dll::fs::path & lib_path, std::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: |
    `lib_path` | Library file name. Can handle std::string, const char*, std::wstring, const wchar_t* or boost::dll::fs::path.
    `ec` | Variable that will be set to the result of the operation.
    `mode` | A mode that will be used on library load.
    Throws: | std::bad_alloc in case of insufficient memory.

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

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

18.     bool is_loaded() const noexcept;

    Check if an library is loaded.

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

19.     explicit operator bool() const noexcept;

    Check if an library is loaded.

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

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

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

22.     template<typename T>
          std::enable_if< std::is_member_pointer< T >::value||std::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.

    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: |

23.     template<typename T>
          std::enable_if<!(std::is_member_pointer< T >::value||std::is_reference< T >::value), T & >::type
          get(const std::string & symbol_name) const;

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

24.     template<typename T>
          std::enable_if< std::is_member_pointer< T >::value||std::is_reference< T >::value, T >::type
          get(const char * symbol_name) const;

25.     template<typename T>
          std::enable_if<!(std::is_member_pointer< T >::value||std::is_reference< T >::value), T & >::type
          get(const char * symbol_name) const;

26.     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: |

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

28.     native_handle_t native() const noexcept;

    Returns the native handler of the loaded library.

    Returns: | Platform-specific handle.

29.     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: |

30.     boost::dll::fs::path location(std::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.

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

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

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