Ignore:
Timestamp:
May 23, 2008, 6:56:41 AM (17 years ago)
Author:
Paul Smedley
Message:

Update source to 3.0.29

File:
1 edited

Legend:

Unmodified
Added
Removed

  • branches/samba-3.0/docs/htmldocs/Samba3-Developers-Guide/vfs.html

    r44 r134  
    1 <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.71.0"><link rel="start" 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" lang="en"><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">&lt;<a href="mailto:ab@samba.org">ab@samba.org</a>&gt;</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">&lt;<a href="mailto:metze@samba.org">metze@samba.org</a>&gt;</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#id324691">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id324696">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id324766">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id324811">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id324817">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id324954">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id325112">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id325117">Upgrading from 2.2.* and 3.0aplha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id325448">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id325454">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id325472">Implement OPAQUE functions</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id324691"></a>The Samba (Posix) VFS layer</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id324696"></a>The general interface</h3></div></div></div><p>
    2 Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the
    3 struct vfs_ops and tree macros to make it easier to call the operations.
    4 (Take a look at <code class="filename">include/vfs.h</code> and <code class="filename">include/vfs_macros.h</code>.)
     1<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.73.2"><link rel="start" 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" lang="en"><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">&lt;<a class="email" href="mailto:ab@samba.org">ab@samba.org</a>&gt;</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">&lt;<a class="email" href="mailto:metze@samba.org">metze@samba.org</a>&gt;</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#id348426">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id348454">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id348708">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id348752">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id348758">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id348885">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id349039">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id349044">Upgrading from 2.2.* and 3.0aplha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id349344">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id349350">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id349366">Implement OPAQUE functions</a></span></dt></dl></dd></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id348426"></a>The Samba (Posix) VFS layer</h2></div></div></div><p>While most of Samba deployments are done using POSIX-compatible
     2operating systems, there is clearly more to a file system than what is
     3required by POSIX when it comes to adopting semantics of NT file
     4system. Since Samba 2.2 all file-system related operations go through
     5an abstraction layer for virtual file system (VFS) that is modelled
     6after both POSIX and additional functions needed to transform NTFS
     7semantics.
     8</p><p>
     9This abstraction layer now provides more features than a regular POSIX
     10file system could fill in. It is not required that all of them should
     11be implemented by your particular file system.  However, when those
     12features are available, Samba would advertize them to a CIFS client
     13and they might be used by an application and in case of Windows client
     14that might mean a client expects even more additional functionality
     15when it encounters those features. There is a practical reason to
     16allow handling of this snowfall without modifying the Samba core and
     17it is fulfilled by providing an infrastructure to dynamically load VFS
     18modules at run time.
     19</p><p>Each VFS module could implement a number of VFS operations. The
     20way it does it is irrelevant, only two things actually matter: whether
     21specific implementation wants to cooperate with other modules'
     22implementations or not, and whether module needs to store additional
     23information that is specific to a context it is operating in. Multiple
     24VFS modules could be loaded at the same time and it is even possible
     25to load several instances of the same VFS module with different
     26parameters.
     27</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id348454"></a>The general interface</h3></div></div></div><p>A VFS module has three major components:
     28</p><div class="itemizedlist"><ul type="disc"><li><span class="emphasis"><em>An initialization function</em></span> that is
     29called during the module load to register implemented
     30operations.</li><li><span class="emphasis"><em>An operations table</em></span> representing a
     31mapping between statically defined module functions and VFS layer
     32operations.</li><li><span class="emphasis"><em>Module functions</em></span> that do actual
     33work.</li></ul></div><p>
     34</p><p>While this structure has been first applied to the VFS
     35subsystem, it is now commonly used across all Samba 3 subsystems that
     36support loadable modules. In fact, one module could provide a number
     37of interfaces to different subsystems by exposing different
     38<span class="emphasis"><em>operation tables</em></span> through separate
     39<span class="emphasis"><em>initialization functions</em></span>.</p><p><span class="emphasis"><em>An initialization function</em></span> is used to
     40register module with Samba run-time. As Samba internal structures and
     41API are changed over lifetime, each released version has a VFS
     42interface version that is increased as VFS development progresses or
     43any of underlying Samba structures are changed in binary-incompatible
     44way. When VFS module is compiled in, VFS interface version of that
     45Samba environment is embedded into the module's binary object and is
     46checked by the Samba core upon module load. If VFS interface number
     47reported by the module isn't the same Samba core knows about, version
     48conflict is detected and module dropped to avoid any potential memory
     49corruption when accessing (changed) Samba structures.
     50</p><p>Therefore, initialization function passes three parameters to the
     51VFS registration function, <code class="literal">smb_register_vfs()</code>
     52</p><div class="itemizedlist"><ul type="disc"><li><span class="emphasis"><em>interface version number</em></span>, as constant
     53  <code class="literal">SMB_VFS_INTERFACE_VERSION</code>, </li><li><span class="emphasis"><em>module name</em></span>, under which Samba core
     54  will know it, and</li><li><span class="emphasis"><em>an operations' table</em></span>.</li></ul></div><p>
     55</p><p>The <span class="emphasis"><em>operations' table</em></span> defines which
     56functions in the module would correspond to specific VFS operations
     57and how those functions would co-operate with the rest of VFS
     58subsystem. Each operation could perform in a following ways:
     59</p><div class="itemizedlist"><ul type="disc"><li><span class="emphasis"><em>transparent</em></span>, meaning that while
     60  operation is overriden, the module will still call a previous
     61  implementation, before or after its own action. This mode is
     62  indicated by the constant
     63  <code class="literal">SMB_VFS_LAYER_TRANSPARENT</code>;
     64  </li><li><span class="emphasis"><em>opaque</em></span>, for the implementations that
     65  are terminating sequence of actions. For example, it is used to
     66  implement POSIX operation on top of non-POSIX file system or even
     67  not a file system at all, like a database for a personal audio
     68  collection. Use constant <code class="literal">SMB_VFS_LAYER_OPAQUE</code> for
     69  this mode;</li><li><span class="emphasis"><em>splitter</em></span>, a way when some file system
     70  activity is done in addition to the transparently calling previous
     71  implentation. This usually involves mangling the result of that call
     72  before returning it back to the caller. This mode is selected by
     73  <code class="literal">SMB_VFS_LAYER_SPLITTER</code> constant;</li><li><span class="emphasis"><em>logger</em></span> does not change anything or
     74  performs any additional VFS operations. When
     75  <span class="emphasis"><em>logger</em></span> module acts, information about
     76  operations is logged somewhere using an external facility (or
     77  Samba's own debugging tools) but not the VFS layer. In order to
     78  describe this type of activity use constant
     79  <code class="literal">SMB_VFS_LAYER_LOGGER</code>;
     80  </li><li>On contrary, <span class="emphasis"><em>scanner</em></span> module does call
     81  other VFS operations while processing the data that goes through the
     82  system. This type of operation is indicated by the
     83  <code class="literal">SMB_VFS_LAYER_SCANNER</code> constant.</li></ul></div><p>
     84</p><p>Fundamentally, there are three types:
     85<span class="emphasis"><em>transparent</em></span>, <span class="emphasis"><em>opaque</em></span>, and
     86<span class="emphasis"><em>logger</em></span>. <span class="emphasis"><em>Splitter</em></span> and
     87<span class="emphasis"><em>scanner</em></span> may confuse developers (and indeed they
     88are confused as our experience has shown) but this separation is to
     89better expose the nature of a module's actions. Most of modules
     90developed so far are either one of those three fundamental types with
     91transparent and opaque being prevalent.
     92</p><p>
     93Each VFS operation has a vfs_op_type, a function pointer and a handle
     94pointer in the struct vfs_ops and tree macros to make it easier to
     95call the operations.  (Take a look at
     96<code class="filename">include/vfs.h</code> and
     97<code class="filename">include/vfs_macros.h</code>.)
    598</p><pre class="programlisting">
    699typedef enum _vfs_op_type {
    … …  
    95188
    96189...
    97 </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id324766"></a>Possible VFS operation layers</h3></div></div></div><p>
     190</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id348708"></a>Possible VFS operation layers</h3></div></div></div><p>
    98191These values are used by the VFS subsystem when building the conn-&gt;vfs
    99192and conn-&gt;vfs_opaque structs for a connection with multiple VFS modules.
    … …  
    124217                                        /*   file activity like logging to files _inside_ samba VFS */
    125218} vfs_op_layer;
    126 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id324811"></a>The Interaction between the Samba VFS subsystem and the modules</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id324817"></a>Initialization and registration</h3></div></div></div><p>
     219</pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id348752"></a>The Interaction between the Samba VFS subsystem and the modules</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id348758"></a>Initialization and registration</h3></div></div></div><p>
    127220As each Samba module a VFS module should have a
    128221</p><pre class="programlisting">NTSTATUS vfs_example_init(void);</pre><p> function if it's staticly linked to samba or
    … …  
    164257        return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples);
    165258}
    166 </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id324954"></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.
     259</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id348885"></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.
    167260</p><pre class="programlisting">
    168261typedef struct vfs_handle_struct {
    … …  
    265358         (tofd), (fsp), (fromfd), (header), (offset), (count)))
    266359...
    267 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id325112"></a>Upgrading to the New VFS Interface</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id325117"></a>Upgrading from 2.2.* and 3.0aplha modules</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>
     360</pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id349039"></a>Upgrading to the New VFS Interface</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id349044"></a>Upgrading from 2.2.* and 3.0aplha modules</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>
    268361Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions.
    269362e.g. example_connect(connection_struct *conn, const char *service, const char *user);
    … …  
    389482(Only for 3.0alpha* modules)
    390483Check if your vfs_done() function contains needed code.
    391 </p><table class="simplelist" border="0" summary="Simple list"><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 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().
     484</p><table class="simplelist" border="0" summary="Simple list"><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().
    392485</td></tr></table><p>
    393486</p></li><li><p>
    … …  
    528621Compiling &amp; Testing...
    529622</p><table class="simplelist" border="0" summary="Simple list"><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>
    530 </p></li></ol></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id325448"></a>Some Notes</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id325454"></a>Implement TRANSPARENT functions</h3></div></div></div><p>
     623</p></li></ol></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id349344"></a>Some Notes</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id349350"></a>Implement TRANSPARENT functions</h3></div></div></div><p>
    531624Avoid writing functions like this:
    532625
    … …  
    539632
    540633Overload only the functions you really need to!
    541 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id325472"></a>Implement OPAQUE functions</h3></div></div></div><p>
     634</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id349366"></a>Implement OPAQUE functions</h3></div></div></div><p>
    542635If you want to just implement a better version of a
    543636default samba opaque function
Note: See TracChangeset for help on using the changeset viewer.