| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>Dynamic Loading of Modules: GLib Reference Manual</title> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="GLib Reference Manual"> |
| <link rel="up" href="glib-core.html" title="GLib Core Application Support"> |
| <link rel="prev" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues"> |
| <link rel="next" href="glib-Memory-Allocation.html" title="Memory Allocation"> |
| <meta name="generator" content="GTK-Doc V1.25.1 (XML mode)"> |
| <link rel="stylesheet" href="style.css" type="text/css"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> |
| <td width="100%" align="left" class="shortcuts"> |
| <a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> |
| <a href="#glib-Dynamic-Loading-of-Modules.description" class="shortcut">Description</a></span> |
| </td> |
| <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> |
| <td><a accesskey="u" href="glib-core.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> |
| <td><a accesskey="p" href="glib-Asynchronous-Queues.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> |
| <td><a accesskey="n" href="glib-Memory-Allocation.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> |
| </tr></table> |
| <div class="refentry"> |
| <a name="glib-Dynamic-Loading-of-Modules"></a><div class="titlepage"></div> |
| <div class="refnamediv"><table width="100%"><tr> |
| <td valign="top"> |
| <h2><span class="refentrytitle"><a name="glib-Dynamic-Loading-of-Modules.top_of_page"></a>Dynamic Loading of Modules</span></h2> |
| <p>Dynamic Loading of Modules — portable method for dynamically loading 'plug-ins'</p> |
| </td> |
| <td class="gallery_image" valign="top" align="right"></td> |
| </tr></table></div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.functions"></a><h2>Functions</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="functions_return"> |
| <col class="functions_name"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-supported" title="g_module_supported ()">g_module_supported</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-build-path" title="g_module_build_path ()">g_module_build_path</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="returnvalue">GModule</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-open" title="g_module_open ()">g_module_open</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-symbol" title="g_module_symbol ()">g_module_symbol</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-name" title="g_module_name ()">g_module_name</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-make-resident" title="g_module_make_resident ()">g_module_make_resident</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-close" title="g_module_close ()">g_module_close</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-error" title="g_module_error ()">g_module_error</a> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| </td> |
| <td class="function_name"> |
| <span class="c_punctuation">(</span><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleCheckInit" title="GModuleCheckInit ()">*GModuleCheckInit</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| <tr> |
| <td class="function_type"> |
| <span class="returnvalue">void</span> |
| </td> |
| <td class="function_name"> |
| <span class="c_punctuation">(</span><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleUnload" title="GModuleUnload ()">*GModuleUnload</a><span class="c_punctuation">)</span> <span class="c_punctuation">()</span> |
| </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.other"></a><h2>Types and Values</h2> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="name"> |
| <col class="description"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="datatype_keyword"> </td> |
| <td class="function_name"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule">GModule</a></td> |
| </tr> |
| <tr> |
| <td class="datatype_keyword">enum</td> |
| <td class="function_name"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleFlags" title="enum GModuleFlags">GModuleFlags</a></td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-SUFFIX:CAPS" title="G_MODULE_SUFFIX">G_MODULE_SUFFIX</a></td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-EXPORT:CAPS" title="G_MODULE_EXPORT">G_MODULE_EXPORT</a></td> |
| </tr> |
| <tr> |
| <td class="define_keyword">#define</td> |
| <td class="function_name"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-IMPORT:CAPS" title="G_MODULE_IMPORT">G_MODULE_IMPORT</a></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.includes"></a><h2>Includes</h2> |
| <pre class="synopsis">#include <gmodule.h> |
| </pre> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.description"></a><h2>Description</h2> |
| <p>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 <code class="function">dlopen()</code> (e.g. Linux/Sun), as |
| well as Windows platforms via DLLs.</p> |
| <p>A program which wants to use these functions must be linked to the |
| libraries output by the command <code class="literal">pkg-config --libs gmodule-2.0</code>.</p> |
| <p>To use them you must first determine whether dynamic loading |
| is supported on the platform by calling <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-supported" title="g_module_supported ()"><code class="function">g_module_supported()</code></a>. |
| If it is, you can open a module with <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-open" title="g_module_open ()"><code class="function">g_module_open()</code></a>, |
| find the module's symbols (e.g. function names) with <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-symbol" title="g_module_symbol ()"><code class="function">g_module_symbol()</code></a>, |
| and later close the module with <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-close" title="g_module_close ()"><code class="function">g_module_close()</code></a>. |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-name" title="g_module_name ()"><code class="function">g_module_name()</code></a> will return the file name of a currently opened module.</p> |
| <p>If any of the above functions fail, the error status can be found with |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-error" title="g_module_error ()"><code class="function">g_module_error()</code></a>.</p> |
| <p>The <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> 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 <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleCheckInit" title="GModuleCheckInit ()"><span class="type">GModuleCheckInit</span></a> and <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleUnload" title="GModuleUnload ()"><span class="type">GModuleUnload</span></a>).</p> |
| <p>If your module introduces static data to common subsystems in the running |
| program, e.g. through calling |
| <code class="literal">g_quark_from_static_string ("my-module-stuff")</code>, |
| it must ensure that it is never unloaded, by calling <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-make-resident" title="g_module_make_resident ()"><code class="function">g_module_make_resident()</code></a>.</p> |
| <p>Example: Calling a function defined in a GModule</p> |
| <div class="informalexample"> |
| <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> |
| <tbody> |
| <tr> |
| <td class="listing_lines" align="right"><pre>1 |
| 2 |
| 3 |
| 4 |
| 5 |
| 6 |
| 7 |
| 8 |
| 9 |
| 10 |
| 11 |
| 12 |
| 13 |
| 14 |
| 15 |
| 16 |
| 17 |
| 18 |
| 19 |
| 20 |
| 21 |
| 22 |
| 23 |
| 24 |
| 25 |
| 26 |
| 27 |
| 28 |
| 29 |
| 30 |
| 31 |
| 32 |
| 33 |
| 34 |
| 35 |
| 36 |
| 37 |
| 38 |
| 39 |
| 40 |
| 41 |
| 42</pre></td> |
| <td class="listing_code"><pre class="programlisting"><span class="comment">// the function signature for 'say_hello'</span> |
| <span class="keyword">typedef</span><span class="normal"> </span><span class="type">void</span><span class="normal"> </span><span class="symbol">(*</span><span class="normal"> SayHelloFunc</span><span class="symbol">)</span><span class="normal"> </span><span class="symbol">(</span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">message</span><span class="symbol">);</span> |
| |
| <span class="normal"><a href="glib-Basic-Types.html#gboolean">gboolean</a></span> |
| <span class="function">just_say_hello</span><span class="normal"> </span><span class="symbol">(</span><span class="keyword">const</span><span class="normal"> </span><span class="type">char</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">filename</span><span class="symbol">,</span><span class="normal"> </span><span class="usertype">GError</span><span class="normal"> </span><span class="symbol">**</span><span class="normal">error</span><span class="symbol">)</span> |
| <span class="cbracket">{</span> |
| <span class="normal"> </span><span class="usertype">SayHelloFunc</span><span class="normal"> say_hello</span><span class="symbol">;</span> |
| <span class="normal"> </span><span class="usertype">GModule</span><span class="normal"> </span><span class="symbol">*</span><span class="normal">module</span><span class="symbol">;</span> |
| |
| <span class="normal"> module </span><span class="symbol">=</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-open">g_module_open</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">filename</span><span class="symbol">,</span><span class="normal"> <a href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-BIND-LAZY:CAPS">G_MODULE_BIND_LAZY</a></span><span class="symbol">);</span> |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="normal">module</span><span class="symbol">)</span> |
| <span class="normal"> </span><span class="cbracket">{</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Error-Reporting.html#g-set-error">g_set_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">error</span><span class="symbol">,</span><span class="normal"> FOO_ERROR</span><span class="symbol">,</span><span class="normal"> FOO_ERROR_BLAH</span><span class="symbol">,</span> |
| <span class="normal"> </span><span class="string">"%s"</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-error">g_module_error</a></span><span class="normal"> </span><span class="symbol">());</span> |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span> |
| <span class="normal"> </span><span class="cbracket">}</span> |
| |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-symbol">g_module_symbol</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">module</span><span class="symbol">,</span><span class="normal"> </span><span class="string">"say_hello"</span><span class="symbol">,</span><span class="normal"> </span><span class="symbol">(</span><span class="normal"><a href="glib-Basic-Types.html#gpointer">gpointer</a> </span><span class="symbol">*)&</span><span class="normal">say_hello</span><span class="symbol">))</span> |
| <span class="normal"> </span><span class="cbracket">{</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Error-Reporting.html#g-set-error">g_set_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">error</span><span class="symbol">,</span><span class="normal"> SAY_ERROR</span><span class="symbol">,</span><span class="normal"> SAY_ERROR_OPEN</span><span class="symbol">,</span> |
| <span class="normal"> </span><span class="string">"%s: %s"</span><span class="symbol">,</span><span class="normal"> filename</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-error">g_module_error</a></span><span class="normal"> </span><span class="symbol">());</span> |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-close">g_module_close</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">module</span><span class="symbol">))</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Message-Logging.html#g-warning">g_warning</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"%s: %s"</span><span class="symbol">,</span><span class="normal"> filename</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-error">g_module_error</a></span><span class="normal"> </span><span class="symbol">());</span> |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span> |
| <span class="normal"> </span><span class="cbracket">}</span> |
| |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(</span><span class="normal">say_hello </span><span class="symbol">==</span><span class="normal"> <a href="glib-Standard-Macros.html#NULL:CAPS">NULL</a></span><span class="symbol">)</span> |
| <span class="normal"> </span><span class="cbracket">{</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Error-Reporting.html#g-set-error">g_set_error</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">error</span><span class="symbol">,</span><span class="normal"> SAY_ERROR</span><span class="symbol">,</span><span class="normal"> SAY_ERROR_OPEN</span><span class="symbol">,</span> |
| <span class="normal"> </span><span class="string">"symbol say_hello is NULL"</span><span class="symbol">);</span> |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-close">g_module_close</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">module</span><span class="symbol">))</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Message-Logging.html#g-warning">g_warning</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"%s: %s"</span><span class="symbol">,</span><span class="normal"> filename</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-error">g_module_error</a></span><span class="normal"> </span><span class="symbol">());</span> |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#FALSE:CAPS">FALSE</a></span><span class="symbol">;</span> |
| <span class="normal"> </span><span class="cbracket">}</span> |
| |
| <span class="normal"> </span><span class="comment">// call our function in the module</span> |
| <span class="normal"> </span><span class="function">say_hello</span><span class="normal"> </span><span class="symbol">(</span><span class="string">"Hello world!"</span><span class="symbol">);</span> |
| |
| <span class="normal"> </span><span class="keyword">if</span><span class="normal"> </span><span class="symbol">(!</span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-close">g_module_close</a></span><span class="normal"> </span><span class="symbol">(</span><span class="normal">module</span><span class="symbol">))</span> |
| <span class="normal"> </span><span class="function"><a href="glib-Message-Logging.html#g-warning">g_warning</a></span><span class="normal"> </span><span class="symbol">(</span><span class="string">"%s: %s"</span><span class="symbol">,</span><span class="normal"> filename</span><span class="symbol">,</span><span class="normal"> </span><span class="function"><a href="glib-Dynamic-Loading-of-Modules.html#g-module-error">g_module_error</a></span><span class="normal"> </span><span class="symbol">());</span> |
| <span class="normal"> </span><span class="keyword">return</span><span class="normal"> <a href="glib-Standard-Macros.html#TRUE:CAPS">TRUE</a></span><span class="symbol">;</span> |
| <span class="normal"> </span><span class="cbracket">}</span></pre></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| |
| <p></p> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.functions_details"></a><h2>Functions</h2> |
| <div class="refsect2"> |
| <a name="g-module-supported"></a><h3>g_module_supported ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| g_module_supported (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <p>Checks if modules are supported on the current platform.</p> |
| <div class="refsect3"> |
| <a name="g-module-supported.returns"></a><h4>Returns</h4> |
| <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> if modules are supported</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-build-path"></a><h3>g_module_build_path ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| g_module_build_path (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *directory</code></em>, |
| <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *module_name</code></em>);</pre> |
| <p>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.</p> |
| <p>The directory should specify the directory where the module can be found. |
| It can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> 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.</p> |
| <p>For example, calling <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-build-path" title="g_module_build_path ()"><code class="function">g_module_build_path()</code></a> on a Linux system with a |
| <em class="parameter"><code>directory</code></em> |
| of <code class="literal">/lib</code> and a <em class="parameter"><code>module_name</code></em> |
| of "mylibrary" will return |
| <code class="literal">/lib/libmylibrary.so</code>. On a Windows system, using <code class="literal">\Windows</code> as the |
| directory it will return <code class="literal">\Windows\mylibrary.dll</code>.</p> |
| <div class="refsect3"> |
| <a name="g-module-build-path.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>directory</p></td> |
| <td class="parameter_description"><p> the directory where the module is. This can be |
| <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> or the empty string to indicate that the standard platform-specific |
| directories will be used, though that is not recommended. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>module_name</p></td> |
| <td class="parameter_description"><p>the name of the module</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-module-build-path.returns"></a><h4>Returns</h4> |
| <p> the complete path of the module, including the standard library |
| prefix and suffix. This should be freed when no longer needed</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-open"></a><h3>g_module_open ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="returnvalue">GModule</span></a> * |
| g_module_open (<em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *file_name</code></em>, |
| <em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleFlags" title="enum GModuleFlags"><span class="type">GModuleFlags</span></a> flags</code></em>);</pre> |
| <p>Opens a module. If the module has already been opened, |
| its reference count is incremented.</p> |
| <p>First of all <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-open" title="g_module_open ()"><code class="function">g_module_open()</code></a> tries to open <em class="parameter"><code>file_name</code></em> |
| as a module. |
| If that fails and <em class="parameter"><code>file_name</code></em> |
| 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 |
| (<a class="link" href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-SUFFIX:CAPS" title="G_MODULE_SUFFIX"><span class="type">G_MODULE_SUFFIX</span></a>), this suffix will be appended and the corresponding |
| module will be opended. If that fails and <em class="parameter"><code>file_name</code></em> |
| doesn't have the |
| ".la"-suffix, this suffix is appended and <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-open" title="g_module_open ()"><code class="function">g_module_open()</code></a> tries to open |
| the corresponding module. If eventually that fails as well, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is |
| returned.</p> |
| <div class="refsect3"> |
| <a name="g-module-open.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>file_name</p></td> |
| <td class="parameter_description"><p> the name of the file containing the module, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> |
| to obtain a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> representing the main program itself. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="NULL is OK, both for passing and for returning."><span class="acronym">allow-none</span></acronym>]</span></td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>flags</p></td> |
| <td class="parameter_description"><p>the flags used for opening the module. This can be the |
| logical OR of any of the <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModuleFlags" title="enum GModuleFlags"><span class="type">GModuleFlags</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-module-open.returns"></a><h4>Returns</h4> |
| <p> a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> on success, or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on failure</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-symbol"></a><h3>g_module_symbol ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| g_module_symbol (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>, |
| <em class="parameter"><code>const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="type">gchar</span></a> *symbol_name</code></em>, |
| <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> *symbol</code></em>);</pre> |
| <p>Gets a symbol pointer from a module, such as one exported |
| by <a class="link" href="glib-Dynamic-Loading-of-Modules.html#G-MODULE-EXPORT:CAPS" title="G_MODULE_EXPORT"><span class="type">G_MODULE_EXPORT</span></a>. Note that a valid symbol can be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.</p> |
| <div class="refsect3"> |
| <a name="g-module-symbol.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>symbol_name</p></td> |
| <td class="parameter_description"><p>the name of the symbol to find</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="parameter_name"><p>symbol</p></td> |
| <td class="parameter_description"><p> returns the pointer to the symbol value. </p></td> |
| <td class="parameter_annotations"><span class="annotation">[<acronym title="Parameter for returning results. Default is transfer full."><span class="acronym">out</span></acronym>]</span></td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-module-symbol.returns"></a><h4>Returns</h4> |
| <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-name"></a><h3>g_module_name ()</h3> |
| <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| g_module_name (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>);</pre> |
| <p>Returns the filename that the module was opened with.</p> |
| <p>If <em class="parameter"><code>module</code></em> |
| refers to the application itself, "main" is returned.</p> |
| <div class="refsect3"> |
| <a name="g-module-name.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a></p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-module-name.returns"></a><h4>Returns</h4> |
| <p> the filename of the module. </p> |
| <p><span class="annotation">[<acronym title="Don't free data after the code is done."><span class="acronym">transfer none</span></acronym>]</span></p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-make-resident"></a><h3>g_module_make_resident ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| g_module_make_resident (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>);</pre> |
| <p>Ensures that a module will never be unloaded. |
| Any future <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-close" title="g_module_close ()"><code class="function">g_module_close()</code></a> calls on the module will be ignored.</p> |
| <div class="refsect3"> |
| <a name="g-module-make-resident.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> to make permanently resident</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-close"></a><h3>g_module_close ()</h3> |
| <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean" title="gboolean"><span class="returnvalue">gboolean</span></a> |
| g_module_close (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>);</pre> |
| <p>Closes a module.</p> |
| <div class="refsect3"> |
| <a name="g-module-close.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>a <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> to close</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="g-module-close.returns"></a><h4>Returns</h4> |
| <p> <a class="link" href="glib-Standard-Macros.html#TRUE:CAPS" title="TRUE"><code class="literal">TRUE</code></a> on success</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="g-module-error"></a><h3>g_module_error ()</h3> |
| <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| g_module_error (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> |
| <p>Gets a string describing the last module error.</p> |
| <div class="refsect3"> |
| <a name="g-module-error.returns"></a><h4>Returns</h4> |
| <p> a string describing the last module error</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GModuleCheckInit"></a><h3>GModuleCheckInit ()</h3> |
| <pre class="programlisting">const <a class="link" href="glib-Basic-Types.html#gchar" title="gchar"><span class="returnvalue">gchar</span></a> * |
| <span class="c_punctuation">(</span>*GModuleCheckInit<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>);</pre> |
| <p>Specifies the type of the module initialization function. |
| If a module contains a function named <code class="function">g_module_check_init()</code> it is called |
| automatically when the module is loaded. It is passed the <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> structure |
| and should return <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on success or a string describing the initialization |
| error.</p> |
| <div class="refsect3"> |
| <a name="GModuleCheckInit.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> corresponding to the module which has just been loaded</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| <div class="refsect3"> |
| <a name="GModuleCheckInit.returns"></a><h4>Returns</h4> |
| <p> <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> on success, or a string describing the initialization error</p> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GModuleUnload"></a><h3>GModuleUnload ()</h3> |
| <pre class="programlisting"><span class="returnvalue">void</span> |
| <span class="c_punctuation">(</span>*GModuleUnload<span class="c_punctuation">)</span> (<em class="parameter"><code><a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> *module</code></em>);</pre> |
| <p>Specifies the type of the module function called when it is unloaded. |
| If a module contains a function named <code class="function">g_module_unload()</code> it is called |
| automatically when the module is unloaded. |
| It is passed the <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> structure.</p> |
| <div class="refsect3"> |
| <a name="GModuleUnload.parameters"></a><h4>Parameters</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="150px" class="parameters_name"> |
| <col class="parameters_description"> |
| <col width="200px" class="parameters_annotations"> |
| </colgroup> |
| <tbody><tr> |
| <td class="parameter_name"><p>module</p></td> |
| <td class="parameter_description"><p>the <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> about to be unloaded</p></td> |
| <td class="parameter_annotations"> </td> |
| </tr></tbody> |
| </table></div> |
| </div> |
| </div> |
| </div> |
| <div class="refsect1"> |
| <a name="glib-Dynamic-Loading-of-Modules.other_details"></a><h2>Types and Values</h2> |
| <div class="refsect2"> |
| <a name="GModule"></a><h3>GModule</h3> |
| <pre class="programlisting">typedef struct _GModule GModule;</pre> |
| <p>The <a class="link" href="glib-Dynamic-Loading-of-Modules.html#GModule" title="GModule"><span class="type">GModule</span></a> struct is an opaque data structure to represent a |
| <a class="link" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules">dynamically-loaded module</a>. |
| It should only be accessed via the following functions.</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="GModuleFlags"></a><h3>enum GModuleFlags</h3> |
| <p>Flags passed to <a class="link" href="glib-Dynamic-Loading-of-Modules.html#g-module-open" title="g_module_open ()"><code class="function">g_module_open()</code></a>. |
| Note that these flags are not supported on all platforms.</p> |
| <div class="refsect3"> |
| <a name="GModuleFlags.members"></a><h4>Members</h4> |
| <div class="informaltable"><table class="informaltable" width="100%" border="0"> |
| <colgroup> |
| <col width="300px" class="enum_members_name"> |
| <col class="enum_members_description"> |
| <col width="200px" class="enum_members_annotations"> |
| </colgroup> |
| <tbody> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-MODULE-BIND-LAZY:CAPS"></a>G_MODULE_BIND_LAZY</p></td> |
| <td class="enum_member_description"> |
| <p>specifies that symbols are only resolved when |
| needed. The default action is to bind all symbols when the module |
| is loaded.</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-MODULE-BIND-LOCAL:CAPS"></a>G_MODULE_BIND_LOCAL</p></td> |
| <td class="enum_member_description"> |
| <p>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.</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| <tr> |
| <td class="enum_member_name"><p><a name="G-MODULE-BIND-MASK:CAPS"></a>G_MODULE_BIND_MASK</p></td> |
| <td class="enum_member_description"> |
| <p>mask for all flags.</p> |
| </td> |
| <td class="enum_member_annotations"> </td> |
| </tr> |
| </tbody> |
| </table></div> |
| </div> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="G-MODULE-SUFFIX:CAPS"></a><h3>G_MODULE_SUFFIX</h3> |
| <pre class="programlisting">#define G_MODULE_SUFFIX "so" |
| </pre> |
| <p>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".</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="G-MODULE-EXPORT:CAPS"></a><h3>G_MODULE_EXPORT</h3> |
| <pre class="programlisting"># define G_MODULE_EXPORT __declspec(dllexport) |
| </pre> |
| <p>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.</p> |
| </div> |
| <hr> |
| <div class="refsect2"> |
| <a name="G-MODULE-IMPORT:CAPS"></a><h3>G_MODULE_IMPORT</h3> |
| <pre class="programlisting">#define G_MODULE_IMPORT extern |
| </pre> |
| <p>Used to declare functions imported from modules.</p> |
| </div> |
| </div> |
| </div> |
| <div class="footer"> |
| <hr>Generated by GTK-Doc V1.25.1</div> |
| </body> |
| </html> |