glibmm 2.80.0
Public Types | Public Member Functions | Static Public Member Functions | Protected Attributes | List of all members
Glib::Module Class Reference

Dynamic loading of modules. More...

#include <glibmm/module.h>

Public Types

enum class  Flags {
  LAZY = 1 << 0 ,
  LOCAL = 1 << 1 ,
  MASK = 0x03

Public Member Functions

 Module (const std::string &file_name, Flags flags=Flags(0))
 Opens a module.
 Module (const Module &)=delete
Moduleoperator= (const Module &)=delete
 Module (Module &&other) noexcept
Moduleoperator= (Module &&other) noexcept
virtual ~Module ()
 Close a module.
 operator bool () const
 Check whether the module was found.
void make_resident ()
 Ensures that a module will never be unloaded.
bool get_symbol (const std::string &symbol_name, void *&symbol) const
 Gets a symbol pointer from the module.
std::string get_name () const
 Get the name of the module.
GModulegobj ()
const GModulegobj () const

Static Public Member Functions

static bool get_supported ()
 Checks if modules are supported on the current platform.
static std::string get_last_error ()
 Gets a string describing the last module error.
static std::string build_path (const std::string &directory, const std::string &module_name)
 A portable way to build the filename of a module.

Protected Attributes


Detailed Description

Dynamic loading of modules.

These functions provide a portable way to dynamically load object files (commonly known as 'plug-ins'). The current implementation supports all systems that provide an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its shl_load() mechanism, and Windows platforms via DLLs.

Member Enumeration Documentation

◆ Flags


Specifies that symbols are only resolved when needed.

The default action is to bind all symbols when the module is loaded.


Specifies that symbols in the module should not be added to the global name space.

The default action on most platforms is to place symbols in the module in the global name space, which may cause conflicts with existing symbols.


Mask for all flags.

Constructor & Destructor Documentation

◆ Module() [1/3]

Glib::Module::Module ( const std::string file_name,
Flags  flags = Flags(0) 

Opens a module.

If the module has already been opened, its reference count is incremented. If not, the module is searched in the following order:

  1. If file_name exists as a regular file, it is used as-is; else
  2. If file_name doesn't have the correct suffix and/or prefix for the platform, then possible suffixes and prefixes will be added to the basename till a file is found and whatever is found will be used; else
  3. If file_name doesn't have the ".la"-suffix, ".la" is appended. Either way, if a matching .la file exists (and is a libtool archive) the libtool archive is parsed to find the actual file name, and that is used.

At the end of all this, we would have a file path that we can access on disk, and it is opened as a module. If not, file_name is opened as a module verbatim in the hopes that the system implementation will somehow be able to access it.

Use operator bool() to see whether the operation succeeded. For instance,

Glib::Module module("plugins/helloworld");
void* func = nullptr;
bool found = get_symbol("some_function", func);
Dynamic loading of modules.
Definition module.h:45
bool get_symbol(const std::string &symbol_name, void *&symbol) const
Gets a symbol pointer from the module.
file_nameThe name or path to the file containing the module, or an empty string to obtain a module representing the main program itself.
flagsThe flags used for opening the module.

◆ Module() [2/3]

Glib::Module::Module ( const Module )

◆ Module() [3/3]

Glib::Module::Module ( Module &&  other)

◆ ~Module()

virtual Glib::Module::~Module ( )

Close a module.

The module will be removed from memory, unless make_resident has been called.

Member Function Documentation

◆ build_path()

static std::string Glib::Module::build_path ( const std::string directory,
const std::string module_name 

A portable way to build the filename of a module.

The platform-specific prefix and suffix are added to the filename, if needed, and the result is added to the directory, using the correct separator character.

The directory should specify the directory where the module can be found. It can be an empty string to indicate that the module is in a standard platform-specific directory, though this is not recommended since the wrong module may be found.

For example, calling build_path() on a Linux system with a directory of /lib and a module_name of "mylibrary" will return /lib/ On a Windows system, using \Windows as the directory it will return \Windows\mylibrary.dll.

directoryThe directory the module is in
module_nameThe name of the module
The system-specific filename of the module
2.76: You will get the wrong results most of the time. Use the constructor instead with module_name as the basename of the file_name argument.

◆ get_last_error()

static std::string Glib::Module::get_last_error ( )

Gets a string describing the last module error.

The error string

◆ get_name()

std::string Glib::Module::get_name ( ) const

Get the name of the module.

The name of the module

◆ get_supported()

static bool Glib::Module::get_supported ( )

Checks if modules are supported on the current platform.

true if available, false otherwise

◆ get_symbol()

bool Glib::Module::get_symbol ( const std::string symbol_name,
void *&  symbol 
) const

Gets a symbol pointer from the module.

symbol_nameThe name of the symbol to lookup
symbolA pointer to set to the symbol
True if the symbol was found, false otherwise.

◆ gobj() [1/2]

GModule * Glib::Module::gobj ( )

◆ gobj() [2/2]

const GModule * Glib::Module::gobj ( ) const

◆ make_resident()

void Glib::Module::make_resident ( )

Ensures that a module will never be unloaded.

Any calls to the Glib::Module destructor will not unload the module.

◆ operator bool()

Glib::Module::operator bool ( ) const

Check whether the module was found.

◆ operator=() [1/2]

Module & Glib::Module::operator= ( const Module )

◆ operator=() [2/2]

Module & Glib::Module::operator= ( Module &&  other)

Member Data Documentation

◆ gobject_

GModule* Glib::Module::gobject_