173
159
The directory should specify the directory where the module can be found.
174
It can be <link linkend="NULL:CAPS"><literal>NULL</literal></link> or an empty string to indicate that the module is in a standard
160
It can be <link linkend="NULL--CAPS"><literal>NULL</literal></link> or an empty string to indicate that the module is in a standard
175
161
platform-specific directory, though this is not recommended since the
176
162
wrong module may be found.
179
165
For example, calling <link linkend="g-module-build-path"><function>g_module_build_path()</function></link> on a Linux system with a <parameter>directory</parameter>
180
of <filename>/lib</filename> and a <parameter>module_name</parameter> of "mylibrary" will return
181
<filename>/lib/libmylibrary.so</filename>. On a Windows system, using
166
of <filename>/lib</filename> and a <parameter>module_name</parameter> of "mylibrary" will return
167
<filename>/lib/libmylibrary.so</filename>. On a Windows system, using
182
168
<filename>\Windows</filename> as the directory it will return
183
169
<filename>\Windows\mylibrary.dll</filename>.
184
170
</para><variablelist role="params">
185
<varlistentry><term><parameter>directory</parameter> :</term>
186
<listitem><simpara>the directory where the module is. This can be <link linkend="NULL:CAPS"><literal>NULL</literal></link> or the empty
187
string to indicate that the standard platform-specific directories will be
171
<varlistentry><term><parameter>directory</parameter> :</term>
172
<listitem><simpara>the directory where the module is. This can be <link linkend="NULL--CAPS"><literal>NULL</literal></link> or the empty
173
string to indicate that the standard platform-specific directories will be
188
174
used, though that is not recommended.
189
175
</simpara></listitem></varlistentry>
190
<varlistentry><term><parameter>module_name</parameter> :</term>
176
<varlistentry><term><parameter>module_name</parameter> :</term>
191
177
<listitem><simpara>the name of the module.
192
178
</simpara></listitem></varlistentry>
193
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the complete path of the module, including the standard library
179
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the complete path of the module, including the standard library
194
180
prefix and suffix. This should be freed when no longer needed.
197
181
</simpara></listitem></varlistentry>
198
182
</variablelist></refsect2>
200
<title><anchor id="g-module-open" role="function"/>g_module_open ()</title>
201
<indexterm><primary>g_module_open</primary></indexterm><programlisting><link linkend="GModule">GModule</link>* g_module_open (const <link linkend="gchar">gchar</link> *file_name,
183
<refsect2 id="g-module-open" role="function">
184
<title>g_module_open ()</title>
185
<indexterm zone="g-module-open"><primary sortas="g_module_open">g_module_open</primary></indexterm><programlisting><link linkend="GModule">GModule</link>* g_module_open (const <link linkend="gchar">gchar</link> *file_name,
202
186
<link linkend="GModuleFlags">GModuleFlags</link> flags);</programlisting>
204
188
Opens a module. If the module has already been opened, its reference
205
count is incremented.
189
count is incremented.
209
192
First of all <link linkend="g-module-open"><function>g_module_open()</function></link> tries to open <parameter>file_name</parameter> as a module. If
210
that fails and <parameter>file_name</parameter> has the ".la"-suffix (and is a libtool archive)
211
it tries to open the corresponding module. If that fails and it doesn't
212
have the proper module suffix for the platform (<link linkend="G-MODULE-SUFFIX:CAPS"><type>G_MODULE_SUFFIX</type></link>), this
213
suffix will be appended and the corresponding module will be opended. If
214
that fails and <parameter>file_name</parameter> doesn't have the ".la"-suffix, this suffix is
215
appended and <link linkend="g-module-open"><function>g_module_open()</function></link> tries to open the corresponding module. If
216
eventually that fails as well, <link linkend="NULL:CAPS"><literal>NULL</literal></link> is returned.
193
that fails and <parameter>file_name</parameter> has the ".la"-suffix (and is a libtool archive)
194
it tries to open the corresponding module. If that fails and it doesn't
195
have the proper module suffix for the platform (<link linkend="G-MODULE-SUFFIX--CAPS"><type>G_MODULE_SUFFIX</type></link>), this
196
suffix will be appended and the corresponding module will be opended. If
197
that fails and <parameter>file_name</parameter> doesn't have the ".la"-suffix, this suffix is
198
appended and <link linkend="g-module-open"><function>g_module_open()</function></link> tries to open the corresponding module. If
199
eventually that fails as well, <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
217
200
</para><variablelist role="params">
218
<varlistentry><term><parameter>file_name</parameter> :</term>
219
<listitem><simpara>the name of the file containing the module, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to obtain
201
<varlistentry><term><parameter>file_name</parameter> :</term>
202
<listitem><simpara>the name of the file containing the module, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> to obtain
220
203
a <link linkend="GModule"><type>GModule</type></link> representing the main program itself.
221
204
</simpara></listitem></varlistentry>
222
<varlistentry><term><parameter>flags</parameter> :</term>
205
<varlistentry><term><parameter>flags</parameter> :</term>
223
206
<listitem><simpara>the flags used for opening the module. This can be the logical
224
207
OR of any of the <link linkend="GModuleFlags"><type>GModuleFlags</type></link>.
225
208
</simpara></listitem></varlistentry>
226
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a <link linkend="GModule"><type>GModule</type></link> on success, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> on failure.
209
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a <link linkend="GModule"><type>GModule</type></link> on success, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> on failure.
229
210
</simpara></listitem></varlistentry>
230
211
</variablelist></refsect2>
232
<title><anchor id="GModuleFlags" role="enum"/>enum GModuleFlags</title>
233
<indexterm><primary>GModuleFlags</primary></indexterm><programlisting>typedef enum
212
<refsect2 id="GModuleFlags" role="enum">
213
<title>enum GModuleFlags</title>
214
<indexterm zone="GModuleFlags"><primary sortas="GModuleFlags">GModuleFlags</primary></indexterm><programlisting>typedef enum
235
216
G_MODULE_BIND_LAZY = 1 << 0,
236
217
G_MODULE_BIND_LOCAL = 1 << 1,
241
222
Flags passed to <link linkend="g-module-open"><function>g_module_open()</function></link>. Note that these flags are
242
223
not supported on all platforms.
243
224
</para><variablelist role="enum">
245
<term><anchor id="G-MODULE-BIND-LAZY:CAPS" role="constant"/><literal>G_MODULE_BIND_LAZY</literal></term>
225
<varlistentry id="G-MODULE-BIND-LAZY--CAPS" role="constant">
226
<term><literal>G_MODULE_BIND_LAZY</literal></term>
246
227
<listitem><simpara>specifies that symbols are only resolved when needed.
247
228
The default action is to bind all symbols when the module is loaded.
248
229
</simpara></listitem>
251
<term><anchor id="G-MODULE-BIND-LOCAL:CAPS" role="constant"/><literal>G_MODULE_BIND_LOCAL</literal></term>
231
<varlistentry id="G-MODULE-BIND-LOCAL--CAPS" role="constant">
232
<term><literal>G_MODULE_BIND_LOCAL</literal></term>
252
233
<listitem><simpara>specifies that symbols in the module should
253
234
not be added to the global name space. The default action on most
254
235
platforms is to place symbols in the module in the global name space,
255
236
which may cause conflicts with existing symbols.
256
237
</simpara></listitem>
259
<term><anchor id="G-MODULE-BIND-MASK:CAPS" role="constant"/><literal>G_MODULE_BIND_MASK</literal></term>
239
<varlistentry id="G-MODULE-BIND-MASK--CAPS" role="constant">
240
<term><literal>G_MODULE_BIND_MASK</literal></term>
260
241
<listitem><simpara>mask for all flags.
262
242
</simpara></listitem>
264
244
</variablelist></refsect2>
266
<title><anchor id="g-module-symbol" role="function"/>g_module_symbol ()</title>
267
<indexterm><primary>g_module_symbol</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_module_symbol (<link linkend="GModule">GModule</link> *module,
245
<refsect2 id="g-module-symbol" role="function">
246
<title>g_module_symbol ()</title>
247
<indexterm zone="g-module-symbol"><primary sortas="g_module_symbol">g_module_symbol</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_module_symbol (<link linkend="GModule">GModule</link> *module,
268
248
const <link linkend="gchar">gchar</link> *symbol_name,
269
249
<link linkend="gpointer">gpointer</link> *symbol);</programlisting>
271
Gets a symbol pointer from a module, such as one exported by <link linkend="G-MODULE-EXPORT:CAPS"><type>G_MODULE_EXPORT</type></link>.
251
Gets a symbol pointer from a module, such as one exported by <link linkend="G-MODULE-EXPORT--CAPS"><type>G_MODULE_EXPORT</type></link>.
274
Note that a valid symbol can be <link linkend="NULL:CAPS"><literal>NULL</literal></link>.
254
Note that a valid symbol can be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.
275
255
</para><variablelist role="params">
276
<varlistentry><term><parameter>module</parameter> :</term>
256
<varlistentry><term><parameter>module</parameter> :</term>
277
257
<listitem><simpara>a <link linkend="GModule"><type>GModule</type></link>.
278
258
</simpara></listitem></varlistentry>
279
<varlistentry><term><parameter>symbol_name</parameter> :</term>
259
<varlistentry><term><parameter>symbol_name</parameter> :</term>
280
260
<listitem><simpara>the name of the symbol to find.
281
261
</simpara></listitem></varlistentry>
282
<varlistentry><term><parameter>symbol</parameter> :</term>
262
<varlistentry><term><parameter>symbol</parameter> :</term>
283
263
<listitem><simpara>returns the pointer to the symbol value.
284
264
</simpara></listitem></varlistentry>
285
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success.
265
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>%TRUE on success.
288
266
</simpara></listitem></varlistentry>
289
267
</variablelist></refsect2>
291
<title><anchor id="g-module-name" role="function"/>g_module_name ()</title>
292
<indexterm><primary>g_module_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_module_name (<link linkend="GModule">GModule</link> *module);</programlisting>
268
<refsect2 id="g-module-name" role="function">
269
<title>g_module_name ()</title>
270
<indexterm zone="g-module-name"><primary sortas="g_module_name">g_module_name</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_module_name (<link linkend="GModule">GModule</link> *module);</programlisting>
294
272
Gets the filename from a <link linkend="GModule"><type>GModule</type></link>.
295
273
</para><variablelist role="params">
296
<varlistentry><term><parameter>module</parameter> :</term>
274
<varlistentry><term><parameter>module</parameter> :</term>
297
275
<listitem><simpara>a <link linkend="GModule"><type>GModule</type></link>.
298
276
</simpara></listitem></varlistentry>
299
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the filename of the module, or "main" if the module is the main
277
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the filename of the module, or "main" if the module is the main
303
279
</simpara></listitem></varlistentry>
304
280
</variablelist></refsect2>
306
<title><anchor id="g-module-make-resident" role="function"/>g_module_make_resident ()</title>
307
<indexterm><primary>g_module_make_resident</primary></indexterm><programlisting><link linkend="void">void</link> g_module_make_resident (<link linkend="GModule">GModule</link> *module);</programlisting>
281
<refsect2 id="g-module-make-resident" role="function">
282
<title>g_module_make_resident ()</title>
283
<indexterm zone="g-module-make-resident"><primary sortas="g_module_make_resident">g_module_make_resident</primary></indexterm><programlisting><link linkend="void">void</link> g_module_make_resident (<link linkend="GModule">GModule</link> *module);</programlisting>
309
285
Ensures that a module will never be unloaded.
310
286
Any future <link linkend="g-module-close"><function>g_module_close()</function></link> calls on the module will be ignored.
311
287
</para><variablelist role="params">
312
<varlistentry><term><parameter>module</parameter> :</term>
288
<varlistentry><term><parameter>module</parameter> :</term>
313
289
<listitem><simpara>a <link linkend="GModule"><type>GModule</type></link> to make permanently resident.
316
290
</simpara></listitem></varlistentry>
317
291
</variablelist></refsect2>
319
<title><anchor id="g-module-close" role="function"/>g_module_close ()</title>
320
<indexterm><primary>g_module_close</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_module_close (<link linkend="GModule">GModule</link> *module);</programlisting>
292
<refsect2 id="g-module-close" role="function">
293
<title>g_module_close ()</title>
294
<indexterm zone="g-module-close"><primary sortas="g_module_close">g_module_close</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> g_module_close (<link linkend="GModule">GModule</link> *module);</programlisting>
323
297
</para><variablelist role="params">
324
<varlistentry><term><parameter>module</parameter> :</term>
298
<varlistentry><term><parameter>module</parameter> :</term>
325
299
<listitem><simpara>a <link linkend="GModule"><type>GModule</type></link> to close.
326
300
</simpara></listitem></varlistentry>
327
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> on success.
301
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>%TRUE on success.
330
302
</simpara></listitem></varlistentry>
331
303
</variablelist></refsect2>
333
<title><anchor id="g-module-error" role="function"/>g_module_error ()</title>
334
<indexterm><primary>g_module_error</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_module_error (void);</programlisting>
304
<refsect2 id="g-module-error" role="function">
305
<title>g_module_error ()</title>
306
<indexterm zone="g-module-error"><primary sortas="g_module_error">g_module_error</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* g_module_error (void);</programlisting>
336
308
Gets a string describing the last module error.
337
309
</para><variablelist role="params">
338
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a string describing the last module error.
310
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>a string describing the last module error.
341
311
</simpara></listitem></varlistentry>
342
312
</variablelist></refsect2>
344
<title><anchor id="GModuleCheckInit" role="function"/>GModuleCheckInit ()</title>
345
<indexterm><primary>GModuleCheckInit</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* (*GModuleCheckInit) (<link linkend="GModule">GModule</link> *module);</programlisting>
313
<refsect2 id="GModuleCheckInit" role="function">
314
<title>GModuleCheckInit ()</title>
315
<indexterm zone="GModuleCheckInit"><primary sortas="GModuleCheckInit">GModuleCheckInit</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link> * (*GModuleCheckInit) (<link linkend="GModule">GModule</link> *module);</programlisting>
347
317
Specifies the type of the module initialization function.
318
<indexterm zone="g-module-check-init"><primary>g_module_check_init</primary></indexterm>
348
319
If a module contains a function named <link linkend="g-module-check-init"><function>g_module_check_init()</function></link> it is called
349
320
automatically when the module is loaded. It is passed the <link linkend="GModule"><type>GModule</type></link> structure
350
and should return <link linkend="NULL:CAPS"><literal>NULL</literal></link> on success or a string describing the initialization
321
and should return <link linkend="NULL--CAPS"><literal>NULL</literal></link> on success or a string describing the initialization
352
323
</para><variablelist role="params">
353
<varlistentry><term><parameter>module</parameter> :</term>
324
<varlistentry><term><parameter>module</parameter> :</term>
354
325
<listitem><simpara>the <link linkend="GModule"><type>GModule</type></link> corresponding to the module which has just been loaded.
355
326
</simpara></listitem></varlistentry>
356
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara><link linkend="NULL:CAPS"><literal>NULL</literal></link> on success, or a string describing the initialization error.
327
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>%NULL on success, or a string describing the initialization error.
359
328
</simpara></listitem></varlistentry>
360
329
</variablelist></refsect2>
362
<title><anchor id="GModuleUnload" role="function"/>GModuleUnload ()</title>
363
<indexterm><primary>GModuleUnload</primary></indexterm><programlisting><link linkend="void">void</link> (*GModuleUnload) (<link linkend="GModule">GModule</link> *module);</programlisting>
330
<refsect2 id="GModuleUnload" role="function">
331
<title>GModuleUnload ()</title>
332
<indexterm zone="GModuleUnload"><primary sortas="GModuleUnload">GModuleUnload</primary></indexterm><programlisting><link linkend="void">void</link> (*GModuleUnload) (<link linkend="GModule">GModule</link> *module);</programlisting>
334
<indexterm zone="g-module-unload"><primary>g_module_unload</primary></indexterm>
365
335
Specifies the type of the module function called when it is unloaded.
366
336
If a module contains a function named <link linkend="g-module-unload"><function>g_module_unload()</function></link> it is called
367
337
automatically when the module is unloaded.
368
338
It is passed the <link linkend="GModule"><type>GModule</type></link> structure.
369
339
</para><variablelist role="params">
370
<varlistentry><term><parameter>module</parameter> :</term>
340
<varlistentry><term><parameter>module</parameter> :</term>
371
341
<listitem><simpara>the <link linkend="GModule"><type>GModule</type></link> about to be unloaded.
374
342
</simpara></listitem></varlistentry>
375
343
</variablelist></refsect2>
377
<title><anchor id="G-MODULE-SUFFIX:CAPS" role="macro"/>G_MODULE_SUFFIX</title>
378
<indexterm><primary>G_MODULE_SUFFIX</primary></indexterm><programlisting>#define G_MODULE_SUFFIX "so"
344
<refsect2 id="G-MODULE-SUFFIX--CAPS" role="macro">
345
<title>G_MODULE_SUFFIX</title>
346
<indexterm zone="G-MODULE-SUFFIX--CAPS"><primary sortas="G_MODULE_SUFFIX">G_MODULE_SUFFIX</primary></indexterm><programlisting>#define G_MODULE_SUFFIX "so"
379
347
</programlisting>
381
349
Expands to the proper shared library suffix for the current platform
382
350
without the leading dot. For the most Unices and Linux this is "so",
383
351
for some HP-UX versions this is "sl" and for Windows this is "dll".
384
352
</para></refsect2>
386
<title><anchor id="G-MODULE-EXPORT:CAPS" role="macro"/>G_MODULE_EXPORT</title>
387
<indexterm><primary>G_MODULE_EXPORT</primary></indexterm><programlisting>#define G_MODULE_EXPORT</programlisting>
353
<refsect2 id="G-MODULE-EXPORT--CAPS" role="macro">
354
<title>G_MODULE_EXPORT</title>
355
<indexterm zone="G-MODULE-EXPORT--CAPS"><primary sortas="G_MODULE_EXPORT">G_MODULE_EXPORT</primary></indexterm><programlisting>#define G_MODULE_EXPORT</programlisting>
389
357
Used to declare functions exported by modules. This is a no-op on Linux and
390
358
Unices, but when compiling for Windows, it marks a symbol to be exported from
391
359
the library or executable being built.
392
360
</para></refsect2>
394
<title><anchor id="G-MODULE-IMPORT:CAPS" role="macro"/>G_MODULE_IMPORT</title>
395
<indexterm><primary>G_MODULE_IMPORT</primary></indexterm><programlisting>#define G_MODULE_IMPORT extern
361
<refsect2 id="G-MODULE-IMPORT--CAPS" role="macro">
362
<title>G_MODULE_IMPORT</title>
363
<indexterm zone="G-MODULE-IMPORT--CAPS"><primary sortas="G_MODULE_IMPORT">G_MODULE_IMPORT</primary></indexterm><programlisting>#define G_MODULE_IMPORT extern
396
364
</programlisting>
398
366
Used to declare functions imported from modules.