source: trunk/samba/docs/htmldocs/Samba3-Developers-Guide/modules.html @ 17

Last change on this file since 17 was 1, checked in by Paul Smedley, 14 years ago

Initial code import

File size: 8.6 KB
Line 
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 8. Modules</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.68.1"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt02.html" title="Part II. Samba Basics"><link rel="prev" href="contributing.html" title="Chapter 7. Contributing code"><link rel="next" href="pt03.html" title="Part III. Samba Subsystems"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Modules</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="contributing.html">Prev</a> </td><th width="60%" align="center">Part II. Samba Basics</th><td width="20%" align="right"> <a accesskey="n" href="pt03.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="modules"></a>Chapter 8. Modules</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><code class="email">&lt;<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>&gt;</code></p></div></div></div></div><div><p class="pubdate"> 19 March 2003 </p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="modules.html#id294031">Advantages</a></span></dt><dt><span class="sect1"><a href="modules.html#id294066">Loading modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="modules.html#id294089">Static modules</a></span></dt><dt><span class="sect2"><a href="modules.html#id294118">Shared modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="modules.html#id294138">Writing modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="modules.html#id294181">Static/Shared selection in configure.in</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id294031"></a>Advantages</h2></div></div></div><p>
2The new modules system has the following advantages:
3</p><table class="simplelist" border="0" summary="Simple list"><tr><td>Transparent loading of static and shared modules (no need
4for a subsystem to know about modules)</td></tr><tr><td>Simple selection between shared and static modules at configure time</td></tr><tr><td>"preload modules" option for increasing performance for stable modules</td></tr><tr><td>No nasty #define stuff anymore</td></tr><tr><td>All backends are available as plugin now (including pdb_ldap and pdb_tdb)</td></tr></table></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id294066"></a>Loading modules</h2></div></div></div><p>
5Some subsystems in samba use different backends. These backends can be
6either statically linked in to samba or available as a plugin. A subsystem
7should have a function that allows a module to register itself. For example,
8the passdb subsystem has:
9</p><pre class="programlisting">
10NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function init);
11</pre><p>
12This function will be called by the initialisation function of the module to
13register itself.
14</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id294089"></a>Static modules</h3></div></div></div><p>
15The modules system compiles a list of initialisation functions for the
16static modules of each subsystem. This is a define. For example,
17it is here currently (from <code class="filename">include/config.h</code>):
18</p><pre class="programlisting">
19/* Static init functions */
20#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();}
21</pre><p>
22These functions should be called before the subsystem is used. That
23should be done when the subsystem is initialised or first used.
24</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id294118"></a>Shared modules</h3></div></div></div><p>
25If a subsystem needs a certain backend, it should check if it has
26already been registered. If the backend hasn't been registered already,
27the subsystem should call smb_probe_module(char *subsystem, char *backend).
28This function tries to load the correct module from a certain path
29($LIBDIR/subsystem/backend.so). If the first character in 'backend'
30is a slash, smb_probe_module() tries to load the module from the
31absolute path specified in 'backend'.
32</p><p>After smb_probe_module() has been executed, the subsystem
33should check again if the module has been registered.
34</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id294138"></a>Writing modules</h2></div></div></div><p>
35Each module has an initialisation function. For modules that are
36included with samba this name is '<em class="replaceable"><code>subsystem</code></em>_<em class="replaceable"><code>backend</code></em>_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()).
37The prototype for these functions is:
38</p><pre class="programlisting">
39NTSTATUS init_module(void);
40</pre><p>This function should call one or more
41registration functions. The function should return NT_STATUS_OK on success and 
42NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</p><p>For example, pdb_ldap_init() contains: </p><pre class="programlisting">
43NTSTATUS pdb_ldap_init(void)
44{
45smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam);
46smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua);
47        return NT_STATUS_OK;
48}
49</pre><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id294181"></a>Static/Shared selection in configure.in</h3></div></div></div><p>
50Some macros in configure.in generate the various defines and substs that
51are necessary for the system to work correct. All modules that should
52be built by default have to be added to the variable 'default_modules'.
53For example, if ldap is found, pdb_ldap is added to this variable.
54</p><p>
55On the bottom of configure.in, SMB_MODULE() should be called
56for each module and SMB_SUBSYSTEM() for each subsystem.
57</p><p>Syntax:</p><pre class="programlisting">
58SMB_MODULE(<em class="replaceable"><code>subsystem</code></em>_<em class="replaceable"><code>backend</code></em>, <em class="replaceable"><code>object files</code></em>, <em class="replaceable"><code>plugin name</code></em>, <em class="replaceable"><code>subsystem name</code></em>, <em class="replaceable"><code>static_action</code></em>, <em class="replaceable"><code>shared_action</code></em>)
59SMB_SUBSYSTEM(<em class="replaceable"><code>subsystem</code></em>,<em class="replaceable"><code>depfile</code></em>)
60</pre><p>The depfile for a certain subsystem is the file that calls the
61initialisation functions for the statically built in modules.</p><p>
62<em class="replaceable"><code>@SUBSYSTEM_MODULES@</code></em> in Makefile.in will
63be replaced with the names of the plugins to build.
64</p><p>You must make sure all .c files that contain defines that can
65be changed by ./configure are rebuilded in the 'modules_clean' make target.
66Practically, this means all c files that contain <span><strong class="command">static_init_subsystem;</strong></span> calls need to be rebuilded.
67</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
68There currently also is a configure.in command called SMB_MODULE_PROVIVES().
69This is used for modules that register multiple things. It should not
70be used as probing will most likely disappear in the future.</p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="contributing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="pt03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 7. Contributing code </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Part III. Samba Subsystems</td></tr></table></div></body></html>
Note: See TracBrowser for help on using the repository browser.