mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-28 16:36:14 +01:00
39e9ef54be
The files here are copied from the docs-gtk-org branch of gtk. This adds gi-docgen to the CI Dockerfiles and ensures the new versions (including the OS upgrades from the previous commit) are used during CI. Helps: #3037
536 lines
23 KiB
XML
536 lines
23 KiB
XML
<?xml version="1.0"?>
|
|
<!-- This file was automatically generated from C sources - DO NOT EDIT!
|
|
To affect the contents of this file, edit the original C definitions,
|
|
and/or use gtk-doc annotations. -->
|
|
<repository version="1.2"
|
|
xmlns="http://www.gtk.org/introspection/core/1.0"
|
|
xmlns:c="http://www.gtk.org/introspection/c/1.0"
|
|
xmlns:glib="http://www.gtk.org/introspection/glib/1.0">
|
|
<include name="GLib" version="2.0"/>
|
|
<package name="gmodule-2.0"/>
|
|
<c:include name="gmodule.h"/>
|
|
<namespace name="GModule"
|
|
version="2.0"
|
|
shared-library="libgmodule-2.0.so.0"
|
|
c:identifier-prefixes="G"
|
|
c:symbol-prefixes="g">
|
|
<record name="Module" c:type="GModule" disguised="1" opaque="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="5">The #GModule struct is an opaque data structure to represent a
|
|
[dynamically-loaded module][glib-Dynamic-Loading-of-Modules].
|
|
It should only be accessed via the following functions.</doc>
|
|
<source-position filename="gmodule.h" line="70"/>
|
|
<method name="close" c:identifier="g_module_close">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="207">Closes a module.</doc>
|
|
<source-position filename="gmodule.h" line="110"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="213">%TRUE on success</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="209">a #GModule to close</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="make_resident" c:identifier="g_module_make_resident">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="226">Ensures that a module will never be unloaded.
|
|
Any future g_module_close() calls on the module will be ignored.</doc>
|
|
<source-position filename="gmodule.h" line="114"/>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="228">a #GModule to make permanently resident</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="name" c:identifier="g_module_name">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="235">Returns the filename that the module was opened with.
|
|
|
|
If @module refers to the application itself, "main" is returned.</doc>
|
|
<source-position filename="gmodule.h" line="128"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="243">the filename of the module</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="237">a #GModule</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</instance-parameter>
|
|
</parameters>
|
|
</method>
|
|
<method name="symbol" c:identifier="g_module_symbol">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="299">Gets a symbol pointer from a module, such as one exported
|
|
by %G_MODULE_EXPORT. Note that a valid symbol can be %NULL.</doc>
|
|
<source-position filename="gmodule.h" line="122"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="308">%TRUE on success</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
<parameters>
|
|
<instance-parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="301">a #GModule</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</instance-parameter>
|
|
<parameter name="symbol_name" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="302">the name of the symbol to find</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="symbol"
|
|
direction="out"
|
|
caller-allocates="0"
|
|
transfer-ownership="full"
|
|
nullable="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="303">returns the pointer to the symbol value</doc>
|
|
<type name="gpointer" c:type="gpointer*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</method>
|
|
<function name="build_path"
|
|
c:identifier="g_module_build_path"
|
|
deprecated="1"
|
|
deprecated-version="2.76">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="179">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 %NULL or 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 g_module_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`.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_module_open() instead with @module_name as the
|
|
basename of the file_name argument. See %G_MODULE_SUFFIX for why.</doc-deprecated>
|
|
<source-position filename="gmodule.h" line="142"/>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="200">the complete path of the module, including the standard library
|
|
prefix and suffix. This should be freed when no longer needed</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="directory"
|
|
transfer-ownership="none"
|
|
nullable="1"
|
|
allow-none="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="181">the directory where the module is. This can be
|
|
%NULL or the empty string to indicate that the standard platform-specific
|
|
directories will be used, though that is not recommended</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="module_name" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="184">the name of the module</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="error" c:identifier="g_module_error">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="217">Gets a string describing the last module error.</doc>
|
|
<source-position filename="gmodule.h" line="118"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="222">a string describing the last module error</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="error_quark" c:identifier="g_module_error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="GLib.Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="open" c:identifier="g_module_open" introspectable="0">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="247">A thin wrapper function around g_module_open_full()</doc>
|
|
<source-position filename="gmodule.h" line="100"/>
|
|
<return-value>
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="256">a #GModule on success, or %NULL on failure</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name"
|
|
transfer-ownership="none"
|
|
nullable="1"
|
|
allow-none="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="249">the name or path to the file containing the module,
|
|
or %NULL to obtain a #GModule representing the main program itself</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="251">the flags used for opening the module. This can be the
|
|
logical OR of any of the #GModuleFlags.</doc>
|
|
<type name="ModuleFlags" c:type="GModuleFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="open_full"
|
|
c:identifier="g_module_open_full"
|
|
version="2.70"
|
|
introspectable="0"
|
|
throws="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="260">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.</doc>
|
|
<source-position filename="gmodule.h" line="104"/>
|
|
<return-value>
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="285">a #GModule on success, or %NULL on failure</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="file_name"
|
|
transfer-ownership="none"
|
|
nullable="1"
|
|
allow-none="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="262">the name or path to the file containing the module,
|
|
or %NULL to obtain a #GModule representing the main program itself</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="flags" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="264">the flags used for opening the module. This can be the
|
|
logical OR of any of the #GModuleFlags</doc>
|
|
<type name="ModuleFlags" c:type="GModuleFlags"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="supported" c:identifier="g_module_supported">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="290">Checks if modules are supported on the current platform.</doc>
|
|
<source-position filename="gmodule.h" line="96"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="295">%TRUE if modules are supported</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
</record>
|
|
<callback name="ModuleCheckInit" c:type="GModuleCheckInit">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="14">Specifies the type of the module initialization function.
|
|
If a module contains a function named g_module_check_init() it is called
|
|
automatically when the module is loaded. It is passed the #GModule structure
|
|
and should return %NULL on success or a string describing the initialization
|
|
error.</doc>
|
|
<source-position filename="gmodule.h" line="71"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="24">%NULL on success, or a string describing the initialization error</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="16">the #GModule corresponding to the module which has just been loaded</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<enumeration name="ModuleError"
|
|
version="2.70"
|
|
c:type="GModuleError"
|
|
glib:error-domain="g-module-error-quark">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="78">Errors returned by g_module_open_full().</doc>
|
|
<source-position filename="gmodule.h" line="91"/>
|
|
<member name="failed" value="0" c:identifier="G_MODULE_ERROR_FAILED">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="80">there was an error loading or opening a module file</doc>
|
|
</member>
|
|
<member name="check_failed"
|
|
value="1"
|
|
c:identifier="G_MODULE_ERROR_CHECK_FAILED">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="81">a module returned an error from its `g_module_check_init()` function</doc>
|
|
</member>
|
|
</enumeration>
|
|
<bitfield name="ModuleFlags" c:type="GModuleFlags">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="49">Flags passed to g_module_open().
|
|
Note that these flags are not supported on all platforms.</doc>
|
|
<source-position filename="gmodule.h" line="68"/>
|
|
<member name="lazy" value="1" c:identifier="G_MODULE_BIND_LAZY">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="51">specifies that symbols are only resolved when
|
|
needed. The default action is to bind all symbols when the module
|
|
is loaded.</doc>
|
|
</member>
|
|
<member name="local" value="2" c:identifier="G_MODULE_BIND_LOCAL">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="54">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.</doc>
|
|
</member>
|
|
<member name="mask" value="3" c:identifier="G_MODULE_BIND_MASK">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule.h"
|
|
line="58">mask for all flags.</doc>
|
|
</member>
|
|
</bitfield>
|
|
<callback name="ModuleUnload" c:type="GModuleUnload">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="28">Specifies the type of the module function called when it is unloaded.
|
|
If a module contains a function named g_module_unload() it is called
|
|
automatically when the module is unloaded.
|
|
It is passed the #GModule structure.</doc>
|
|
<source-position filename="gmodule.h" line="72"/>
|
|
<return-value transfer-ownership="none">
|
|
<type name="none" c:type="void"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="module" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="30">the #GModule about to be unloaded</doc>
|
|
<type name="Module" c:type="GModule*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</callback>
|
|
<function name="module_build_path"
|
|
c:identifier="g_module_build_path"
|
|
moved-to="Module.build_path"
|
|
deprecated="1"
|
|
deprecated-version="2.76">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="179">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 %NULL or 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 g_module_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`.</doc>
|
|
<doc-deprecated xml:space="preserve">Use g_module_open() instead with @module_name as the
|
|
basename of the file_name argument. See %G_MODULE_SUFFIX for why.</doc-deprecated>
|
|
<source-position filename="gmodule.h" line="142"/>
|
|
<return-value transfer-ownership="full">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="200">the complete path of the module, including the standard library
|
|
prefix and suffix. This should be freed when no longer needed</doc>
|
|
<type name="utf8" c:type="gchar*"/>
|
|
</return-value>
|
|
<parameters>
|
|
<parameter name="directory"
|
|
transfer-ownership="none"
|
|
nullable="1"
|
|
allow-none="1">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="181">the directory where the module is. This can be
|
|
%NULL or the empty string to indicate that the standard platform-specific
|
|
directories will be used, though that is not recommended</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
<parameter name="module_name" transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="184">the name of the module</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</parameter>
|
|
</parameters>
|
|
</function>
|
|
<function name="module_error"
|
|
c:identifier="g_module_error"
|
|
moved-to="Module.error">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="217">Gets a string describing the last module error.</doc>
|
|
<source-position filename="gmodule.h" line="118"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="222">a string describing the last module error</doc>
|
|
<type name="utf8" c:type="const gchar*"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="module_error_quark"
|
|
c:identifier="g_module_error_quark"
|
|
moved-to="Module.error_quark">
|
|
<return-value transfer-ownership="none">
|
|
<type name="GLib.Quark" c:type="GQuark"/>
|
|
</return-value>
|
|
</function>
|
|
<function name="module_supported"
|
|
c:identifier="g_module_supported"
|
|
moved-to="Module.supported">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="290">Checks if modules are supported on the current platform.</doc>
|
|
<source-position filename="gmodule.h" line="96"/>
|
|
<return-value transfer-ownership="none">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="295">%TRUE if modules are supported</doc>
|
|
<type name="gboolean" c:type="gboolean"/>
|
|
</return-value>
|
|
</function>
|
|
<docsection name="modules">
|
|
<doc xml:space="preserve"
|
|
filename="gmodule-2.0.c"
|
|
line="99">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 Windows platforms via DLLs.
|
|
|
|
A program which wants to use these functions must be linked to the
|
|
libraries output by the command `pkg-config --libs gmodule-2.0`.
|
|
|
|
To use them you must first determine whether dynamic loading
|
|
is supported on the platform by calling g_module_supported().
|
|
If it is, you can open a module with g_module_open(),
|
|
find the module's symbols (e.g. function names) with g_module_symbol(),
|
|
and later close the module with g_module_close().
|
|
g_module_name() will return the file name of a currently opened module.
|
|
|
|
If any of the above functions fail, the error status can be found with
|
|
g_module_error().
|
|
|
|
The #GModule implementation features reference counting for opened modules,
|
|
and supports hook functions within a module which are called when the
|
|
module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
|
|
|
|
If your module introduces static data to common subsystems in the running
|
|
program, e.g. through calling
|
|
`g_quark_from_static_string ("my-module-stuff")`,
|
|
it must ensure that it is never unloaded, by calling g_module_make_resident().
|
|
|
|
Example: Calling a function defined in a GModule
|
|
|[<!-- language="C" -->
|
|
// the function signature for 'say_hello'
|
|
typedef void (* SayHelloFunc) (const char *message);
|
|
|
|
gboolean
|
|
just_say_hello (const char *filename, GError **error)
|
|
{
|
|
SayHelloFunc say_hello;
|
|
GModule *module;
|
|
|
|
module = g_module_open (filename, G_MODULE_BIND_LAZY);
|
|
if (!module)
|
|
{
|
|
g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
|
|
"%s", g_module_error ());
|
|
return FALSE;
|
|
}
|
|
|
|
if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
|
|
{
|
|
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
|
|
"%s: %s", filename, g_module_error ());
|
|
if (!g_module_close (module))
|
|
g_warning ("%s: %s", filename, g_module_error ());
|
|
return FALSE;
|
|
}
|
|
|
|
if (say_hello == NULL)
|
|
{
|
|
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
|
|
"symbol say_hello is NULL");
|
|
if (!g_module_close (module))
|
|
g_warning ("%s: %s", filename, g_module_error ());
|
|
return FALSE;
|
|
}
|
|
|
|
// call our function in the module
|
|
say_hello ("Hello world!");
|
|
|
|
if (!g_module_close (module))
|
|
g_warning ("%s: %s", filename, g_module_error ());
|
|
return TRUE;
|
|
}
|
|
]|</doc>
|
|
</docsection>
|
|
</namespace>
|
|
</repository>
|