From 8f8a9f01909ba29e2b781310baeeaaddc3f15f0d Mon Sep 17 00:00:00 2001 From: "Gerald W. Carter" Date: Tue, 22 Apr 2008 10:09:40 -0500 Subject: Moving docs tree to docs-xml to make room for generated docs in the release tarball. (This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14) --- docs-xml/Samba3-Developers-Guide/modules.xml | 166 +++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 docs-xml/Samba3-Developers-Guide/modules.xml (limited to 'docs-xml/Samba3-Developers-Guide/modules.xml') diff --git a/docs-xml/Samba3-Developers-Guide/modules.xml b/docs-xml/Samba3-Developers-Guide/modules.xml new file mode 100644 index 0000000000..a74c176844 --- /dev/null +++ b/docs-xml/Samba3-Developers-Guide/modules.xml @@ -0,0 +1,166 @@ + + + + + + JelmerVernooij + + Samba Team +
jelmer@samba.org
+ + + 19 March 2003 + + +Modules + + +Advantages + + +The new modules system has the following advantages: + + + +Transparent loading of static and shared modules (no need +for a subsystem to know about modules) +Simple selection between shared and static modules at configure time +"preload modules" option for increasing performance for stable modules +No nasty #define stuff anymore +All backends are available as plugin now (including pdb_ldap and pdb_tdb) + + + + +Loading modules + + +Some subsystems in samba use different backends. These backends can be +either statically linked in to samba or available as a plugin. A subsystem +should have a function that allows a module to register itself. For example, +the passdb subsystem has: + + + +NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function init); + + + +This function will be called by the initialisation function of the module to +register itself. + + + +Static modules + + +The modules system compiles a list of initialisation functions for the +static modules of each subsystem. This is a define. For example, +it is here currently (from include/config.h): + + + +/* Static init functions */ +#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();} + + + +These functions should be called before the subsystem is used. That +should be done when the subsystem is initialised or first used. + + + + + +Shared modules + + +If a subsystem needs a certain backend, it should check if it has +already been registered. If the backend hasn't been registered already, +the subsystem should call smb_probe_module(char *subsystem, char *backend). +This function tries to load the correct module from a certain path +($LIBDIR/subsystem/backend.so). If the first character in 'backend' +is a slash, smb_probe_module() tries to load the module from the +absolute path specified in 'backend'. + + +After smb_probe_module() has been executed, the subsystem +should check again if the module has been registered. + + + + + + +Writing modules + + +Each module has an initialisation function. For modules that are +included with samba this name is 'subsystem_backend_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()). +The prototype for these functions is: + + + +NTSTATUS init_module(void); + + +This function should call one or more +registration functions. The function should return NT_STATUS_OK on success and +NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure. + +For example, pdb_ldap_init() contains: + + +NTSTATUS pdb_ldap_init(void) +{ +smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam); +smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua); + return NT_STATUS_OK; +} + + + +Static/Shared selection in configure.in + + +Some macros in configure.in generate the various defines and substs that +are necessary for the system to work correct. All modules that should +be built by default have to be added to the variable 'default_modules'. +For example, if ldap is found, pdb_ldap is added to this variable. + + + +On the bottom of configure.in, SMB_MODULE() should be called +for each module and SMB_SUBSYSTEM() for each subsystem. + + +Syntax: + + +SMB_MODULE(subsystem_backend, object files, plugin name, subsystem name, static_action, shared_action) +SMB_SUBSYSTEM(subsystem,depfile) + + +The depfile for a certain subsystem is the file that calls the +initialisation functions for the statically built in modules. + + +@SUBSYSTEM_MODULES@ in Makefile.in will +be replaced with the names of the plugins to build. + + +You must make sure all .c files that contain defines that can +be changed by ./configure are rebuilded in the 'modules_clean' make target. +Practically, this means all c files that contain static_init_subsystem; calls need to be rebuilded. + + + + +There currently also is a configure.in command called SMB_MODULE_PROVIVES(). +This is used for modules that register multiple things. It should not +be used as probing will most likely disappear in the future. + + + + + -- cgit