First version of VFS API developers documentation. Needs work on both formatting...
authorAlexander Bokovoy <ab@samba.org>
Wed, 4 Jun 2003 13:06:37 +0000 (13:06 +0000)
committerAlexander Bokovoy <ab@samba.org>
Wed, 4 Jun 2003 13:06:37 +0000 (13:06 +0000)
(This used to be commit 768e42bf40cccf24afe61ed6ae4601502dd89e74)

docs/docbook/devdoc/dev-doc.xml
docs/docbook/devdoc/vfs.xml [new file with mode: 0644]

index e272f2eb42b18ec10d73e20a57efe391623aaf2b..d4feff1aa56a60df798cc197e3f9af27a1f4edf2 100644 (file)
@@ -18,6 +18,7 @@
 <!ENTITY modules SYSTEM "modules.xml">
 <!ENTITY packagers SYSTEM "packagers.xml">
 <!ENTITY contributing SYSTEM "contributing.xml">
+<!ENTITY vfs SYSTEM "vfs.xml">
 ]>
 
 <book id="Samba-Developers-Guide">
@@ -77,6 +78,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
 &encryption;
 &modules;
 &rpc-plugin;
+&vfs;
 &packagers;
 &contributing;
 
diff --git a/docs/docbook/devdoc/vfs.xml b/docs/docbook/devdoc/vfs.xml
new file mode 100644 (file)
index 0000000..491e98d
--- /dev/null
@@ -0,0 +1,792 @@
+<chapter id="vfs">
+<chapterinfo>
+       <author>
+               <firstname>Alexander</firstname><surname>Bokovoy</surname>
+               <affiliation>
+                       <address><email>ab@samba.org</email></address>
+               </affiliation>
+       </author>
+       <author>
+               <firstname>Stefan</firstname><surname>Metzmacher</surname>
+               <affiliation>
+                       <address><email>metze@metzemix.de</email></address>
+               </affiliation>
+       </author>
+       <pubdate> 27 May 2003 </pubdate>
+</chapterinfo>
+
+<title>VFS Modules</title>
+
+<sect1>
+<title>The Samba (Posix) VFS layer</title>
+
+<sect2>
+<title>The general interface</title>
+
+<para>
+Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the
+struct vfs_ops and tree macros to make it easier to call the operations.
+(Take a look at <filename>include/vfs.h</filename> and <filename>include/vfs_macros.h</filename>.)
+</para>
+
+<para><programlisting>
+typedef enum _vfs_op_type {
+       SMB_VFS_OP_NOOP = -1,
+
+       ...
+
+       /* File operations */
+
+       SMB_VFS_OP_OPEN,
+       SMB_VFS_OP_CLOSE,
+       SMB_VFS_OP_READ,
+       SMB_VFS_OP_WRITE,
+       SMB_VFS_OP_LSEEK,
+       SMB_VFS_OP_SENDFILE,
+
+       ...
+
+       SMB_VFS_OP_LAST
+} vfs_op_type;
+</programlisting></para>
+
+<para>This struct contains the function and handle pointers for all operations.<programlisting>
+struct vfs_ops {
+       struct vfs_fn_pointers {
+               ...
+               
+               /* File operations */
+               
+               int (*open)(struct vfs_handle_struct *handle,
+                       struct connection_struct *conn,
+                       const char *fname, int flags, mode_t mode);
+               int (*close)(struct vfs_handle_struct *handle,
+                       struct files_struct *fsp, int fd);
+               ssize_t (*read)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, void *data, size_t n);
+               ssize_t (*write)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, 
+                       const void *data, size_t n);
+               SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle, 
+                       struct files_struct *fsp, int fd, 
+                       SMB_OFF_T offset, int whence);
+               ssize_t (*sendfile)(struct vfs_handle_struct *handle, 
+                       int tofd, files_struct *fsp, int fromfd, 
+                       const DATA_BLOB *header, SMB_OFF_T offset, size_t count);
+
+               ...
+       } ops;
+       
+       struct vfs_handles_pointers {
+               ...
+               
+               /* File operations */
+               
+               struct vfs_handle_struct *open;
+               struct vfs_handle_struct *close;
+               struct vfs_handle_struct *read;
+               struct vfs_handle_struct *write;
+               struct vfs_handle_struct *lseek;
+               struct vfs_handle_struct *sendfile;
+               
+               ...
+       } handles;
+};
+</programlisting></para>
+
+<para>
+This macros SHOULD be used to call any vfs operation.
+DO NOT ACCESS conn-&gt;vfs.ops.* directly !!!
+<programlisting>
+...
+       
+/* File operations */
+#define SMB_VFS_OPEN(conn, fname, flags, mode) \
+       ((conn)-&gt;vfs.ops.open((conn)-&gt;vfs.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_CLOSE(fsp, fd) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.close(\
+       (fsp)-&gt;conn-&gt;vfs.handles.close, (fsp), (fd)))
+#define SMB_VFS_READ(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.read(\
+       (fsp)-&gt;conn-&gt;vfs.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_WRITE(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.write(\
+       (fsp)-&gt;conn-&gt;vfs.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.lseek(\
+       (fsp)-&gt;conn-&gt;vfs.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
+       ((fsp)-&gt;conn-&gt;vfs.ops.sendfile(\
+       (fsp)-&gt;conn-&gt;vfs.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+
+...
+</programlisting></para>
+
+</sect2>
+
+<sect2>
+<title>Possible VFS operation layers</title>
+
+<para>
+These values are used by the VFS subsystem when building the conn-&gt;vfs 
+and conn-&gt;vfs_opaque structs for a connection with multiple VFS modules. 
+Internally, Samba differentiates only opaque and transparent layers at this process.
+Other types are used for providing better diagnosing facilities.
+</para>
+
+<para>
+Most modules will provide transparent layers. Opaque layer is for modules
+which implement actual file system calls (like DB-based VFS). For example,
+default POSIX VFS which is built in into Samba is an opaque VFS module.
+</para>
+
+<para>    
+Other layer types (logger, splitter, scanner) were designed to provide different 
+degree of transparency and for diagnosing VFS module behaviour.
+</para>
+
+<para>
+Each module can implement several layers at the same time provided that only
+one layer is used per each operation.
+</para>
+
+<para><programlisting>
+typedef enum _vfs_op_layer {
+       SMB_VFS_LAYER_NOOP = -1,        /* - For using in VFS module to indicate end of array */
+                                       /*   of operations description */
+       SMB_VFS_LAYER_OPAQUE = 0,       /* - Final level, does not call anything beyond itself */
+       SMB_VFS_LAYER_TRANSPARENT,      /* - Normal operation, calls underlying layer after */
+                                       /*   possibly changing passed data */
+       SMB_VFS_LAYER_LOGGER,           /* - Logs data, calls underlying layer, logging may not */
+                                       /*   use Samba VFS */
+       SMB_VFS_LAYER_SPLITTER,         /* - Splits operation, calls underlying layer _and_ own facility, */
+                                       /*   then combines result */
+       SMB_VFS_LAYER_SCANNER           /* - Checks data and possibly initiates additional */
+                                       /*   file activity like logging to files _inside_ samba VFS */
+} vfs_op_layer;
+</programlisting></para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>The Interaction between the Samba VFS subsystem and the modules</title>
+
+<sect2>
+<title>Initialization and registration</title>
+
+<para>
+As each Samba module a VFS module should have a 
+<programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or
+<programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module.
+</para>
+
+<para>
+This should be the only non static function inside the module.
+Global variables should also be static!
+</para>
+
+<para>
+The module should register its functions via the
+<programlisting>
+NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
+</programlisting> function.
+</para>
+
+<variablelist>
+
+<varlistentry><term>version</term>
+<listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
+</varlistentry>
+
+<varlistentry><term>name</term>
+<listitem><para>this is the name witch can be listed in the 
+<command>vfs objects</command> parameter to use this module.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>vfs_op_tuples</term>
+<listitem><para>
+this is an array of vfs_op_tuple's.
+(vfs_op_tuples is descripted in details below.)
+</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>
+For each operation the module wants to provide it has a entry in the 
+vfs_op_tuple array.
+</para>
+
+<programlisting>
+typedef struct _vfs_op_tuple {
+       void* op;
+       vfs_op_type type;
+       vfs_op_layer layer;
+} vfs_op_tuple;
+</programlisting>
+
+<variablelist>
+
+<varlistentry><term>op</term>
+<listitem><para>the function pointer to the specified function.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>type</term>
+<listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>layer</term>
+<listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>A simple example:</para>
+
+<programlisting>
+static vfs_op_tuple example_op_tuples[] = {    
+       {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
+
+       {SMB_VFS_OP(example_rename),    SMB_VFS_OP_RENAME,      SMB_VFS_LAYER_OPAQUE},
+
+       /* This indicates the end of the array */
+       {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
+};
+
+NTSTATUS init_module(void)
+{
+       return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, &quot;example&quot;, example_op_tuples);
+}
+</programlisting>
+
+</sect2>
+
+<sect2>
+<title>How the Modules handle per connection data</title>
+
+<para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
+</para>
+
+<programlisting>
+typedef struct vfs_handle_struct {
+       struct vfs_handle_struct  *next, *prev;
+       const char *param;
+       struct vfs_ops vfs_next;
+       struct connection_struct *conn;
+       void *data;
+       void (*free_data)(void **data);
+} vfs_handle_struct;
+</programlisting>
+
+<variablelist>
+
+<varlistentry><term>param</term>
+<listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para>
+<para>e.g. for 'vfs objects = example:test' param would be &quot;test&quot;.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>vfs_next</term>
+<listitem><para>This vfs_ops struct contains the information for calling the next module operations.
+Use the vfs_next_* macros to call a next module operations and
+don't access handle-&gt;vfs_next.ops.* directly!</para></listitem>
+</varlistentry>
+
+<varlistentry><term>conn</term>
+<listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>data</term>
+<listitem><para>This is a pointer for holding module private data.
+You can alloc data with connection life time on the handle-&gt;conn-&gt;mem_ctx TALLOC_CTX.
+But you can also manage the memory allocation yourself.</para></listitem>
+</varlistentry>
+
+<varlistentry><term>free_data</term>
+<listitem><para>This is a function pointer to a function that free's the module private data.
+If you talloc your private data on the TALLOC_CTX handle-&gt;conn-&gt;mem_ctx,
+you can set this function pointer to NULL.</para></listitem>
+</varlistentry>
+
+</variablelist>
+
+<para>Some usefull MACROS for handle private data.
+</para>
+
+<programlisting>
+#define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
+       if (!(handle)||((datap=(type *)(handle)-&gt;data)==NULL)) { \
+               DEBUG(0,(&quot;%s() failed to get vfs_handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
+               ret; \
+       } \
+}
+
+#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
+       if (!(handle)) { \
+               DEBUG(0,(&quot;%s() failed to set handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
+               ret; \
+       } else { \
+               if ((handle)-&gt;free_data) { \
+                       (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
+               } \
+               (handle)-&gt;data = (void *)datap; \
+               (handle)-&gt;free_data = free_fn; \
+       } \
+}
+
+#define SMB_VFS_HANDLE_FREE_DATA(handle) { \
+       if ((handle) &amp;&amp; (handle)-&gt;free_data) { \
+               (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
+       } \
+}
+</programlisting>
+
+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
+
+<para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
+</para>
+
+<programlisting>
+...
+/* File operations */
+#define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
+       ((conn)-&gt;vfs_opaque.ops.open(\
+       (conn)-&gt;vfs_opaque.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.close(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.close,\
+        (fsp), (fd)))
+#define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.read(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.write(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.lseek(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
+       ((fsp)-&gt;conn-&gt;vfs_opaque.ops.sendfile(\
+       (fsp)-&gt;conn-&gt;vfs_opaque.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+...
+</programlisting>
+
+<para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
+
+<para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
+</para>
+
+<programlisting>
+...
+/* File operations */
+#define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
+       ((handle)-&gt;vfs_next.ops.open(\
+       (handle)-&gt;vfs_next.handles.open,\
+        (conn), (fname), (flags), (mode)))
+#define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
+       ((handle)-&gt;vfs_next.ops.close(\
+       (handle)-&gt;vfs_next.handles.close,\
+        (fsp), (fd)))
+#define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
+       ((handle)-&gt;vfs_next.ops.read(\
+       (handle)-&gt;vfs_next.handles.read,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
+       ((handle)-&gt;vfs_next.ops.write(\
+       (handle)-&gt;vfs_next.handles.write,\
+        (fsp), (fd), (data), (n)))
+#define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
+       ((handle)-&gt;vfs_next.ops.lseek(\
+       (handle)-&gt;vfs_next.handles.lseek,\
+        (fsp), (fd), (offset), (whence)))
+#define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
+       ((handle)-&gt;vfs_next.ops.sendfile(\
+       (handle)-&gt;vfs_next.handles.sendfile,\
+        (tofd), (fsp), (fromfd), (header), (offset), (count)))
+...
+</programlisting>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Upgrading to the New VFS Interface</title>
+
+<sect2>
+<title>Upgrading from 2.2.* and 3.0aplha modules</title>
+
+<orderedlist>
+<listitem><para>
+Add &quot;vfs_handle_struct *handle, &quot; as first parameter to all vfs operation functions.
+e.g. example_connect(connection_struct *conn, const char *service, const char *user);
+-&gt;   example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
+</para></listitem>
+
+<listitem><para>
+Replace &quot;default_vfs_ops.&quot; with &quot;smb_vfs_next_&quot;.
+e.g. default_vfs_ops.connect(conn, service, user);
+-&gt;   smb_vfs_next_connect(conn, service, user);
+</para>
+
+<listitem><para>
+Uppercase all &quot;vfs_next_*&quot; functions.
+e.g. smb_vfs_next_connect(conn, service, user);
+-&gt;   SMB_VFS_NEXT_CONNECT(conn, service, user);
+</para></listitem>
+
+<listitem><para>
+Add &quot;handle, &quot; as first parameter to all VFS_NEXT_*() calls.
+e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
+-&gt;   SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
+</para></listitem>
+
+<listitem><para>
+(Only for 2.2.* modules) 
+Convert the old struct vfs_ops example_ops to 
+a vfs_op_tuple example_op_tuples[] array.
+e.g.
+<programlisting>
+struct vfs_ops example_ops = {
+       /* Disk operations */
+       example_connect,                /* connect */
+       example_disconnect,             /* disconnect */
+       NULL,                           /* disk free *
+       /* Directory operations */
+       NULL,                           /* opendir */
+       NULL,                           /* readdir */
+       NULL,                           /* mkdir */
+       NULL,                           /* rmdir */
+       NULL,                           /* closedir */
+       /* File operations */
+       NULL,                           /* open */
+       NULL,                           /* close */
+       NULL,                           /* read  */
+       NULL,                           /* write */
+       NULL,                           /* lseek */
+       NULL,                           /* sendfile */
+       NULL,                           /* rename */
+       NULL,                           /* fsync */
+       example_stat,                   /* stat  */
+       example_fstat,                  /* fstat */
+       example_lstat,                  /* lstat */
+       NULL,                           /* unlink */
+       NULL,                           /* chmod */
+       NULL,                           /* fchmod */
+       NULL,                           /* chown */
+       NULL,                           /* fchown */
+       NULL,                           /* chdir */
+       NULL,                           /* getwd */
+       NULL,                           /* utime */
+       NULL,                           /* ftruncate */
+       NULL,                           /* lock */
+       NULL,                           /* symlink */
+       NULL,                           /* readlink */
+       NULL,                           /* link */
+       NULL,                           /* mknod */
+       NULL,                           /* realpath */
+       NULL,                           /* fget_nt_acl */
+       NULL,                           /* get_nt_acl */
+       NULL,                           /* fset_nt_acl */
+       NULL,                           /* set_nt_acl */
+
+       NULL,                           /* chmod_acl */
+       NULL,                           /* fchmod_acl */
+
+       NULL,                           /* sys_acl_get_entry */
+       NULL,                           /* sys_acl_get_tag_type */
+       NULL,                           /* sys_acl_get_permset */
+       NULL,                           /* sys_acl_get_qualifier */
+       NULL,                           /* sys_acl_get_file */
+       NULL,                           /* sys_acl_get_fd */
+       NULL,                           /* sys_acl_clear_perms */
+       NULL,                           /* sys_acl_add_perm */
+       NULL,                           /* sys_acl_to_text */
+       NULL,                           /* sys_acl_init */
+       NULL,                           /* sys_acl_create_entry */
+       NULL,                           /* sys_acl_set_tag_type */
+       NULL,                           /* sys_acl_set_qualifier */
+       NULL,                           /* sys_acl_set_permset */
+       NULL,                           /* sys_acl_valid */
+       NULL,                           /* sys_acl_set_file */
+       NULL,                           /* sys_acl_set_fd */
+       NULL,                           /* sys_acl_delete_def_file */
+       NULL,                           /* sys_acl_get_perm */
+       NULL,                           /* sys_acl_free_text */
+       NULL,                           /* sys_acl_free_acl */
+       NULL                            /* sys_acl_free_qualifier */
+};
+</programlisting>
+-&gt;
+<programlisting> 
+static vfs_op_tuple example_op_tuples[] = {
+       {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
+       
+       {SMB_VFS_OP(example_fstat),     SMB_VFS_OP_FSTAT,       SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_stat),              SMB_VFS_OP_STAT,        SMB_VFS_LAYER_TRANSPARENT},
+       {SMB_VFS_OP(example_lstat),     SMB_VFS_OP_LSTAT,       SMB_VFS_LAYER_TRANSPARENT},
+
+       {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
+};
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+Move the example_op_tuples[] array to the end of the file. 
+</para></listitem>
+
+<listitem><para>
+Add the init_module() function at the end of the file.
+e.g.
+<programlisting>
+NTSTATUS init_module(void)
+{
+       return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,&quot;example&quot;,example_op_tuples);
+}
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+Check if your vfs_init() function does more then just prepare the vfs_ops structs or
+remember the struct smb_vfs_handle_struct.
+- If NOT you can remove the vfs_init() function.
+- If YES decide if you want to move the code to the example_connect() operation or to the init_module().
+  And then remove vfs_init().
+  e.g. 
+  - a debug class registration should go into init_module().
+  - the allocation of private data should go to example_connect().
+</para></listitem>
+
+<listitem><para>
+(Only for 3.0aplha* modules) 
+Check if your vfs_done() function contains needed code.
+- If NOT you can remove the vfs_done() function.
+- If YES decide if you can move the code to the example_disconnect() operation.
+  Otherwise register a SMB_EXIT_EVENT with smb_register_exit_event();
+  (Described in the MODULES section of the Samba-Developer-HOWTO.)
+  And then remove vfs_done(). 
+  e.g. the freeing of private data should go to example_disconnect().
+</para></listitem>
+
+<listitem><para>
+Check if you have any global variables left.
+- Decide if it wouldn't be better to have this data on a connection basis.
+  - If NOT leave them as they are.
+    (e.g. this could be the variable for the private debug class.)
+  - If YES pack all this data into a struct.
+    You can use handle-&gt;data to point to such a struct on a
+    per connection basis.
+
+  e.g. if you have such a struct:
+<programlisting>    
+struct example_privates {
+       char *some_string;
+       int db_connection;
+};
+</programlisting>      
+1st way of doing it:
+<programlisting>
+static int example_connect(vfs_handle_struct *handle,
+       connection_struct *conn, const char *service, 
+       const char* user)
+{
+       struct example_privates *data = NULL;
+
+       /* alloc our private data */
+       data = (struct example_privates *)talloc_zero(conn-&gt;mem_ctx, sizeof(struct example_privates));
+       if (!data) {
+               DEBUG(0,(&quot;talloc_zero() failed\n&quot;));
+               return -1;
+       }
+
+       /* init out private data */
+       data-&gt;some_string = talloc_strdup(conn-&gt;mem_ctx,&quot;test&quot;);
+       if (!data-&gt;some_string) {
+               DEBUG(0,(&quot;talloc_strdup() failed\n&quot;));
+               return -1;
+       }
+
+       data-&gt;db_connection = open_db_conn();
+
+       /* and now store the private data pointer in handle-&gt;data
+        * we don't need to specify a free_function here because
+        * we use the connection TALLOC context.
+        * (return -1 if something failed.)
+        */
+       VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
+
+       return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
+}
+
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       struct example_privates *data = NULL;
+       
+       /* get the pointer to our private data
+        * return -1 if something failed
+        */
+       SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
+       
+       /* do something here...*/
+       DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
+       
+       return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+2nd way of doing it:
+<programlisting>
+static void free_example_privates(void **datap)
+{
+       struct example_privates *data = (struct example_privates *)*datap;
+       
+       SAFE_FREE(data-&gt;some_string);
+       SAFE_FREE(data);
+       
+       datap = NULL;
+       
+       return;
+}
+
+static int example_connect(vfs_handle_struct *handle, 
+       connection_struct *conn, const char *service, 
+       const char* user)
+{
+       struct example_privates *data = NULL;
+
+       /* alloc our private data */
+       data = (struct example_privates *)malloc(sizeof(struct example_privates));
+       if (!data) {
+               DEBUG(0,(&quot;malloc() failed\n&quot;));
+               return -1;
+       }
+
+       /* init out private data */
+       data-&gt;some_string = strdup(conn-&gt;mem_ctx,&quot;test&quot;);
+       if (!data-&gt;some_string) {
+               DEBUG(0,(&quot;strdup() failed\n&quot;));
+               return -1;
+       }
+
+       data-&gt;db_connection = open_db_conn();
+
+       /* and now store the private data pointer in handle-&gt;data
+        * we need to specify a free_function because we used malloc() and strdup().
+        * (return -1 if something failed.)
+        */
+       SMB_VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
+
+       return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
+}
+
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       struct example_privates *data = NULL;
+       
+       /* get the pointer to our private data
+        * return -1 if something failed
+        */
+       SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
+       
+       /* do something here...*/
+       DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
+       
+       return VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+</para></listitem>
+
+<listitem><para>
+To make it easy to build 3rd party modules it would be usefull to provide
+configure.in, (configure), install.sh and Makefile.in with the module.
+(Take a look at the example in <filename>examples/VFS</filename>.)
+
+The configure script accept --with-samba-source to specify the path to
+the samba source tree.
+It also accept --enable-developer witch let the compiler give you more warnings.  
+
+The idea is that you can extend this configure.in and Makefile.in scripts
+for your module.
+</para></listitem>
+
+<listitem><para>
+Compiling & Testing...
+- configure --enable-developer ...
+- make
+- Try to fiy all compiler warnings
+- make
+- Testing, Testing, Testing ...
+</para></listitem>
+</orderedlist>
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Some Notes</title>
+
+<sect2>
+<title>Implement TRANSPARENT functions</title>
+
+<para>
+Avoid writting functions like this:
+
+<programlisting>
+static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
+{
+       return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
+}
+</programlisting>
+
+Overload only the functions you really need to!
+</para>
+
+</sect2>
+
+<sect2>
+<title>Implement OPAQUE functions</title>
+
+<para>
+If you want just implement only a better version of a 
+default samba opaque function
+(e.g. like a disk_free() function for a speciall filesystem) 
+it's ok to just overload that specific function.
+</para>
+
+<para>
+If you want to implement a database filesystem or
+something different from a posix filesystem.
+Make sure that you overload every vfs operation!!!
+</para>
+<para>
+Functions your FS does not support should be overloaded by something like this:
+e.g. for a readonly filesystem.
+</para>
+
+<programlisting>
+static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
+                       char *oldname, char *newname)
+{
+       DEBUG(10,(&quot;function rename() not allowed on vfs 'example'\n&quot;));
+       errno = ENOSYS;
+       return -1;
+}
+</programlisting>
+
+</sect2>
+
+</sect1>
+
+</chapter>