X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gmodule%2Fgmodule.c;h=bf1eac73e1badc491698d10591ad5d23bb0a571b;hb=bc6ee788b4ff6590513da6ab657448885e92b20b;hp=2d7f410b6109ffb4099586bd5e90a9fd091fbe93;hpb=73007021796f33d7ccec4e5f2bb2b2f8660347f2;p=platform%2Fupstream%2Fglib.git diff --git a/gmodule/gmodule.c b/gmodule/gmodule.c index 2d7f410..bf1eac7 100644 --- a/gmodule/gmodule.c +++ b/gmodule/gmodule.c @@ -12,9 +12,7 @@ * 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 . */ /* @@ -38,7 +36,7 @@ #include #include #include -#ifdef HAVE_UNISTD_H +#ifdef G_OS_UNIX #include #endif #ifdef G_OS_WIN32 @@ -48,11 +46,141 @@ #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 + * |[ + * // 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. */ @@ -91,7 +219,7 @@ static inline GModule* g_module_find_by_name (const gchar *name); /* --- 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; @@ -135,7 +263,7 @@ g_module_find_by_name (const gchar *name) 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; } @@ -150,8 +278,6 @@ g_module_set_error (const gchar *error) #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) @@ -194,6 +320,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) { @@ -326,7 +460,7 @@ _g_module_debug_init (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, @@ -338,7 +472,7 @@ 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 (); @@ -368,7 +502,7 @@ g_module_open (const gchar *file_name, 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; } @@ -378,7 +512,7 @@ g_module_open (const gchar *file_name, { module->ref_count++; - g_static_rec_mutex_unlock (&g_module_global_lock); + g_rec_mutex_unlock (&g_module_global_lock); return module; } @@ -461,7 +595,7 @@ g_module_open (const gchar *file_name, 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; } @@ -493,9 +627,8 @@ g_module_open (const gchar *file_name, { 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; @@ -512,7 +645,7 @@ g_module_open (const gchar *file_name, (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; } @@ -520,9 +653,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: (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); @@ -534,15 +704,23 @@ 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); 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--; @@ -586,10 +764,17 @@ g_module_close (GModule *module) 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) { @@ -598,16 +783,34 @@ g_module_make_resident (GModule *module) module->is_resident = TRUE; } -G_CONST_RETURN gchar* +/** + * 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; @@ -619,7 +822,7 @@ g_module_symbol (GModule *module, 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 { @@ -638,17 +841,27 @@ g_module_symbol (GModule *module, { 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_CONST_RETURN gchar* +/** + * 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) { g_return_val_if_fail (module != NULL, NULL); @@ -663,7 +876,7 @@ g_module_name (GModule *module) #undef g_module_name -G_CONST_RETURN gchar* +const gchar * g_module_name (GModule *module) { g_return_val_if_fail (module != NULL, NULL); @@ -676,9 +889,33 @@ 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);