Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the master branch, built from commit 25d613dfbc.
PrevUpHomeNext

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.


PrevUpHomeNext