lib: modules: Change XXX_init interface from XXX_init(void) to XXX_init(TALLOC_CTX *)

[bbaumbach/samba-autobuild/.git] / 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
index a74c17684438166473c418149bd04245b59a30d2..f0d19f1b8e955cb29a95391403a2be9c1effdd66 100644 (file)
--- a/docs-xml/Samba3-Developers-Guide/modules.xml
+++ b/docs-xml/Samba3-Developers-Guide/modules.xml
@@ -101,7 +101,7 @@ The prototype for these functions is:
 </para>
 
 <para><programlisting>
-NTSTATUS init_module(void);
+NTSTATUS init_module(TALLOC_CTX *);
 </programlisting></para>
 
 <para>This function should call one or more 
@@ -111,7 +111,7 @@ NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</para>
 <para>For example, pdb_ldap_init() contains: </para>
 
 <para><programlisting>
-NTSTATUS pdb_ldap_init(void)
+NTSTATUS pdb_ldap_init(TALLOC_CTX *)
 {
 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam);
 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua);
@@ -119,6 +119,16 @@ smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nu
 }
 </programlisting></para>
 
+<para>
+The TALLOC_CTX pointer passed as a parameter must be a long-lived context,
+that will stay around for as long as the program that loads the module
+exists. It allows the caller to taloc_free any long lived data the
+module choses to place on this context on program exit (giving a cleaner
+valgrind trace). It should be used by modules in place of talloc_autofree_context(),
+use of which makes programs thread-unsafe. Modules that don't care about
+free on exist should use the NULL talloc context.
+</para>
+
 <sect2>
 <title>Static/Shared selection in configure.in</title>