diff options
Diffstat (limited to 'docs/htmldocs/Samba3-Developers-Guide/vfs.html')
| -rw-r--r-- | docs/htmldocs/Samba3-Developers-Guide/vfs.html | 653 |
1 files changed, 0 insertions, 653 deletions
diff --git a/docs/htmldocs/Samba3-Developers-Guide/vfs.html b/docs/htmldocs/Samba3-Developers-Guide/vfs.html deleted file mode 100644 index e2d78b84ec..0000000000 --- a/docs/htmldocs/Samba3-Developers-Guide/vfs.html +++ /dev/null @@ -1,653 +0,0 @@ -<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 10. VFS Modules</title><link rel="stylesheet" href="../samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt03.html" title="Part III. Samba Subsystems"><link rel="prev" href="rpc-plugin.html" title="Chapter 9. RPC Pluggable Modules"><link rel="next" href="parsing.html" title="Chapter 11. The smb.conf file"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 10. VFS Modules</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="rpc-plugin.html">Prev</a> </td><th width="60%" align="center">Part III. Samba Subsystems</th><td width="20%" align="right"> <a accesskey="n" href="parsing.html">Next</a></td></tr></table><hr></div><div class="chapter" title="Chapter 10. VFS Modules"><div class="titlepage"><div><div><h2 class="title"><a name="vfs"></a>Chapter 10. VFS Modules</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Alexander</span> <span class="surname">Bokovoy</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:ab@samba.org">ab@samba.org</a>></code></p></div></div></div></div><div><div class="author"><h3 class="author"><span class="firstname">Stefan</span> <span class="surname">Metzmacher</span></h3><div class="affiliation"><div class="address"><p><code class="email"><<a class="email" href="mailto:metze@samba.org">metze@samba.org</a>></code></p></div></div></div></div><div><p class="pubdate"> 27 May 2003 </p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="vfs.html#id330849">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id330877">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id331145">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id331195">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id331201">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id331328">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id331482">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id331487">Upgrading from 2.2.* and 3.0alpha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id331788">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id331793">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id331809">Implement OPAQUE functions</a></span></dt></dl></dd></dl></div><div class="sect1" title="The Samba (Posix) VFS layer"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330849"></a>The Samba (Posix) VFS layer</h2></div></div></div><p>While most of Samba deployments are done using POSIX-compatible -operating systems, there is clearly more to a file system than what is -required by POSIX when it comes to adopting semantics of NT file -system. Since Samba 2.2 all file-system related operations go through -an abstraction layer for virtual file system (VFS) that is modelled -after both POSIX and additional functions needed to transform NTFS -semantics. -</p><p> -This abstraction layer now provides more features than a regular POSIX -file system could fill in. It is not required that all of them should -be implemented by your particular file system. However, when those -features are available, Samba would advertize them to a CIFS client -and they might be used by an application and in case of Windows client -that might mean a client expects even more additional functionality -when it encounters those features. There is a practical reason to -allow handling of this snowfall without modifying the Samba core and -it is fulfilled by providing an infrastructure to dynamically load VFS -modules at run time. -</p><p>Each VFS module could implement a number of VFS operations. The -way it does it is irrelevant, only two things actually matter: whether -specific implementation wants to cooperate with other modules' -implementations or not, and whether module needs to store additional -information that is specific to a context it is operating in. Multiple -VFS modules could be loaded at the same time and it is even possible -to load several instances of the same VFS module with different -parameters. -</p><div class="sect2" title="The general interface"><div class="titlepage"><div><div><h3 class="title"><a name="id330877"></a>The general interface</h3></div></div></div><p>A VFS module has three major components: -</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>An initialization function</em></span> that is -called during the module load to register implemented -operations.</p></li><li class="listitem"><p><span class="emphasis"><em>An operations table</em></span> representing a -mapping between statically defined module functions and VFS layer -operations.</p></li><li class="listitem"><p><span class="emphasis"><em>Module functions</em></span> that do actual - work.</p></li></ul></div><p> -</p><p>While this structure has been first applied to the VFS -subsystem, it is now commonly used across all Samba 3 subsystems that -support loadable modules. In fact, one module could provide a number -of interfaces to different subsystems by exposing different -<span class="emphasis"><em>operation tables</em></span> through separate -<span class="emphasis"><em>initialization functions</em></span>.</p><p><span class="emphasis"><em>An initialization function</em></span> is used to -register module with Samba run-time. As Samba internal structures and -API are changed over lifetime, each released version has a VFS -interface version that is increased as VFS development progresses or -any of underlying Samba structures are changed in binary-incompatible -way. When VFS module is compiled in, VFS interface version of that -Samba environment is embedded into the module's binary object and is -checked by the Samba core upon module load. If VFS interface number -reported by the module isn't the same Samba core knows about, version -conflict is detected and module dropped to avoid any potential memory -corruption when accessing (changed) Samba structures. -</p><p>Therefore, initialization function passes three parameters to the -VFS registration function, <code class="literal">smb_register_vfs()</code> -</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>interface version number</em></span>, as constant - <code class="literal">SMB_VFS_INTERFACE_VERSION</code>, </p></li><li class="listitem"><p><span class="emphasis"><em>module name</em></span>, under which Samba core - will know it, and</p></li><li class="listitem"><p><span class="emphasis"><em>an operations' table</em></span>.</p></li></ul></div><p> -</p><p>The <span class="emphasis"><em>operations' table</em></span> defines which -functions in the module would correspond to specific VFS operations -and how those functions would co-operate with the rest of VFS -subsystem. Each operation could perform in a following ways: -</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>transparent</em></span>, meaning that while - operation is overriden, the module will still call a previous - implementation, before or after its own action. This mode is - indicated by the constant - <code class="literal">SMB_VFS_LAYER_TRANSPARENT</code>;</p></li><li class="listitem"><p><span class="emphasis"><em>opaque</em></span>, for the implementations that - are terminating sequence of actions. For example, it is used to - implement POSIX operation on top of non-POSIX file system or even - not a file system at all, like a database for a personal audio - collection. Use constant <code class="literal">SMB_VFS_LAYER_OPAQUE</code> for - this mode;</p></li><li class="listitem"><p><span class="emphasis"><em>splitter</em></span>, a way when some file system - activity is done in addition to the transparently calling previous - implentation. This usually involves mangling the result of that call - before returning it back to the caller. This mode is selected by - <code class="literal">SMB_VFS_LAYER_SPLITTER</code> constant;</p></li><li class="listitem"><p><span class="emphasis"><em>logger</em></span> does not change anything or - performs any additional VFS operations. When - <span class="emphasis"><em>logger</em></span> module acts, information about - operations is logged somewhere using an external facility (or - Samba's own debugging tools) but not the VFS layer. In order to - describe this type of activity use constant - <code class="literal">SMB_VFS_LAYER_LOGGER</code>; - </p></li><li class="listitem"><p>On contrary, <span class="emphasis"><em>scanner</em></span> module does call - other VFS operations while processing the data that goes through the - system. This type of operation is indicated by the - <code class="literal">SMB_VFS_LAYER_SCANNER</code> constant.</p></li></ul></div><p> -</p><p>Fundamentally, there are three types: -<span class="emphasis"><em>transparent</em></span>, <span class="emphasis"><em>opaque</em></span>, and -<span class="emphasis"><em>logger</em></span>. <span class="emphasis"><em>Splitter</em></span> and -<span class="emphasis"><em>scanner</em></span> may confuse developers (and indeed they -are confused as our experience has shown) but this separation is to -better expose the nature of a module's actions. Most of modules -developed so far are either one of those three fundamental types with -transparent and opaque being prevalent. -</p><p> -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 -<code class="filename">include/vfs.h</code> and -<code class="filename">include/vfs_macros.h</code>.) -</p><pre class="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; -</pre><p>This struct contains the function and handle pointers for all operations.</p><pre class="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; -}; -</pre><p> -This macros SHOULD be used to call any vfs operation. -DO NOT ACCESS conn->vfs.ops.* directly !!! -</p><pre class="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))) - -... -</pre></div><div class="sect2" title="Possible VFS operation layers"><div class="titlepage"><div><div><h3 class="title"><a name="id331145"></a>Possible VFS operation layers</h3></div></div></div><p> -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. -</p><p> -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. -</p><p> -Other layer types (logger, splitter, scanner) were designed to provide different -degree of transparency and for diagnosing VFS module behaviour. -</p><p> -Each module can implement several layers at the same time provided that only -one layer is used per each operation. -</p><pre class="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; -</pre></div></div><div class="sect1" title="The Interaction between the Samba VFS subsystem and the modules"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id331195"></a>The Interaction between the Samba VFS subsystem and the modules</h2></div></div></div><div class="sect2" title="Initialization and registration"><div class="titlepage"><div><div><h3 class="title"><a name="id331201"></a>Initialization and registration</h3></div></div></div><p> -As each Samba module a VFS module should have a -</p><pre class="programlisting">NTSTATUS vfs_example_init(void);</pre><p> function if it's staticly linked to samba or -</p><pre class="programlisting">NTSTATUS init_module(void);</pre><p> function if it's a shared module. -</p><p> -This should be the only non static function inside the module. -Global variables should also be static! -</p><p> -The module should register its functions via the -</p><pre class="programlisting"> -NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples); -</pre><p> function. -</p><div class="variablelist"><dl><dt><span class="term">version</span></dt><dd><p>should be filled with SMB_VFS_INTERFACE_VERSION</p></dd><dt><span class="term">name</span></dt><dd><p>this is the name witch can be listed in the -<code class="literal">vfs objects</code> parameter to use this module.</p></dd><dt><span class="term">vfs_op_tuples</span></dt><dd><p> -this is an array of vfs_op_tuple's. -(vfs_op_tuples is descripted in details below.) -</p></dd></dl></div><p> -For each operation the module wants to provide it has a entry in the -vfs_op_tuple array. -</p><pre class="programlisting"> -typedef struct _vfs_op_tuple { - void* op; - vfs_op_type type; - vfs_op_layer layer; -} vfs_op_tuple; -</pre><div class="variablelist"><dl><dt><span class="term">op</span></dt><dd><p>the function pointer to the specified function.</p></dd><dt><span class="term">type</span></dt><dd><p>the vfs_op_type of the function to specified witch operation the function provides.</p></dd><dt><span class="term">layer</span></dt><dd><p>the vfs_op_layer in whitch the function operates.</p></dd></dl></div><p>A simple example:</p><pre class="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); -} -</pre></div><div class="sect2" title="How the Modules handle per connection data"><div class="titlepage"><div><div><h3 class="title"><a name="id331328"></a>How the Modules handle per connection data</h3></div></div></div><p>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct. -</p><pre class="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; -</pre><div class="variablelist"><dl><dt><span class="term">param</span></dt><dd><p>this is the module parameter specified in the <code class="literal">vfs objects</code> parameter.</p><p>e.g. for 'vfs objects = example:test' param would be "test".</p></dd><dt><span class="term">vfs_next</span></dt><dd><p>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!</p></dd><dt><span class="term">conn</span></dt><dd><p>This is a pointer back to the connection_struct to witch the handle belongs.</p></dd><dt><span class="term">data</span></dt><dd><p>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.</p></dd><dt><span class="term">free_data</span></dt><dd><p>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.</p></dd></dl></div><p>Some useful MACROS for handle private data. -</p><pre class="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); \ - } \ -} -</pre><p>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</p><p>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros. -</p><pre class="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))) -... -</pre><p>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</p><p>The easiest way to do this is to use the SMB_VFS_NEXT_* macros. -</p><pre class="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))) -... -</pre></div></div><div class="sect1" title="Upgrading to the New VFS Interface"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id331482"></a>Upgrading to the New VFS Interface</h2></div></div></div><div class="sect2" title="Upgrading from 2.2.* and 3.0alpha modules"><div class="titlepage"><div><div><h3 class="title"><a name="id331487"></a>Upgrading from 2.2.* and 3.0alpha modules</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> -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); -</p></li><li class="listitem"><p> -Replace "default_vfs_ops." with "smb_vfs_next_". -e.g. default_vfs_ops.connect(conn, service, user); --> smb_vfs_next_connect(conn, service, user); -</p></li><li class="listitem"><p> -Uppercase all "smb_vfs_next_*" functions. -e.g. smb_vfs_next_connect(conn, service, user); --> SMB_VFS_NEXT_CONNECT(conn, service, user); -</p></li><li class="listitem"><p> -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); -</p></li><li class="listitem"><p> -(Only for 2.2.* modules) -Convert the old struct vfs_ops example_ops to -a vfs_op_tuple example_op_tuples[] array. -e.g. -</p><pre class="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 */ -}; -</pre><p> --> -</p><pre class="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} -}; -</pre><p> -</p></li><li class="listitem"><p> -Move the example_op_tuples[] array to the end of the file. -</p></li><li class="listitem"><p> -Add the init_module() function at the end of the file. -e.g. -</p><pre class="programlisting"> -NTSTATUS init_module(void) -{ - return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,"example",example_op_tuples); -} -</pre><p> -</p></li><li class="listitem"><p> -Check if your vfs_init() function does more then just prepare the vfs_ops structs or -remember the struct smb_vfs_handle_struct. -</p><table border="0" summary="Simple list" class="simplelist"><tr><td>If NOT you can remove the vfs_init() function.</td></tr><tr><td>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().</td></tr></table><p> -</p></li><li class="listitem"><p> -(Only for 3.0alpha* modules) -Check if your vfs_done() function contains needed code. -</p><table border="0" summary="Simple list" class="simplelist"><tr><td>If NOT you can remove the vfs_done() function.</td></tr><tr><td>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 <a class="link" href="modules.html" title="Chapter 8. Modules">modules section</a>) And then remove vfs_done(). e.g. the freeing of private data should go to example_disconnect(). -</td></tr></table><p> -</p></li><li class="listitem"><p> -Check if you have any global variables left. -Decide if it wouldn't be better to have this data on a connection basis. -</p><table border="0" summary="Simple list" class="simplelist"><tr><td>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</td></tr><tr><td>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.</td></tr></table><p> - - e.g. if you have such a struct: -</p><pre class="programlisting"> -struct example_privates { - char *some_string; - int db_connection; -}; -</pre><p> -first way of doing it: -</p><pre class="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); -} -</pre><p> -second way of doing it: -</p><pre class="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); -} -</pre><p> -</p></li><li class="listitem"><p> -To make it easy to build 3rd party modules it would be useful to provide -configure.in, (configure), install.sh and Makefile.in with the module. -(Take a look at the example in <code class="filename">examples/VFS</code>.) -</p><p> -The configure script accepts <code class="option">--with-samba-source</code> to specify -the path to the samba source tree. -It also accept <code class="option">--enable-developer</code> which lets the compiler -give you more warnings. -</p><p> -The idea is that you can extend this -<code class="filename">configure.in</code> and <code class="filename">Makefile.in</code> scripts -for your module. -</p></li><li class="listitem"><p> -Compiling & Testing... -</p><table border="0" summary="Simple list" class="simplelist"><tr><td><strong class="userinput"><code>./configure <code class="option">--enable-developer</code></code></strong> ...</td></tr><tr><td><strong class="userinput"><code>make</code></strong></td></tr><tr><td>Try to fix all compiler warnings</td></tr><tr><td><strong class="userinput"><code>make</code></strong></td></tr><tr><td>Testing, Testing, Testing ...</td></tr></table><p> -</p></li></ol></div></div></div><div class="sect1" title="Some Notes"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id331788"></a>Some Notes</h2></div></div></div><div class="sect2" title="Implement TRANSPARENT functions"><div class="titlepage"><div><div><h3 class="title"><a name="id331793"></a>Implement TRANSPARENT functions</h3></div></div></div><p> -Avoid writing functions like this: - -</p><pre class="programlisting"> -static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) -{ - return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); -} -</pre><p> - -Overload only the functions you really need to! -</p></div><div class="sect2" title="Implement OPAQUE functions"><div class="titlepage"><div><div><h3 class="title"><a name="id331809"></a>Implement OPAQUE functions</h3></div></div></div><p> -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. -</p><p> -If you want to implement a database filesystem or -something different from a posix filesystem. -Make sure that you overload every vfs operation!!! -</p><p> -Functions your FS does not support should be overloaded by something like this: -e.g. for a readonly filesystem. -</p><pre class="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; -} -</pre></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rpc-plugin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parsing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 9. RPC Pluggable Modules </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 11. The smb.conf file</td></tr></table></div></body></html> |