docs/reference/glib/tmpl/modules.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Dynamic Loading of Modules
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 portable method for dynamically loading 'plug-ins'.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 These functions provide a portable way to dynamically load object files
  10 (commonly known as 'plug-ins').
  11 The current implementation supports all systems that provide
  12 an implementation of dlopen() (e.g. Linux/Sun), as well as HP-UX via its
  13 shl_load() mechanism, and Windows platforms via DLLs.
  14 </para>
  15
  16 <para>
  17 A program, which wants to use these functions must be linked to the
  18 libraries output by the command "glib-config --libs gmodule".
  19 </para>
  20
  21 <para>
  22 To use them you must first determine whether dynamic loading
  23 is supported on the platform by calling g_module_supported().
  24 If it is, you can open a module with g_module_open(),
  25 find the module's symbols (e.g. function names) with g_module_symbol(),
  26 and later close the module with g_module_close().
  27 g_module_name() will return the file name of a currently opened module.
  28 </para>
  29 <para>
  30 If any of the above functions fail, the error status can be found with
  31 g_module_error().
  32 </para>
  33 <para>
  34 The gmodule implementation features reference counting for opened modules,
  35 and supports hook functions within a module which are called when the
  36 module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
  37 </para>
  38 <para>
  39 If your module introduces static data to common subsystems in the running
  40 program, e.g. through calling g_quark_from_static_string ("my-module-stuff"),
  41 it must ensure that it is never unloaded, by calling g_module_make_resident().
  42 </para>
  43
  44 <!-- ##### SECTION See_Also ##### -->
  45 <para>
  46
  47 </para>
  48
  49 <!-- ##### STRUCT GModule ##### -->
  50 <para>
  51 The #GModule struct is an opaque data structure to represent a
  52 <link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded Module</link>.
  53 It should only be accessed via the following functions.
  54 </para>
  55
  56
  57 <!-- ##### FUNCTION g_module_supported ##### -->
  58 <para>
  59 Checks if modules are supported on the current platform.
  60 </para>
  61
  62 @Returns: TRUE if modules are supported.
  63
  64
  65 <!-- ##### FUNCTION g_module_build_path ##### -->
  66 <para>
  67 A portable way to build the filename of a module. The platform-specific
  68 prefix and suffix are added to the filename, if needed, and the result is
  69 added to the directory, using the correct separator character.
  70 </para>
  71 <para>
  72 The directory should specify the directory where the module can be found.
  73 It can be NULL or an empty string to indicate that the module is in a standard
  74 operating-system specific directory, though this is not recommended since the
  75 wrong module may be found.
  76 </para>
  77 <para>
  78 For example, calling g_module_build_path() on a Linux system with a directory
  79 of "/lib" and a module_name of "mylibrary" will return "/lib/libmylibrary.so".
  80 On a Windows system, using "\Windows" as the directory it will return
  81 "\Windows\mylibrary.dll".
  82 </para>
  83
  84 @directory: the directory where the module is. This can be NULL or the empty
  85 string to indicate that the standard operating system-specific directories
  86 will be used, though that is not recommended.
  87 @module_name: the name of the module.
  88 @Returns: the complete path of the module, including the standard library
  89 prefix and suffix. This should be freed when no longer needed.
  90
  91
  92 <!-- ##### FUNCTION g_module_open ##### -->
  93 <para>
  94 Opens a module. If the module has already been opened, its reference
  95 count is incremented.
  96 </para>
  97
  98 <para>
  99 First of all g_module_open() tries to open @file_name as a module. If
 100 that fails and @file_name has the ".la"-suffix (and is a libtool
 101 archive) it tries to open the corresponding module. If that fails and
 102 it doesn't have the proper module suffix for that plaform
 103 (#G_MODULE_SUFFIX,) this suffix will be appended and the coresponding
 104 module will be opended. If that fails and @file_name doesn't have the
 105 ".la"-suffix, this suffix is appended and g_module_open() tries to
 106 open the corresponding module. If eventually that fails as well, NULL
 107 is returned.
 108 </para>
 109
 110 @file_name: the name of the file containing the module.
 111 @flags: the flags used for opening the module. Currently this can be 0 or
 112 G_MODULE_BIND_LAZY for lazy binding, where symbols are only bound when needed.
 113 @Returns: a #GModule on success, or NULL on failure.
 114
 115
 116 <!-- ##### ENUM GModuleFlags ##### -->
 117 <para>
 118 Flags passed to g_module_open().
 119 G_MODULE_BIND_LAZY specifies that symbols are only resolved when needed.
 120 The default action is to bind all symbols when the module is loaded.
 121 (G_MODULE_BIND_LAZY is not supported on all platforms.)
 122 </para>
 123
 124 @G_MODULE_BIND_LAZY:
 125 @G_MODULE_BIND_MASK:
 126
 127 <!-- ##### FUNCTION g_module_symbol ##### -->
 128 <para>
 129 Gets a symbol pointer from a module.
 130 </para>
 131
 132 @module: the module.
 133 @symbol_name: the name of the symbol to find.
 134 @symbol: returns the pointer to the symbol value.
 135 @Returns: TRUE on success.
 136
 137
 138 <!-- ##### FUNCTION g_module_name ##### -->
 139 <para>
 140 Gets the file name from a #GModule.
 141 </para>
 142
 143 @module: the module.
 144 @Returns: the file name of the module, or "main" if the module is the main
 145 program itself.
 146
 147
 148 <!-- ##### FUNCTION g_module_make_resident ##### -->
 149 <para>
 150 Ensures that a module will never be unloaded.
 151 Any future g_module_close() calls on the module will be ignored.
 152 </para>
 153
 154 @module: a module to make permanently resident.
 155
 156
 157 <!-- ##### FUNCTION g_module_close ##### -->
 158 <para>
 159 Closes a module.
 160 </para>
 161
 162 @module: the module to close.
 163 @Returns: TRUE on success.
 164
 165
 166 <!-- ##### FUNCTION g_module_error ##### -->
 167 <para>
 168 Gets a string describing the last module error.
 169 </para>
 170
 171 @Returns: a string describing the last module error.
 172
 173
 174 <!-- ##### USER_FUNCTION GModuleCheckInit ##### -->
 175 <para>
 176 Specifies the type of the module initialization function.
 177 If a module contains a function named g_module_check_init() it is called
 178 automatically when the module is loaded. It is passed the #GModule structure
 179 and should return NULL on success or a string describing the initialization
 180 error.
 181 </para>
 182
 183 @module: the #GModule corresponding to the module which has just been loaded.
 184 @Returns: NULL on success, or a string describing the initialization error.
 185
 186
 187 <!-- ##### USER_FUNCTION GModuleUnload ##### -->
 188 <para>
 189 Specifies the type of the module function called when it is unloaded.
 190 If a module contains a function named g_module_unload() it is called
 191 automatically when the module is unloaded.
 192 It is passed the #GModule structure.
 193 </para>
 194
 195 @module: the module about to be unloaded.
 196
 197
 198 <!-- ##### MACRO G_MODULE_EXPORT ##### -->
 199 <para>
 200 Used to declare functions exported by modules.
 201 </para>
 202
 203
 204
 205 <!-- ##### MACRO G_MODULE_IMPORT ##### -->
 206 <para>
 207 Used to declare functions imported from modules.
 208 </para>
 209
 210
 211