luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-22 09:57:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Move GModule docs inline

Browse Source
This commit is contained in:
Matthias Clasen
2011-11-14 21:06:30 -05:00
parent 2195e20dce
commit 127df9bd83
3 changed files with 250 additions and 300 deletions
Download Patch File Download Diff File Expand all files Collapse all files

258
gmodule/gmodule.c
View File

@@ -48,6 +48,143 @@
#include "gmoduleconf.h"
#include "gstdio.h"
/**
* SECTION:modules
* @title: Dynamic Loading of Modules
* @short_description: portable method for dynamically loading 'plug-ins'
*
* 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.
*
* A program which wants to use these functions must be linked to the
* libraries output by the command
* <command>pkg-config --libs gmodule-2.0</command>.
*
* 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
* <literal>g_quark_from_static_string ("my-module-stuff")</literal>,
* it must ensure that it is never unloaded, by calling g_module_make_resident().
*
* <para>
* <example>
* <title>Calling a function defined in a <structname>GModule</structname></title>
* <programlisting>
* /&ast; the function signature for 'say_hello' &ast;/
* 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,
* "&percnt;s", g_module_error ());
* return FALSE;
* }
*
* if (!g_module_symbol (module, "say_hello", (gpointer *)&amp;say_hello))
* {
* g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
* "&percnt;s: &percnt;s", filename, g_module_error ());
* if (!g_module_close (module))
* g_warning ("&percnt;s: &percnt;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 ("&percnt;s: &percnt;s", filename, g_module_error ());
* return FALSE;
* }
*
* /&ast; call our function in the module &ast;/
* say_hello ("Hello world!");
*
* if (!g_module_close (module))
* g_warning ("&percnt;s: &percnt;s", filename, g_module_error ());
* return TRUE;
* }
* </programlisting>
* </example>
*/
/**
* GModule:
* The #GModule struct is an opaque data structure to represent a
* <link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded
* Module</link>. It should only be accessed via the following functions.
*/
/**
* GModuleCheckInit:
* @module: the #GModule corresponding to the module which has just been loaded
*
* Specifies the type of the module initialization function.
* <indexterm zone="g-module-check-init"><primary>g_module_check_init</primary></indexterm>
* 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.
*
* Returns: %NULL on success, or a string describing the initialization error
*/
/**
* GModuleUnload:
* @module: the #GModule about to be unloaded
*
* <indexterm zone="g-module-unload"><primary>g_module_unload</primary></indexterm>
* 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.
*/
/**
* G_MODULE_SUFFIX:
*
* Expands to the proper shared library suffix for the current platform
* without the leading dot. For the most Unices and Linux this is "so",
* for some HP-UX versions this is "sl" and for Windows this is "dll".
*/
/**
* G_MODULE_EXPORT:
*
* Used to declare functions exported by modules. This is a no-op on Linux
* and Unices, but when compiling for Windows, it marks a symbol to be
* exported from the library or executable being built.
*/
/**
* G_MODULE_IMPORT:
*
* Used to declare functions imported from modules.
*/
/* We maintain a list of modules, so we can reference count them.
* That's needed because some platforms don't support references counts on
* modules e.g. the shl_* implementation of HP-UX
@@ -194,6 +331,14 @@ _g_module_build_path (const gchar *directory,
#endif /* no implementation */
/* --- functions --- */
/**
* g_module_supported:
*
* Checks if modules are supported on the current platform.
*
* Returns: %TRUE if modules are supported
*/
gboolean
g_module_supported (void)
{
@@ -519,9 +664,46 @@ g_module_open (const gchar *file_name,
#undef g_module_open
GModule*
g_module_open (const gchar *file_name,
GModuleFlags flags)
/**
* GModuleFlags:
* @G_MODULE_BIND_LAZY: specifies that symbols are only resolved when
* needed. The default action is to bind all symbols when the module
* is loaded.
* @G_MODULE_BIND_LOCAL: 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.
* @G_MODULE_BIND_MASK: mask for all flags.
*
* Flags passed to g_module_open().
* Note that these flags are not supported on all platforms.
*/
/**
* g_module_open:
* @file_name: the name of the file containing the module, or %NULL
* to obtain a #GModule representing the main program itself
* @flags: the flags used for opening the module. This can be the
* logical OR of any of the #GModuleFlags
*
* Opens a module. If the module has already been opened,
* its reference count is incremented.
*
* First of all g_module_open() tries to open @file_name as a module.
* If that fails and @file_name has the ".la"-suffix (and is a libtool
* archive) it tries to open the corresponding module. If that fails
* and it doesn't have the proper module suffix for the platform
* (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding
* module will be opended. If that fails and @file_name doesn't have the
* ".la"-suffix, this suffix is appended and g_module_open() tries to open
* the corresponding module. If eventually that fails as well, %NULL is
* returned.
*
* Returns: a #GModule on success, or %NULL on failure
*/
GModule *
g_module_open (const gchar *file_name,
GModuleFlags flags)
{
gchar *utf8_file_name = g_locale_to_utf8 (file_name, -1, NULL, NULL, NULL);
GModule *retval = g_module_open_utf8 (utf8_file_name, flags);
@@ -533,8 +715,16 @@ g_module_open (const gchar *file_name,
#endif
/**
* g_module_close:
* @module: a #GModule to close
*
* Closes a module.
*
* Returns: %TRUE on success
*/
gboolean
g_module_close (GModule *module)
g_module_close (GModule *module)
{
SUPPORT_OR_RETURN (FALSE);
@@ -597,16 +787,34 @@ g_module_make_resident (GModule *module)
module->is_resident = TRUE;
}
/**
* g_module_error:
*
* Gets a string describing the last module error.
*
* Returns: a string describing the last module error
*/
const gchar *
g_module_error (void)
{
return g_private_get (&module_error_private);
}
/**
* g_module_symbol:
* @module: a #GModule
* @symbol_name: the name of the symbol to find
* @symbol: returns the pointer to the symbol value
*
* Gets a symbol pointer from a module, such as one exported
* by #G_MODULE_EXPORT. Note that a valid symbol can be %NULL.
*
* Returns: %TRUE on success
*/
gboolean
g_module_symbol (GModule *module,
const gchar *symbol_name,
gpointer *symbol)
g_module_symbol (GModule *module,
const gchar *symbol_name,
gpointer *symbol)
{
const gchar *module_error;
@@ -647,6 +855,13 @@ g_module_symbol (GModule *module,
return !module_error;
}
/**
* g_module_name:
* @module: a #GModule to make permanently resident
*
* Ensures that a module will never be unloaded.
* Any future g_module_close() calls on the module will be ignored.
*/
const gchar *
g_module_name (GModule *module)
{
@@ -675,9 +890,34 @@ g_module_name (GModule *module)
#endif
gchar*
/**
* g_module_build_path:
* @directory: 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
* @module_name: the name of the module
*
* 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 <filename>/lib</filename> and a @module_name of "mylibrary"
* will return <filename>/lib/libmylibrary.so</filename>. On a Windows system,
* using <filename>\Windows</filename> as the directory it will return
* <filename>\Windows\mylibrary.dll</filename>.
*
* Returns: the complete path of the module, including the standard library
* prefix and suffix. This should be freed when no longer needed
*/
gchar *
g_module_build_path (const gchar *directory,
const gchar *module_name)
const gchar *module_name)
{
g_return_val_if_fail (module_name != NULL, NULL);