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

      // 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();

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

1.     shared_library() noexcept;

   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.

   Parameters: |
   `lib` | A library to copy.
   Postconditions: | lib == *this
   Throws: |

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

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.

   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,
                      boost::dll::fs::error_code & ec,
                      load_mode::type mode = load_mode::default_mode);

   Loads a library by specified path with a specified mode.

   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.

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

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

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

   Parameters: |
   `lib` | A shared library to assign from.
   Postconditions: | lib == *this
   Throws: |

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

10.     ~shared_library();

    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

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

2.     shared_library & assign(const shared_library & lib);

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

   Parameters: |
   `lib` | A library instance to assign from.
   Postconditions: | lib.location() == this->location()
   Throws: |

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

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

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

   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.

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

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

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

7.     bool is_loaded() const noexcept;

   Check if an library is loaded.

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

8.     bool operator!() const noexcept;

   Check if an library is not loaded.

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

9.     explicit operator bool() const noexcept;

   Check if an library is loaded.

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

10.     bool has(const char * symbol_name) const noexcept;

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

    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.

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

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

12.     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");

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

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

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

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

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

15.     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;

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

16.     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");

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

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

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

18.     native_handle_t native() const noexcept;

    Returns the native handler of the loaded library.

    Returns: | Platform-specific handle.

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

    Returns: | Full path to the shared library.
    Throws: |

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

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