diff options
Diffstat (limited to 'docs/docbook/devdoc/vfs.xml')
| -rw-r--r-- | docs/docbook/devdoc/vfs.xml | 797 |
1 files changed, 0 insertions, 797 deletions
diff --git a/docs/docbook/devdoc/vfs.xml b/docs/docbook/devdoc/vfs.xml deleted file mode 100644 index ed2afef53e..0000000000 --- a/docs/docbook/devdoc/vfs.xml +++ /dev/null @@ -1,797 +0,0 @@ -<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->vfs.ops.* directly !!! -<programlisting> -... - -/* File operations */ -#define SMB_VFS_OPEN(conn, fname, flags, mode) \ - ((conn)->vfs.ops.open((conn)->vfs.handles.open,\ - (conn), (fname), (flags), (mode))) -#define SMB_VFS_CLOSE(fsp, fd) \ - ((fsp)->conn->vfs.ops.close(\ - (fsp)->conn->vfs.handles.close, (fsp), (fd))) -#define SMB_VFS_READ(fsp, fd, data, n) \ - ((fsp)->conn->vfs.ops.read(\ - (fsp)->conn->vfs.handles.read,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_WRITE(fsp, fd, data, n) \ - ((fsp)->conn->vfs.ops.write(\ - (fsp)->conn->vfs.handles.write,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_LSEEK(fsp, fd, offset, whence) \ - ((fsp)->conn->vfs.ops.lseek(\ - (fsp)->conn->vfs.handles.lseek,\ - (fsp), (fd), (offset), (whence))) -#define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \ - ((fsp)->conn->vfs.ops.sendfile(\ - (fsp)->conn->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->vfs -and conn->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, "example", 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 "test".</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 SMB_VFS_NEXT_* macros to call a next module operations and -don't access handle->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->conn->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->conn->mem_ctx, -you can set this function pointer to NULL.</para></listitem> -</varlistentry> - -</variablelist> - -<para>Some useful MACROS for handle private data. -</para> - -<programlisting> -#define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \ - if (!(handle)||((datap=(type *)(handle)->data)==NULL)) { \ - DEBUG(0,("%s() failed to get vfs_handle->data!\n",FUNCTION_MACRO)); \ - ret; \ - } \ -} - -#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \ - if (!(handle)) { \ - DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \ - ret; \ - } else { \ - if ((handle)->free_data) { \ - (handle)->free_data(&(handle)->data); \ - } \ - (handle)->data = (void *)datap; \ - (handle)->free_data = free_fn; \ - } \ -} - -#define SMB_VFS_HANDLE_FREE_DATA(handle) { \ - if ((handle) && (handle)->free_data) { \ - (handle)->free_data(&(handle)->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)->vfs_opaque.ops.open(\ - (conn)->vfs_opaque.handles.open,\ - (conn), (fname), (flags), (mode))) -#define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \ - ((fsp)->conn->vfs_opaque.ops.close(\ - (fsp)->conn->vfs_opaque.handles.close,\ - (fsp), (fd))) -#define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \ - ((fsp)->conn->vfs_opaque.ops.read(\ - (fsp)->conn->vfs_opaque.handles.read,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \ - ((fsp)->conn->vfs_opaque.ops.write(\ - (fsp)->conn->vfs_opaque.handles.write,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \ - ((fsp)->conn->vfs_opaque.ops.lseek(\ - (fsp)->conn->vfs_opaque.handles.lseek,\ - (fsp), (fd), (offset), (whence))) -#define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \ - ((fsp)->conn->vfs_opaque.ops.sendfile(\ - (fsp)->conn->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)->vfs_next.ops.open(\ - (handle)->vfs_next.handles.open,\ - (conn), (fname), (flags), (mode))) -#define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \ - ((handle)->vfs_next.ops.close(\ - (handle)->vfs_next.handles.close,\ - (fsp), (fd))) -#define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \ - ((handle)->vfs_next.ops.read(\ - (handle)->vfs_next.handles.read,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \ - ((handle)->vfs_next.ops.write(\ - (handle)->vfs_next.handles.write,\ - (fsp), (fd), (data), (n))) -#define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \ - ((handle)->vfs_next.ops.lseek(\ - (handle)->vfs_next.handles.lseek,\ - (fsp), (fd), (offset), (whence))) -#define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \ - ((handle)->vfs_next.ops.sendfile(\ - (handle)->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 "vfs_handle_struct *handle, " as first parameter to all vfs operation functions. -e.g. example_connect(connection_struct *conn, const char *service, const char *user); --> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user); -</para></listitem> - -<listitem><para> -Replace "default_vfs_ops." with "smb_vfs_next_". -e.g. default_vfs_ops.connect(conn, service, user); --> smb_vfs_next_connect(conn, service, user); -</para></listitem> - -<listitem><para> -Uppercase all "smb_vfs_next_*" functions. -e.g. smb_vfs_next_connect(conn, service, user); --> SMB_VFS_NEXT_CONNECT(conn, service, user); -</para></listitem> - -<listitem><para> -Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls. -e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); --> 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> --> -<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,"example",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. -<simplelist> -<member>If NOT you can remove the vfs_init() function.</member> -<member>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() and the allocation of private data should go to example_connect().</member> -</simplelist> -</para></listitem> - -<listitem><para> -(Only for 3.0alpha* modules) -Check if your vfs_done() function contains needed code. -<simplelist> -<member>If NOT you can remove the vfs_done() function.</member> -<member>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 <link linkend="modules">modules section</link>) And then remove vfs_done(). e.g. the freeing of private data should go to example_disconnect(). -</member> -</simplelist> -</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. -<simplelist> - <member>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</member> - <member>If YES pack all this data into a struct. You can use handle->data to point to such a struct on a per connection basis.</member> -</simplelist> - - e.g. if you have such a struct: -<programlisting> -struct example_privates { - char *some_string; - int db_connection; -}; -</programlisting> -first 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->mem_ctx, sizeof(struct example_privates)); - if (!data) { - DEBUG(0,("talloc_zero() failed\n")); - return -1; - } - - /* init out private data */ - data->some_string = talloc_strdup(conn->mem_ctx,"test"); - if (!data->some_string) { - DEBUG(0,("talloc_strdup() failed\n")); - return -1; - } - - data->db_connection = open_db_conn(); - - /* and now store the private data pointer in handle->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,("some_string: %s\n",data->some_string)); - - return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); -} -</programlisting> -second way of doing it: -<programlisting> -static void free_example_privates(void **datap) -{ - struct example_privates *data = (struct example_privates *)*datap; - - SAFE_FREE(data->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,("malloc() failed\n")); - return -1; - } - - /* init out private data */ - data->some_string = strdup("test"); - if (!data->some_string) { - DEBUG(0,("strdup() failed\n")); - return -1; - } - - data->db_connection = open_db_conn(); - - /* and now store the private data pointer in handle->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, free_example_privates, 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,("some_string: %s\n",data->some_string)); - - return SMB_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>.) -</para> - -<para> -The configure script accepts <option>--with-samba-source</option> to specify -the path to the samba source tree. -It also accept <option>--enable-developer</option> which lets the compiler -give you more warnings. -</para> - -<para> -The idea is that you can extend this -<filename>configure.in</filename> and <filename>Makefile.in</filename> scripts -for your module. -</para></listitem> - -<listitem><para> -Compiling & Testing... -<simplelist> -<member><userinput>./configure <option>--enable-developer</option></userinput> ...</member> -<member><userinput>make</userinput></member> -<member>Try to fix all compiler warnings</member> -<member><userinput>make</userinput></member> -<member>Testing, Testing, Testing ...</member> -</simplelist> -</para></listitem> -</orderedlist> -</sect2> - -</sect1> - -<sect1> -<title>Some Notes</title> - -<sect2> -<title>Implement TRANSPARENT functions</title> - -<para> -Avoid writing 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 to just implement a better version of a -default samba opaque function -(e.g. like a disk_free() function for a special 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,("function rename() not allowed on vfs 'example'\n")); - errno = ENOSYS; - return -1; -} -</programlisting> - -</sect2> - -</sect1> - -</chapter> |