From: Matthias Clasen Date: Tue, 15 Nov 2011 02:06:30 +0000 (-0500) Subject: Move GModule docs inline X-Git-Tag: 2.31.2~118 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=127df9bd83d610cb989e63037f3e3a6b64c034e0;p=platform%2Fupstream%2Fglib.git Move GModule docs inline --- diff --git a/docs/reference/glib/tmpl/.gitignore b/docs/reference/glib/tmpl/.gitignore index b6cee54..06e0652 100644 --- a/docs/reference/glib/tmpl/.gitignore +++ b/docs/reference/glib/tmpl/.gitignore @@ -38,6 +38,7 @@ memory_slices.sgml memory.sgml messages.sgml misc_utils.sgml +modules.sgml option.sgml patterns.sgml quarks.sgml diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml deleted file mode 100644 index 0b7ba74..0000000 --- a/docs/reference/glib/tmpl/modules.sgml +++ /dev/null @@ -1,291 +0,0 @@ - -Dynamic Loading of Modules - - -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 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(). - - - - -Calling a function defined in a <structname>GModule</structname> - -/* 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; -} - - - - - - - - - - - - - - - - - -The #GModule struct is an opaque data structure to represent a -Dynamically-Loaded Module. -It should only be accessed via the following functions. - - - - - -Checks if modules are supported on the current platform. - - -@void: -@Returns: %TRUE if modules are supported. - - - - -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. - - -@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. -@Returns: the complete path of the module, including the standard library -prefix and suffix. This should be freed when no longer needed. - - - - -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. - -@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. - - - - -Flags passed to g_module_open(). Note that these flags are -not supported on all platforms. - - -@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. - - - -Gets a symbol pointer from a module, such as one exported by #G_MODULE_EXPORT. - - -Note that a valid symbol can be %NULL. - - -@module: a #GModule. -@symbol_name: the name of the symbol to find. -@symbol: returns the pointer to the symbol value. -@Returns: %TRUE on success. - - - - -Gets the filename from a #GModule. - - -@Returns: the filename of the module, or "main" if the module is the main -program itself. - -@module: a #GModule. - - - - -Ensures that a module will never be unloaded. -Any future g_module_close() calls on the module will be ignored. - - -@module: a #GModule to make permanently resident. - - - - -Closes a module. - - -@module: a #GModule to close. -@Returns: %TRUE on success. - - - - -Gets a string describing the last module error. - - -@void: -@Returns: a string describing the last module error. - - - - -Specifies the type of the module initialization function. -g_module_check_init -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. - - -@module: the #GModule corresponding to the module which has just been loaded. -@Returns: %NULL on success, or a string describing the initialization error. - - - - -g_module_unload -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. - - -@module: the #GModule about to be unloaded. - - - - -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". - - - - - - -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. - - - - - - -Used to declare functions imported from modules. - - - - diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c index e4ef3eb..388c6b5 100644 --- a/gmodule/gmodule.c +++ b/gmodule/gmodule.c @@ -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 + * 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(). + * + * + * + * Calling a function defined in a <structname>GModule</structname> + * + * /* 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; + * } + * + * + */ + +/** + * GModule: + * The #GModule struct is an opaque data structure to represent a + * Dynamically-Loaded + * Module. 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. + * g_module_check_init + * 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 + * + * g_module_unload + * 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 /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. + * + * 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);