From: Matthias Clasen Date: Fri, 12 Sep 2008 22:59:03 +0000 (+0000) Subject: Reinstate docs that got lost X-Git-Tag: GLIB_2_18_1~27 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=876aaf71740a78510c71fa752d5586239f7cb176;p=platform%2Fupstream%2Fglib.git Reinstate docs that got lost svn path=/trunk/; revision=7478 --- diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 121936f..f45d595 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,7 @@ +2008-09-12 Matthias Clasen + + * glib/tmpl/modules.sgml: Reinstate docs that somehow got lost. + 2008-09-02 Matthias Clasen * === Released 2.18.0 === diff --git a/docs/reference/glib/tmpl/modules.sgml b/docs/reference/glib/tmpl/modules.sgml index 33d2683..c47df35 100644 --- a/docs/reference/glib/tmpl/modules.sgml +++ b/docs/reference/glib/tmpl/modules.sgml @@ -99,3 +99,186 @@ just_say_hello (const char *filename, GError **error) + + +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. + + +@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. + + +@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. +@Returns: a #GModule on success, or %NULL on failure. + + + + +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. + + +@module: a #GModule. +@Returns: the filename of the module, or "main" if the module is the main +program itself. + + + + +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. + + +@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. + + + +