- Timestamp:
- Jul 6, 2011, 8:21:13 PM (14 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
trunk/server/docs/htmldocs/Samba3-Developers-Guide/vfs.html
r414 r599 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.7 4.0"><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" 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"><<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#id2559067">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559108">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2559434">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2559507">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559514">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2559659">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2559860">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559866">Upgrading from 2.2.* and 3.0alpha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2560270">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2560275">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2560295">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="id2559067"></a>The Samba (Posix) VFS layer</h2></div></div></div><p>While most of Samba deployments are done using POSIX-compatible1 <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 2 2 operating systems, there is clearly more to a file system than what is 3 3 required by POSIX when it comes to adopting semantics of NT file … … 25 25 to load several instances of the same VFS module with different 26 26 parameters. 27 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2559108"></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><p><span class="emphasis"><em>An initialization function</em></span> that is27 </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: 28 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>An initialization function</em></span> that is 29 29 called during the module load to register implemented 30 operations.</p></li><li ><p><span class="emphasis"><em>An operations table</em></span> representing a30 operations.</p></li><li class="listitem"><p><span class="emphasis"><em>An operations table</em></span> representing a 31 31 mapping between statically defined module functions and VFS layer 32 operations.</p></li><li ><p><span class="emphasis"><em>Module functions</em></span> that do actual32 operations.</p></li><li class="listitem"><p><span class="emphasis"><em>Module functions</em></span> that do actual 33 33 work.</p></li></ul></div><p> 34 34 </p><p>While this structure has been first applied to the VFS … … 50 50 </p><p>Therefore, initialization function passes three parameters to the 51 51 VFS registration function, <code class="literal">smb_register_vfs()</code> 52 </p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>interface version number</em></span>, as constant53 <code class="literal">SMB_VFS_INTERFACE_VERSION</code>, </p></li><li ><p><span class="emphasis"><em>module name</em></span>, under which Samba core54 will know it, and</p></li><li ><p><span class="emphasis"><em>an operations' table</em></span>.</p></li></ul></div><p>52 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>interface version number</em></span>, as constant 53 <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 54 will know it, and</p></li><li class="listitem"><p><span class="emphasis"><em>an operations' table</em></span>.</p></li></ul></div><p> 55 55 </p><p>The <span class="emphasis"><em>operations' table</em></span> defines which 56 56 functions in the module would correspond to specific VFS operations 57 57 and how those functions would co-operate with the rest of VFS 58 58 subsystem. Each operation could perform in a following ways: 59 </p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>transparent</em></span>, meaning that while59 </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>transparent</em></span>, meaning that while 60 60 operation is overriden, the module will still call a previous 61 61 implementation, before or after its own action. This mode is 62 62 indicated by the constant 63 <code class="literal">SMB_VFS_LAYER_TRANSPARENT</code>;</p></li><li ><p><span class="emphasis"><em>opaque</em></span>, for the implementations that63 <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 64 64 are terminating sequence of actions. For example, it is used to 65 65 implement POSIX operation on top of non-POSIX file system or even 66 66 not a file system at all, like a database for a personal audio 67 67 collection. Use constant <code class="literal">SMB_VFS_LAYER_OPAQUE</code> for 68 this mode;</p></li><li ><p><span class="emphasis"><em>splitter</em></span>, a way when some file system68 this mode;</p></li><li class="listitem"><p><span class="emphasis"><em>splitter</em></span>, a way when some file system 69 69 activity is done in addition to the transparently calling previous 70 70 implentation. This usually involves mangling the result of that call 71 71 before returning it back to the caller. This mode is selected by 72 <code class="literal">SMB_VFS_LAYER_SPLITTER</code> constant;</p></li><li ><p><span class="emphasis"><em>logger</em></span> does not change anything or72 <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 73 73 performs any additional VFS operations. When 74 74 <span class="emphasis"><em>logger</em></span> module acts, information about … … 77 77 describe this type of activity use constant 78 78 <code class="literal">SMB_VFS_LAYER_LOGGER</code>; 79 </p></li><li ><p>On contrary, <span class="emphasis"><em>scanner</em></span> module does call79 </p></li><li class="listitem"><p>On contrary, <span class="emphasis"><em>scanner</em></span> module does call 80 80 other VFS operations while processing the data that goes through the 81 81 system. This type of operation is indicated by the … … 187 187 188 188 ... 189 </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2559434"></a>Possible VFS operation layers</h3></div></div></div><p>189 </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> 190 190 These values are used by the VFS subsystem when building the conn->vfs 191 191 and conn->vfs_opaque structs for a connection with multiple VFS modules. … … 216 216 /* file activity like logging to files _inside_ samba VFS */ 217 217 } vfs_op_layer; 218 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2559507"></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="id2559514"></a>Initialization and registration</h3></div></div></div><p>218 </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> 219 219 As each Samba module a VFS module should have a 220 220 </p><pre class="programlisting">NTSTATUS vfs_example_init(void);</pre><p> function if it's staticly linked to samba or … … 256 256 return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples); 257 257 } 258 </pre></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2559659"></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.258 </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. 259 259 </p><pre class="programlisting"> 260 260 typedef struct vfs_handle_struct { … … 357 357 (tofd), (fsp), (fromfd), (header), (offset), (count))) 358 358 ... 359 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2559860"></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="id2559866"></a>Upgrading from 2.2.* and 3.0alpha modules</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p>359 </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> 360 360 Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions. 361 361 e.g. example_connect(connection_struct *conn, const char *service, const char *user); 362 362 -> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user); 363 </p></li><li ><p>363 </p></li><li class="listitem"><p> 364 364 Replace "default_vfs_ops." with "smb_vfs_next_". 365 365 e.g. default_vfs_ops.connect(conn, service, user); 366 366 -> smb_vfs_next_connect(conn, service, user); 367 </p></li><li ><p>367 </p></li><li class="listitem"><p> 368 368 Uppercase all "smb_vfs_next_*" functions. 369 369 e.g. smb_vfs_next_connect(conn, service, user); 370 370 -> SMB_VFS_NEXT_CONNECT(conn, service, user); 371 </p></li><li ><p>371 </p></li><li class="listitem"><p> 372 372 Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls. 373 373 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); 374 374 -> SMB_VFS_NEXT_CONNECT(handle, conn, service, user); 375 </p></li><li ><p>375 </p></li><li class="listitem"><p> 376 376 (Only for 2.2.* modules) 377 377 Convert the old struct vfs_ops example_ops to … … 462 462 }; 463 463 </pre><p> 464 </p></li><li ><p>464 </p></li><li class="listitem"><p> 465 465 Move the example_op_tuples[] array to the end of the file. 466 </p></li><li ><p>466 </p></li><li class="listitem"><p> 467 467 Add the init_module() function at the end of the file. 468 468 e.g. … … 473 473 } 474 474 </pre><p> 475 </p></li><li ><p>475 </p></li><li class="listitem"><p> 476 476 Check if your vfs_init() function does more then just prepare the vfs_ops structs or 477 477 remember the struct smb_vfs_handle_struct. 478 </p><table class="simplelist" border="0" summary="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().478 </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(). 479 479 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> 480 </p></li><li ><p>480 </p></li><li class="listitem"><p> 481 481 (Only for 3.0alpha* modules) 482 482 Check if your vfs_done() function contains needed code. 483 </p><table class="simplelist" border="0" summary="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().483 </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(). 484 484 </td></tr></table><p> 485 </p></li><li ><p>485 </p></li><li class="listitem"><p> 486 486 Check if you have any global variables left. 487 487 Decide if it wouldn't be better to have this data on a connection basis. 488 </p><table class="simplelist" border="0" summary="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>488 </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> 489 489 490 490 e.g. if you have such a struct: … … 604 604 } 605 605 </pre><p> 606 </p></li><li ><p>606 </p></li><li class="listitem"><p> 607 607 To make it easy to build 3rd party modules it would be useful to provide 608 608 configure.in, (configure), install.sh and Makefile.in with the module. … … 617 617 <code class="filename">configure.in</code> and <code class="filename">Makefile.in</code> scripts 618 618 for your module. 619 </p></li><li ><p>619 </p></li><li class="listitem"><p> 620 620 Compiling & Testing... 621 </p><table class="simplelist" border="0" summary="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>622 </p></li></ol></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2560270"></a>Some Notes</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2560275"></a>Implement TRANSPARENT functions</h3></div></div></div><p>621 </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> 622 </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> 623 623 Avoid writing functions like this: 624 624 … … 631 631 632 632 Overload only the functions you really need to! 633 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2560295"></a>Implement OPAQUE functions</h3></div></div></div><p>633 </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> 634 634 If you want to just implement a better version of a 635 635 default samba opaque function
Note:
See TracChangeset
for help on using the changeset viewer.
