glibmm: Glib::Module Class Reference

glibmm 2.89.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 { Flags::LAZY = 1 << 0 , Flags::LOCAL = 1 << 1 , Flags::MASK = 0x3 }
| Flags passed to g_module_open(). More...

## Public Member Functions
| Module (const std::string & file_name, Flags flags=Flags(0))
| Opens a module.
| Module (const Module &)=delete
Module & | operator= (const Module &)=delete
| Module (Module && other) noexcept
Module & | operator= (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.
GModule * | gobj ()
const GModule * | gobj () 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
GModule * | gobject_

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

## Constructor & Destructor Documentation

## ◆ Module() [1/3]

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

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");
if(module)
{
void* func = nullptr;
bool found = get_symbol("some_function", func);
}
Glib::Module
Dynamic loading of modules.
Definition module.h:45
Glib::Module::get_symbol
bool get_symbol(const std::string &symbol_name, void *&symbol) const
Gets a symbol pointer from the module.

Parameters

  file_name | The name or path to the file containing the module, or an empty string to obtain a module representing the main program itself.
  flags | The flags used for opening the module.

## ◆ Module() [2/3]

Glib::Module::Module | ( | const Module & |  | ) |
| delete

## ◆ Module() [3/3]

Glib::Module::Module | ( | Module && | other | ) |
| noexcept

## ◆ ~Module()

virtual Glib::Module::~Module | ( |  | ) |
| virtual

Close a module.

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

## Member Function Documentation

## ◆ build_path()

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

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/libmylibrary.so. On a Windows system, using \Windows as the directory it will return \Windows\mylibrary.dll.

Parameters

  directory | The directory the module is in
  module_name | The name of the module

Returns
  The system-specific filename of the module

Deprecated
  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()

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

Gets a string describing the last module error.

Returns
  The error string

## ◆ get_name()

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

Get the name of the module.

Returns
  The name of the module

## ◆ get_supported()

bool Glib::Module::get_supported | ( |  | ) |
| static

Checks if modules are supported on the current platform.

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

Parameters

  symbol_name | The name of the symbol to lookup
  symbol | A pointer to set to the symbol

Returns
  True if the symbol was found, false otherwise.

## ◆ gobj() [1/2]

GModule * Glib::Module::gobj | ( |  | ) |
| inline

## ◆ gobj() [2/2]

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

## ◆ 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
| explicit

Check whether the module was found.

## ◆ operator=() [1/2]

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

## ◆ operator=() [2/2]

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

## Member Data Documentation

## ◆ gobject_

GModule* Glib::Module::gobject_
| protected