2004-06-06 02:31:58 +04:00
<?xml version="1.0" encoding="iso-8859-1"?>
2005-03-13 04:38:40 +03:00
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
2004-04-07 14:15:11 +04:00
<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@samba.org</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>
