- Timestamp:
- Mar 1, 2010, 3:05:48 PM (15 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
branches/samba-3.3.x/docs/htmldocs/Samba3-Developers-Guide/vfs.html
r368 r411 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 5.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#id2565148">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2565189">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2565500">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2565561">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2565568">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2565713">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2565913">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2565919">Upgrading from 2.2.* and 3.0alpha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2566324">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2566329">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2566349">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="id2565148"></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.74.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#id2559076">The Samba (Posix) VFS layer</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559117">The general interface</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2559428">Possible VFS operation layers</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2559489">The Interaction between the Samba VFS subsystem and the modules</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559495">Initialization and registration</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2559640">How the Modules handle per connection data</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2559841">Upgrading to the New VFS Interface</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2559847">Upgrading from 2.2.* and 3.0alpha modules</a></span></dt></dl></dd><dt><span class="sect1"><a href="vfs.html#id2560251">Some Notes</a></span></dt><dd><dl><dt><span class="sect2"><a href="vfs.html#id2560257">Implement TRANSPARENT functions</a></span></dt><dt><span class="sect2"><a href="vfs.html#id2560276">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="id2559076"></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" title="The general interface"><div class="titlepage"><div><div><h3 class="title"><a name="id2565189"></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"><span class="emphasis"><em>An initialization function</em></span> that is27 </p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2559117"></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 29 29 called during the module load to register implemented 30 operations.</li><li class="listitem"><span class="emphasis"><em>An operations table</em></span> representing a30 operations.</li><li><span class="emphasis"><em>An operations table</em></span> representing a 31 31 mapping between statically defined module functions and VFS layer 32 operations.</li><li class="listitem"><span class="emphasis"><em>Module functions</em></span> that do actual32 operations.</li><li><span class="emphasis"><em>Module functions</em></span> that do actual 33 33 work.</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 class="itemizedlist" type="disc"><li class="listitem"><span class="emphasis"><em>interface version number</em></span>, as constant53 <code class="literal">SMB_VFS_INTERFACE_VERSION</code>, </li><li class="listitem"><span class="emphasis"><em>module name</em></span>, under which Samba core54 will know it, and</li><li class="listitem"><span class="emphasis"><em>an operations' table</em></span>.</li></ul></div><p>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 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 class="itemizedlist" type="disc"><li class="listitem"><span class="emphasis"><em>transparent</em></span>, meaning that while59 </p><div class="itemizedlist"><ul type="disc"><li><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 63 <code class="literal">SMB_VFS_LAYER_TRANSPARENT</code>; 64 </li><li class="listitem"><span class="emphasis"><em>opaque</em></span>, for the implementations that64 </li><li><span class="emphasis"><em>opaque</em></span>, for the implementations that 65 65 are terminating sequence of actions. For example, it is used to 66 66 implement POSIX operation on top of non-POSIX file system or even 67 67 not a file system at all, like a database for a personal audio 68 68 collection. Use constant <code class="literal">SMB_VFS_LAYER_OPAQUE</code> for 69 this mode;</li><li class="listitem"><span class="emphasis"><em>splitter</em></span>, a way when some file system69 this mode;</li><li><span class="emphasis"><em>splitter</em></span>, a way when some file system 70 70 activity is done in addition to the transparently calling previous 71 71 implentation. This usually involves mangling the result of that call 72 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 class="listitem"><span class="emphasis"><em>logger</em></span> does not change anything or73 <code class="literal">SMB_VFS_LAYER_SPLITTER</code> constant;</li><li><span class="emphasis"><em>logger</em></span> does not change anything or 74 74 performs any additional VFS operations. When 75 75 <span class="emphasis"><em>logger</em></span> module acts, information about … … 78 78 describe this type of activity use constant 79 79 <code class="literal">SMB_VFS_LAYER_LOGGER</code>; 80 </li><li class="listitem">On contrary, <span class="emphasis"><em>scanner</em></span> module does call80 </li><li>On contrary, <span class="emphasis"><em>scanner</em></span> module does call 81 81 other VFS operations while processing the data that goes through the 82 82 system. This type of operation is indicated by the … … 188 188 189 189 ... 190 </pre></div><div class="sect2" title="Possible VFS operation layers"><div class="titlepage"><div><div><h3 class="title"><a name="id2565500"></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="id2559428"></a>Possible VFS operation layers</h3></div></div></div><p> 191 191 These values are used by the VFS subsystem when building the conn->vfs 192 192 and conn->vfs_opaque structs for a connection with multiple VFS modules. … … 217 217 /* file activity like logging to files _inside_ samba VFS */ 218 218 } vfs_op_layer; 219 </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="id2565561"></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="id2565568"></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="id2559489"></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="id2559495"></a>Initialization and registration</h3></div></div></div><p> 220 220 As each Samba module a VFS module should have a 221 221 </p><pre class="programlisting">NTSTATUS vfs_example_init(void);</pre><p> function if it's staticly linked to samba or … … 257 257 return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples); 258 258 } 259 </pre></div><div class="sect2" title="How the Modules handle per connection data"><div class="titlepage"><div><div><h3 class="title"><a name="id2565713"></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="id2559640"></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. 260 260 </p><pre class="programlisting"> 261 261 typedef struct vfs_handle_struct { … … 358 358 (tofd), (fsp), (fromfd), (header), (offset), (count))) 359 359 ... 360 </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="id2565913"></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="id2565919"></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 </pre></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2559841"></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="id2559847"></a>Upgrading from 2.2.* and 3.0alpha modules</h3></div></div></div><div class="orderedlist"><ol type="1"><li><p> 361 361 Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions. 362 362 e.g. example_connect(connection_struct *conn, const char *service, const char *user); 363 363 -> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user); 364 </p></li><li class="listitem"><p>364 </p></li><li><p> 365 365 Replace "default_vfs_ops." with "smb_vfs_next_". 366 366 e.g. default_vfs_ops.connect(conn, service, user); 367 367 -> smb_vfs_next_connect(conn, service, user); 368 </p></li><li class="listitem"><p>368 </p></li><li><p> 369 369 Uppercase all "smb_vfs_next_*" functions. 370 370 e.g. smb_vfs_next_connect(conn, service, user); 371 371 -> SMB_VFS_NEXT_CONNECT(conn, service, user); 372 </p></li><li class="listitem"><p>372 </p></li><li><p> 373 373 Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls. 374 374 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); 375 375 -> SMB_VFS_NEXT_CONNECT(handle, conn, service, user); 376 </p></li><li class="listitem"><p>376 </p></li><li><p> 377 377 (Only for 2.2.* modules) 378 378 Convert the old struct vfs_ops example_ops to … … 463 463 }; 464 464 </pre><p> 465 </p></li><li class="listitem"><p>465 </p></li><li><p> 466 466 Move the example_op_tuples[] array to the end of the file. 467 </p></li><li class="listitem"><p>467 </p></li><li><p> 468 468 Add the init_module() function at the end of the file. 469 469 e.g. … … 474 474 } 475 475 </pre><p> 476 </p></li><li class="listitem"><p>476 </p></li><li><p> 477 477 Check if your vfs_init() function does more then just prepare the vfs_ops structs or 478 478 remember the struct smb_vfs_handle_struct. 479 </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 </p><table class="simplelist" border="0" summary="Simple list"><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(). 480 480 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> 481 </p></li><li class="listitem"><p>481 </p></li><li><p> 482 482 (Only for 3.0alpha* modules) 483 483 Check if your vfs_done() function contains needed code. 484 </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 </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(). 485 485 </td></tr></table><p> 486 </p></li><li class="listitem"><p>486 </p></li><li><p> 487 487 Check if you have any global variables left. 488 488 Decide if it wouldn't be better to have this data on a connection basis. 489 </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 </p><table class="simplelist" border="0" summary="Simple list"><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> 490 490 491 491 e.g. if you have such a struct: … … 605 605 } 606 606 </pre><p> 607 </p></li><li class="listitem"><p>607 </p></li><li><p> 608 608 To make it easy to build 3rd party modules it would be useful to provide 609 609 configure.in, (configure), install.sh and Makefile.in with the module. … … 618 618 <code class="filename">configure.in</code> and <code class="filename">Makefile.in</code> scripts 619 619 for your module. 620 </p></li><li class="listitem"><p>620 </p></li><li><p> 621 621 Compiling & Testing... 622 </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>623 </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="id2566324"></a>Some Notes</h2></div></div></div><div class="sect2" title="Implement TRANSPARENT functions"><div class="titlepage"><div><div><h3 class="title"><a name="id2566329"></a>Implement TRANSPARENT functions</h3></div></div></div><p>622 </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> 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="id2560251"></a>Some Notes</h2></div></div></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id2560257"></a>Implement TRANSPARENT functions</h3></div></div></div><p> 624 624 Avoid writing functions like this: 625 625 … … 632 632 633 633 Overload only the functions you really need to! 634 </p></div><div class="sect2" title="Implement OPAQUE functions"><div class="titlepage"><div><div><h3 class="title"><a name="id2566349"></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="id2560276"></a>Implement OPAQUE functions</h3></div></div></div><p> 635 635 If you want to just implement a better version of a 636 636 default samba opaque function
Note:
See TracChangeset
for help on using the changeset viewer.
