* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
- * License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- * Boston, MA 02111-1307, USA.
+ * License along with this library; if not, see <http://www.gnu.org/licenses/>.
*/
/*
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
-#ifdef HAVE_UNISTD_H
+#ifdef G_OS_UNIX
#include <unistd.h>
#endif
#ifdef G_OS_WIN32
#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 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;
+ * }
+ * ]|
+ */
+
+/**
+ * GModule:
+ *
+ * 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.
+ */
+
+/**
+ * GModuleCheckInit:
+ * @module: the #GModule corresponding to the module which has just been loaded
+ *
+ * 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.
+ *
+ * Returns: %NULL on success, or a string describing the initialization error
+ */
+
+/**
+ * GModuleUnload:
+ * @module: the #GModule about to be unloaded
+ *
+ * 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 most Unices and Linux this is "so", 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 refernce counts on
- * modules e.g. the shl_* implementation of HP-UX
- * (http://www.stat.umn.edu/~luke/xls/projects/dlbasics/dlbasics.html).
- * Also, the module for the program itself is kept seperatedly for
+ * That's needed because some platforms don't support references counts on
+ * modules. Also, the module for the program itself is kept seperately for
* faster access and because it has special semantics.
*/
/* --- variables --- */
static GModule *modules = NULL;
static GModule *main_module = NULL;
-static GStaticPrivate module_error_private = G_STATIC_PRIVATE_INIT;
+static GPrivate module_error_private = G_PRIVATE_INIT (g_free);
static gboolean module_debug_initialized = FALSE;
static guint module_debug_flags = 0;
static inline void
g_module_set_error_unduped (gchar *error)
{
- g_static_private_set (&module_error_private, error, g_free);
+ g_private_replace (&module_error_private, error);
errno = 0;
}
#define SUPPORT_OR_RETURN(rv) { g_module_set_error (NULL); }
#if (G_MODULE_IMPL == G_MODULE_IMPL_DL)
#include "gmodule-dl.c"
-#elif (G_MODULE_IMPL == G_MODULE_IMPL_DLD)
-#include "gmodule-dld.c"
#elif (G_MODULE_IMPL == G_MODULE_IMPL_WIN32)
#include "gmodule-win32.c"
#elif (G_MODULE_IMPL == G_MODULE_IMPL_DYLD)
#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)
{
module_debug_initialized = TRUE;
}
-static GStaticRecMutex g_module_global_lock = G_STATIC_REC_MUTEX_INIT;
+static GRecMutex g_module_global_lock;
GModule*
g_module_open (const gchar *file_name,
SUPPORT_OR_RETURN (NULL);
- g_static_rec_mutex_lock (&g_module_global_lock);
+ g_rec_mutex_lock (&g_module_global_lock);
if (G_UNLIKELY (!module_debug_initialized))
_g_module_debug_init ();
else
main_module->ref_count++;
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return main_module;
}
{
module->ref_count++;
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return module;
}
module->ref_count++;
g_module_set_error (NULL);
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return module;
}
{
gchar *error;
- error = g_strconcat ("GModule (",
- file_name ? file_name : "NULL",
- ") initialization check failed: ",
+ error = g_strconcat ("GModule (", file_name, ") ",
+ "initialization check failed: ",
check_failed, NULL);
g_module_close (module);
module = NULL;
(module_debug_flags & G_MODULE_DEBUG_RESIDENT_MODULES))
g_module_make_resident (module);
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return module;
}
#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: (allow-none): 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);
#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);
g_return_val_if_fail (module != NULL, FALSE);
g_return_val_if_fail (module->ref_count > 0, FALSE);
- g_static_rec_mutex_lock (&g_module_global_lock);
+ g_rec_mutex_lock (&g_module_global_lock);
module->ref_count--;
g_free (module);
}
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return g_module_error() == NULL;
}
+/**
+ * g_module_make_resident:
+ * @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.
+ */
void
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_static_private_get (&module_error_private);
+ return g_private_get (&module_error_private);
}
+/**
+ * g_module_symbol:
+ * @module: a #GModule
+ * @symbol_name: the name of the symbol to find
+ * @symbol: (out): 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;
g_return_val_if_fail (symbol_name != NULL, FALSE);
g_return_val_if_fail (symbol != NULL, FALSE);
- g_static_rec_mutex_lock (&g_module_global_lock);
+ g_rec_mutex_lock (&g_module_global_lock);
#ifdef G_MODULE_NEED_USCORE
{
{
gchar *error;
- error = g_strconcat ("`", symbol_name, "': ", module_error, NULL);
+ error = g_strconcat ("'", symbol_name, "': ", module_error, NULL);
g_module_set_error (error);
g_free (error);
*symbol = NULL;
}
- g_static_rec_mutex_unlock (&g_module_global_lock);
+ g_rec_mutex_unlock (&g_module_global_lock);
return !module_error;
}
+/**
+ * g_module_name:
+ * @module: a #GModule
+ *
+ * Returns the filename that the module was opened with.
+ *
+ * If @module refers to the application itself, "main" is returned.
+ *
+ * Returns: (transfer none): the filename of the module
+ */
const gchar *
g_module_name (GModule *module)
{
#endif
-gchar*
+/**
+ * g_module_build_path:
+ * @directory: (allow-none): 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);
projects / platform / upstream / glib.git / blobdiff