docs-xml/Samba-Developers-Guide/vfs.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="vfs">
   4 <chapterinfo>
   5         <author>
   6                 <firstname>Alexander</firstname><surname>Bokovoy</surname>
   7                 <affiliation>
   8                         <address><email>ab@samba.org</email></address>
   9                 </affiliation>
  10         </author>
  11         <author>
  12                 <firstname>Stefan</firstname><surname>Metzmacher</surname>
  13                 <affiliation>
  14                         <address><email>metze@samba.org</email></address>
  15                 </affiliation>
  16         </author>
  17         <pubdate> 27 May 2003 </pubdate>
  18 </chapterinfo>
  19
  20 <title>VFS Modules</title>
  21
  22 <sect1>
  23 <title>The Samba (Posix) VFS layer</title>
  24
  25 <para>While most of Samba deployments are done using POSIX-compatible
  26 operating systems, there is clearly more to a file system than what is
  27 required by POSIX when it comes to adopting semantics of NT file
  28 system. Since Samba 2.2 all file-system related operations go through
  29 an abstraction layer for virtual file system (VFS) that is modelled
  30 after both POSIX and additional functions needed to transform NTFS
  31 semantics.
  32 </para>
  33
  34 <para>
  35 This abstraction layer now provides more features than a regular POSIX
  36 file system could fill in. It is not required that all of them should
  37 be implemented by your particular file system.  However, when those
  38 features are available, Samba would advertize them to a CIFS client
  39 and they might be used by an application and in case of Windows client
  40 that might mean a client expects even more additional functionality
  41 when it encounters those features. There is a practical reason to
  42 allow handling of this snowfall without modifying the Samba core and
  43 it is fulfilled by providing an infrastructure to dynamically load VFS
  44 modules at run time.
  45 </para>
  46
  47 <para>Each VFS module could implement a number of VFS operations. The
  48 way it does it is irrelevant, only two things actually matter: whether
  49 specific implementation wants to cooperate with other modules'
  50 implementations or not, and whether module needs to store additional
  51 information that is specific to a context it is operating in. Multiple
  52 VFS modules could be loaded at the same time and it is even possible
  53 to load several instances of the same VFS module with different
  54 parameters.
  55 </para>
  56
  57 <sect2>
  58 <title>The general interface</title>
  59
  60 <para>A VFS module has three major components:
  61 <itemizedlist>
  62         <listitem><para><emphasis>An initialization function</emphasis> that is
  63 called during the module load to register implemented
  64 operations.</para></listitem>
  65 <listitem><para><emphasis>An operations table</emphasis> representing a
  66 mapping between statically defined module functions and VFS layer
  67 operations.</para></listitem>
  68 <listitem><para><emphasis>Module functions</emphasis> that do actual
  69                 work.</para></listitem>
  70 </itemizedlist>
  71 </para>
  72
  73 <para>While this structure has been first applied to the VFS
  74 subsystem, it is now commonly used across all Samba 3 subsystems that
  75 support loadable modules. In fact, one module could provide a number
  76 of interfaces to different subsystems by exposing different
  77 <emphasis>operation tables</emphasis> through separate
  78 <emphasis>initialization functions</emphasis>.</para>
  79
  80 <para><emphasis>An initialization function</emphasis> is used to
  81 register module with Samba run-time. As Samba internal structures and
  82 API are changed over lifetime, each released version has a VFS
  83 interface version that is increased as VFS development progresses or
  84 any of underlying Samba structures are changed in binary-incompatible
  85 way. When VFS module is compiled in, VFS interface version of that
  86 Samba environment is embedded into the module's binary object and is
  87 checked by the Samba core upon module load. If VFS interface number
  88 reported by the module isn't the same Samba core knows about, version
  89 conflict is detected and module dropped to avoid any potential memory
  90 corruption when accessing (changed) Samba structures.
  91 </para>
  92
  93 <para>Therefore, initialization function passes three parameters to the
  94 VFS registration function, <literal>smb_register_vfs()</literal>
  95 <itemizedlist>
  96         <listitem><para><emphasis>interface version number</emphasis>, as constant
  97                         <literal>SMB_VFS_INTERFACE_VERSION</literal>, </para></listitem>
  98         <listitem><para><emphasis>module name</emphasis>, under which Samba core
  99                         will know it, and</para></listitem>
 100         <listitem><para><emphasis>an operations' table</emphasis>.</para></listitem>
 101 </itemizedlist>
 102 </para>
 103
 104 <para>The <emphasis>operations' table</emphasis> defines which
 105 functions in the module would correspond to specific VFS operations
 106 and how those functions would co-operate with the rest of VFS
 107 subsystem. Each operation could perform in a following ways:
 108 <itemizedlist>
 109         <listitem><para><emphasis>transparent</emphasis>, meaning that while
 110   operation is overridden, the module will still call a previous
 111   implementation, before or after its own action. This mode is
 112   indicated by the constant
 113   <literal>SMB_VFS_LAYER_TRANSPARENT</literal>;</para>
 114   </listitem>
 115   <listitem><para><emphasis>opaque</emphasis>, for the implementations that
 116   are terminating sequence of actions. For example, it is used to
 117   implement POSIX operation on top of non-POSIX file system or even
 118   not a file system at all, like a database for a personal audio
 119   collection. Use constant <literal>SMB_VFS_LAYER_OPAQUE</literal> for
 120   this mode;</para></listitem>
 121   <listitem><para><emphasis>splitter</emphasis>, a way when some file system
 122   activity is done in addition to the transparently calling previous
 123   implentation. This usually involves mangling the result of that call
 124   before returning it back to the caller. This mode is selected by
 125   <literal>SMB_VFS_LAYER_SPLITTER</literal> constant;</para></listitem>
 126   <listitem><para><emphasis>logger</emphasis> does not change anything or
 127   performs any additional VFS operations. When
 128   <emphasis>logger</emphasis> module acts, information about
 129   operations is logged somewhere using an external facility (or
 130   Samba's own debugging tools) but not the VFS layer. In order to
 131   describe this type of activity use constant
 132   <literal>SMB_VFS_LAYER_LOGGER</literal>;
 133   </para>
 134   </listitem>
 135   <listitem><para>On contrary, <emphasis>scanner</emphasis> module does call
 136   other VFS operations while processing the data that goes through the
 137   system. This type of operation is indicated by the
 138   <literal>SMB_VFS_LAYER_SCANNER</literal> constant.</para></listitem>
 139 </itemizedlist>
 140 </para>
 141
 142 <para>Fundamentally, there are three types:
 143 <emphasis>transparent</emphasis>, <emphasis>opaque</emphasis>, and
 144 <emphasis>logger</emphasis>. <emphasis>Splitter</emphasis> and
 145 <emphasis>scanner</emphasis> may confuse developers (and indeed they
 146 are confused as our experience has shown) but this separation is to
 147 better expose the nature of a module's actions. Most of modules
 148 developed so far are either one of those three fundamental types with
 149 transparent and opaque being prevalent.
 150 </para>
 151
 152 <para>
 153 Each VFS operation has a vfs_op_type, a function pointer and a handle
 154 pointer in the struct vfs_ops and tree macros to make it easier to
 155 call the operations.  (Take a look at
 156 <filename>include/vfs.h</filename> and
 157 <filename>include/vfs_macros.h</filename>.)
 158 </para>
 159
 160 <para><programlisting>
 161 typedef enum _vfs_op_type {
 162         SMB_VFS_OP_NOOP = -1,
 163
 164         ...
 165
 166         /* File operations */
 167
 168         SMB_VFS_OP_OPEN,
 169         SMB_VFS_OP_CLOSE,
 170         SMB_VFS_OP_READ,
 171         SMB_VFS_OP_WRITE,
 172         SMB_VFS_OP_LSEEK,
 173         SMB_VFS_OP_SENDFILE,
 174
 175         ...
 176
 177         SMB_VFS_OP_LAST
 178 } vfs_op_type;
 179 </programlisting></para>
 180
 181 <para>This struct contains the function and handle pointers for all operations.<programlisting>
 182 struct vfs_ops {
 183         struct vfs_fn_pointers {
 184                 ...
 185
 186                 /* File operations */
 187
 188                 int (*open)(struct vfs_handle_struct *handle,
 189                         struct connection_struct *conn,
 190                         const char *fname, int flags, mode_t mode);
 191                 int (*close)(struct vfs_handle_struct *handle,
 192                         struct files_struct *fsp, int fd);
 193                 ssize_t (*read)(struct vfs_handle_struct *handle,
 194                         struct files_struct *fsp, int fd, void *data, size_t n);
 195                 ssize_t (*write)(struct vfs_handle_struct *handle,
 196                         struct files_struct *fsp, int fd,
 197                         const void *data, size_t n);
 198                 SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle,
 199                         struct files_struct *fsp, int fd,
 200                         SMB_OFF_T offset, int whence);
 201                 ssize_t (*sendfile)(struct vfs_handle_struct *handle,
 202                         int tofd, files_struct *fsp, int fromfd,
 203                         const DATA_BLOB *header, SMB_OFF_T offset, size_t count);
 204
 205                 ...
 206         } ops;
 207
 208         struct vfs_handles_pointers {
 209                 ...
 210
 211                 /* File operations */
 212
 213                 struct vfs_handle_struct *open;
 214                 struct vfs_handle_struct *close;
 215                 struct vfs_handle_struct *read;
 216                 struct vfs_handle_struct *write;
 217                 struct vfs_handle_struct *lseek;
 218                 struct vfs_handle_struct *sendfile;
 219
 220                 ...
 221         } handles;
 222 };
 223 </programlisting></para>
 224
 225 <para>
 226 This macros SHOULD be used to call any vfs operation.
 227 DO NOT ACCESS conn-&gt;vfs.ops.* directly !!!
 228 <programlisting>
 229 ...
 230
 231 /* File operations */
 232 #define SMB_VFS_OPEN(conn, fname, flags, mode) \
 233         ((conn)-&gt;vfs.ops.open((conn)-&gt;vfs.handles.open,\
 234          (conn), (fname), (flags), (mode)))
 235 #define SMB_VFS_CLOSE(fsp, fd) \
 236         ((fsp)-&gt;conn-&gt;vfs.ops.close(\
 237         (fsp)-&gt;conn-&gt;vfs.handles.close, (fsp), (fd)))
 238 #define SMB_VFS_READ(fsp, fd, data, n) \
 239         ((fsp)-&gt;conn-&gt;vfs.ops.read(\
 240         (fsp)-&gt;conn-&gt;vfs.handles.read,\
 241          (fsp), (fd), (data), (n)))
 242 #define SMB_VFS_WRITE(fsp, fd, data, n) \
 243         ((fsp)-&gt;conn-&gt;vfs.ops.write(\
 244         (fsp)-&gt;conn-&gt;vfs.handles.write,\
 245          (fsp), (fd), (data), (n)))
 246 #define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
 247         ((fsp)-&gt;conn-&gt;vfs.ops.lseek(\
 248         (fsp)-&gt;conn-&gt;vfs.handles.lseek,\
 249          (fsp), (fd), (offset), (whence)))
 250 #define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
 251         ((fsp)-&gt;conn-&gt;vfs.ops.sendfile(\
 252         (fsp)-&gt;conn-&gt;vfs.handles.sendfile,\
 253          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 254
 255 ...
 256 </programlisting></para>
 257
 258 </sect2>
 259
 260 <sect2>
 261 <title>Possible VFS operation layers</title>
 262
 263 <para>
 264 These values are used by the VFS subsystem when building the conn-&gt;vfs
 265 and conn-&gt;vfs_opaque structs for a connection with multiple VFS modules.
 266 Internally, Samba differentiates only opaque and transparent layers at this process.
 267 Other types are used for providing better diagnosing facilities.
 268 </para>
 269
 270 <para>
 271 Most modules will provide transparent layers. Opaque layer is for modules
 272 which implement actual file system calls (like DB-based VFS). For example,
 273 default POSIX VFS which is built in into Samba is an opaque VFS module.
 274 </para>
 275
 276 <para>
 277 Other layer types (logger, splitter, scanner) were designed to provide different
 278 degree of transparency and for diagnosing VFS module behaviour.
 279 </para>
 280
 281 <para>
 282 Each module can implement several layers at the same time provided that only
 283 one layer is used per each operation.
 284 </para>
 285
 286 <para><programlisting>
 287 typedef enum _vfs_op_layer {
 288         SMB_VFS_LAYER_NOOP = -1,        /* - For using in VFS module to indicate end of array */
 289                                         /*   of operations description */
 290         SMB_VFS_LAYER_OPAQUE = 0,       /* - Final level, does not call anything beyond itself */
 291         SMB_VFS_LAYER_TRANSPARENT,      /* - Normal operation, calls underlying layer after */
 292                                         /*   possibly changing passed data */
 293         SMB_VFS_LAYER_LOGGER,           /* - Logs data, calls underlying layer, logging may not */
 294                                         /*   use Samba VFS */
 295         SMB_VFS_LAYER_SPLITTER,         /* - Splits operation, calls underlying layer _and_ own facility, */
 296                                         /*   then combines result */
 297         SMB_VFS_LAYER_SCANNER           /* - Checks data and possibly initiates additional */
 298                                         /*   file activity like logging to files _inside_ samba VFS */
 299 } vfs_op_layer;
 300 </programlisting></para>
 301
 302 </sect2>
 303
 304 </sect1>
 305
 306 <sect1>
 307 <title>The Interaction between the Samba VFS subsystem and the modules</title>
 308
 309 <sect2>
 310 <title>Initialization and registration</title>
 311
 312 <para>
 313 As each Samba module a VFS module should have a
 314 <programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or
 315 <programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module.
 316 </para>
 317
 318 <para>
 319 This should be the only non static function inside the module.
 320 Global variables should also be static!
 321 </para>
 322
 323 <para>
 324 The module should register its functions via the
 325 <programlisting>
 326 NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
 327 </programlisting> function.
 328 </para>
 329
 330 <variablelist>
 331
 332 <varlistentry><term>version</term>
 333 <listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
 334 </varlistentry>
 335
 336 <varlistentry><term>name</term>
 337 <listitem><para>this is the name witch can be listed in the
 338 <command>vfs objects</command> parameter to use this module.</para></listitem>
 339 </varlistentry>
 340
 341 <varlistentry><term>vfs_op_tuples</term>
 342 <listitem><para>
 343 this is an array of vfs_op_tuple's.
 344 (vfs_op_tuples is descripted in details below.)
 345 </para></listitem>
 346 </varlistentry>
 347
 348 </variablelist>
 349
 350 <para>
 351 For each operation the module wants to provide it has a entry in the
 352 vfs_op_tuple array.
 353 </para>
 354
 355 <programlisting>
 356 typedef struct _vfs_op_tuple {
 357         void* op;
 358         vfs_op_type type;
 359         vfs_op_layer layer;
 360 } vfs_op_tuple;
 361 </programlisting>
 362
 363 <variablelist>
 364
 365 <varlistentry><term>op</term>
 366 <listitem><para>the function pointer to the specified function.</para></listitem>
 367 </varlistentry>
 368
 369 <varlistentry><term>type</term>
 370 <listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
 371 </varlistentry>
 372
 373 <varlistentry><term>layer</term>
 374 <listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
 375 </varlistentry>
 376
 377 </variablelist>
 378
 379 <para>A simple example:</para>
 380
 381 <programlisting>
 382 static vfs_op_tuple example_op_tuples[] = {
 383         {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
 384         {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
 385
 386         {SMB_VFS_OP(example_rename),    SMB_VFS_OP_RENAME,      SMB_VFS_LAYER_OPAQUE},
 387
 388         /* This indicates the end of the array */
 389         {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
 390 };
 391
 392 NTSTATUS init_module(void)
 393 {
 394         return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, &quot;example&quot;, example_op_tuples);
 395 }
 396 </programlisting>
 397
 398 </sect2>
 399
 400 <sect2>
 401 <title>How the Modules handle per connection data</title>
 402
 403 <para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
 404 </para>
 405
 406 <programlisting>
 407 typedef struct vfs_handle_struct {
 408         struct vfs_handle_struct  *next, *prev;
 409         const char *param;
 410         struct vfs_ops vfs_next;
 411         struct connection_struct *conn;
 412         void *data;
 413         void (*free_data)(void **data);
 414 } vfs_handle_struct;
 415 </programlisting>
 416
 417 <variablelist>
 418
 419 <varlistentry><term>param</term>
 420 <listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para>
 421 <para>e.g. for 'vfs objects = example:test' param would be &quot;test&quot;.</para></listitem>
 422 </varlistentry>
 423
 424 <varlistentry><term>vfs_next</term>
 425 <listitem><para>This vfs_ops struct contains the information for calling the next module operations.
 426 Use the SMB_VFS_NEXT_* macros to call a next module operations and
 427 don't access handle-&gt;vfs_next.ops.* directly!</para></listitem>
 428 </varlistentry>
 429
 430 <varlistentry><term>conn</term>
 431 <listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
 432 </varlistentry>
 433
 434 <varlistentry><term>data</term>
 435 <listitem><para>This is a pointer for holding module private data.
 436 You can alloc data with connection life time on the handle-&gt;conn-&gt;mem_ctx TALLOC_CTX.
 437 But you can also manage the memory allocation yourself.</para></listitem>
 438 </varlistentry>
 439
 440 <varlistentry><term>free_data</term>
 441 <listitem><para>This is a function pointer to a function that free's the module private data.
 442 If you talloc your private data on the TALLOC_CTX handle-&gt;conn-&gt;mem_ctx,
 443 you can set this function pointer to NULL.</para></listitem>
 444 </varlistentry>
 445
 446 </variablelist>
 447
 448 <para>Some useful MACROS for handle private data.
 449 </para>
 450
 451 <programlisting>
 452 #define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
 453         if (!(handle)||((datap=(type *)(handle)-&gt;data)==NULL)) { \
 454                 DEBUG(0,(&quot;%s() failed to get vfs_handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
 455                 ret; \
 456         } \
 457 }
 458
 459 #define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
 460         if (!(handle)) { \
 461                 DEBUG(0,(&quot;%s() failed to set handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
 462                 ret; \
 463         } else { \
 464                 if ((handle)-&gt;free_data) { \
 465                         (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
 466                 } \
 467                 (handle)-&gt;data = (void *)datap; \
 468                 (handle)-&gt;free_data = free_fn; \
 469         } \
 470 }
 471
 472 #define SMB_VFS_HANDLE_FREE_DATA(handle) { \
 473         if ((handle) &amp;&amp; (handle)-&gt;free_data) { \
 474                 (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
 475         } \
 476 }
 477 </programlisting>
 478
 479 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
 480
 481 <para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
 482 </para>
 483
 484 <programlisting>
 485 ...
 486 /* File operations */
 487 #define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
 488         ((conn)-&gt;vfs_opaque.ops.open(\
 489         (conn)-&gt;vfs_opaque.handles.open,\
 490          (conn), (fname), (flags), (mode)))
 491 #define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
 492         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.close(\
 493         (fsp)-&gt;conn-&gt;vfs_opaque.handles.close,\
 494          (fsp), (fd)))
 495 #define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
 496         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.read(\
 497         (fsp)-&gt;conn-&gt;vfs_opaque.handles.read,\
 498          (fsp), (fd), (data), (n)))
 499 #define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
 500         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.write(\
 501         (fsp)-&gt;conn-&gt;vfs_opaque.handles.write,\
 502          (fsp), (fd), (data), (n)))
 503 #define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
 504         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.lseek(\
 505         (fsp)-&gt;conn-&gt;vfs_opaque.handles.lseek,\
 506          (fsp), (fd), (offset), (whence)))
 507 #define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
 508         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.sendfile(\
 509         (fsp)-&gt;conn-&gt;vfs_opaque.handles.sendfile,\
 510          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 511 ...
 512 </programlisting>
 513
 514 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
 515
 516 <para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
 517 </para>
 518
 519 <programlisting>
 520 ...
 521 /* File operations */
 522 #define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
 523         ((handle)-&gt;vfs_next.ops.open(\
 524         (handle)-&gt;vfs_next.handles.open,\
 525          (conn), (fname), (flags), (mode)))
 526 #define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
 527         ((handle)-&gt;vfs_next.ops.close(\
 528         (handle)-&gt;vfs_next.handles.close,\
 529          (fsp), (fd)))
 530 #define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
 531         ((handle)-&gt;vfs_next.ops.read(\
 532         (handle)-&gt;vfs_next.handles.read,\
 533          (fsp), (fd), (data), (n)))
 534 #define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
 535         ((handle)-&gt;vfs_next.ops.write(\
 536         (handle)-&gt;vfs_next.handles.write,\
 537          (fsp), (fd), (data), (n)))
 538 #define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
 539         ((handle)-&gt;vfs_next.ops.lseek(\
 540         (handle)-&gt;vfs_next.handles.lseek,\
 541          (fsp), (fd), (offset), (whence)))
 542 #define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
 543         ((handle)-&gt;vfs_next.ops.sendfile(\
 544         (handle)-&gt;vfs_next.handles.sendfile,\
 545          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 546 ...
 547 </programlisting>
 548
 549 </sect2>
 550
 551 </sect1>
 552
 553 <sect1>
 554 <title>Upgrading to the New VFS Interface</title>
 555
 556 <sect2>
 557 <title>Upgrading from 2.2.* and 3.0alpha modules</title>
 558
 559 <orderedlist>
 560 <listitem><para>
 561 Add &quot;vfs_handle_struct *handle, &quot; as first parameter to all vfs operation functions.
 562 e.g. example_connect(connection_struct *conn, const char *service, const char *user);
 563 -&gt;   example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
 564 </para></listitem>
 565
 566 <listitem><para>
 567 Replace &quot;default_vfs_ops.&quot; with &quot;smb_vfs_next_&quot;.
 568 e.g. default_vfs_ops.connect(conn, service, user);
 569 -&gt;   smb_vfs_next_connect(conn, service, user);
 570 </para></listitem>
 571
 572 <listitem><para>
 573 Uppercase all &quot;smb_vfs_next_*&quot; functions.
 574 e.g. smb_vfs_next_connect(conn, service, user);
 575 -&gt;   SMB_VFS_NEXT_CONNECT(conn, service, user);
 576 </para></listitem>
 577
 578 <listitem><para>
 579 Add &quot;handle, &quot; as first parameter to all SMB_VFS_NEXT_*() calls.
 580 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
 581 -&gt;   SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
 582 </para></listitem>
 583
 584 <listitem><para>
 585 (Only for 2.2.* modules)
 586 Convert the old struct vfs_ops example_ops to
 587 a vfs_op_tuple example_op_tuples[] array.
 588 e.g.
 589 <programlisting>
 590 struct vfs_ops example_ops = {
 591         /* Disk operations */
 592         example_connect,                /* connect */
 593         example_disconnect,             /* disconnect */
 594         NULL,                           /* disk free *
 595         /* Directory operations */
 596         NULL,                           /* opendir */
 597         NULL,                           /* readdir */
 598         NULL,                           /* mkdir */
 599         NULL,                           /* rmdir */
 600         NULL,                           /* closedir */
 601         /* File operations */
 602         NULL,                           /* open */
 603         NULL,                           /* close */
 604         NULL,                           /* read  */
 605         NULL,                           /* write */
 606         NULL,                           /* lseek */
 607         NULL,                           /* sendfile */
 608         NULL,                           /* rename */
 609         NULL,                           /* fsync */
 610         example_stat,                   /* stat  */
 611         example_fstat,                  /* fstat */
 612         example_lstat,                  /* lstat */
 613         NULL,                           /* unlink */
 614         NULL,                           /* chmod */
 615         NULL,                           /* fchmod */
 616         NULL,                           /* chown */
 617         NULL,                           /* fchown */
 618         NULL,                           /* chdir */
 619         NULL,                           /* getwd */
 620         NULL,                           /* utime */
 621         NULL,                           /* ftruncate */
 622         NULL,                           /* lock */
 623         NULL,                           /* symlink */
 624         NULL,                           /* readlink */
 625         NULL,                           /* link */
 626         NULL,                           /* mknod */
 627         NULL,                           /* realpath */
 628         NULL,                           /* fget_nt_acl */
 629         NULL,                           /* get_nt_acl */
 630         NULL,                           /* fset_nt_acl */
 631         NULL,                           /* set_nt_acl */
 632
 633         NULL,                           /* chmod_acl */
 634         NULL,                           /* fchmod_acl */
 635
 636         NULL,                           /* sys_acl_get_entry */
 637         NULL,                           /* sys_acl_get_tag_type */
 638         NULL,                           /* sys_acl_get_permset */
 639         NULL,                           /* sys_acl_get_qualifier */
 640         NULL,                           /* sys_acl_get_file */
 641         NULL,                           /* sys_acl_get_fd */
 642         NULL,                           /* sys_acl_clear_perms */
 643         NULL,                           /* sys_acl_add_perm */
 644         NULL,                           /* sys_acl_to_text */
 645         NULL,                           /* sys_acl_init */
 646         NULL,                           /* sys_acl_create_entry */
 647         NULL,                           /* sys_acl_set_tag_type */
 648         NULL,                           /* sys_acl_set_qualifier */
 649         NULL,                           /* sys_acl_set_permset */
 650         NULL,                           /* sys_acl_valid */
 651         NULL,                           /* sys_acl_set_file */
 652         NULL,                           /* sys_acl_set_fd */
 653         NULL,                           /* sys_acl_delete_def_file */
 654         NULL,                           /* sys_acl_get_perm */
 655         NULL,                           /* sys_acl_free_text */
 656         NULL,                           /* sys_acl_free_acl */
 657         NULL                            /* sys_acl_free_qualifier */
 658 };
 659 </programlisting>
 660 -&gt;
 661 <programlisting>
 662 static vfs_op_tuple example_op_tuples[] = {
 663         {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
 664         {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
 665
 666         {SMB_VFS_OP(example_fstat),     SMB_VFS_OP_FSTAT,       SMB_VFS_LAYER_TRANSPARENT},
 667         {SMB_VFS_OP(example_stat),              SMB_VFS_OP_STAT,        SMB_VFS_LAYER_TRANSPARENT},
 668         {SMB_VFS_OP(example_lstat),     SMB_VFS_OP_LSTAT,       SMB_VFS_LAYER_TRANSPARENT},
 669
 670         {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
 671 };
 672 </programlisting>
 673 </para></listitem>
 674
 675 <listitem><para>
 676 Move the example_op_tuples[] array to the end of the file.
 677 </para></listitem>
 678
 679 <listitem><para>
 680 Add the init_module() function at the end of the file.
 681 e.g.
 682 <programlisting>
 683 NTSTATUS init_module(void)
 684 {
 685         return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,&quot;example&quot;,example_op_tuples);
 686 }
 687 </programlisting>
 688 </para></listitem>
 689
 690 <listitem><para>
 691 Check if your vfs_init() function does more then just prepare the vfs_ops structs or
 692 remember the struct smb_vfs_handle_struct.
 693 <simplelist>
 694 <member>If NOT you can remove the vfs_init() function.</member>
 695 <member>If YES decide if you want to move the code to the example_connect() operation or to the init_module(). And then remove vfs_init().
 696   e.g. a debug class registration should go into init_module() and the allocation of private data should go to example_connect().</member>
 697 </simplelist>
 698 </para></listitem>
 699
 700 <listitem><para>
 701 (Only for 3.0alpha* modules)
 702 Check if your vfs_done() function contains needed code.
 703 <simplelist>
 704 <member>If NOT you can remove the vfs_done() function.</member>
 705 <member>If YES decide if you can move the code to the example_disconnect() operation. Otherwise register a SMB_EXIT_EVENT with smb_register_exit_event(); (Described in the <link linkend="modules">modules section</link>) And then remove vfs_done(). e.g. the freeing of private data should go to example_disconnect().
 706 </member>
 707 </simplelist>
 708 </para></listitem>
 709
 710 <listitem><para>
 711 Check if you have any global variables left.
 712 Decide if it wouldn't be better to have this data on a connection basis.
 713 <simplelist>
 714   <member>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</member>
 715   <member>If YES pack all this data into a struct. You can use handle-&gt;data to point to such a struct on a per connection basis.</member>
 716 </simplelist>
 717
 718   e.g. if you have such a struct:
 719 <programlisting>
 720 struct example_privates {
 721         char *some_string;
 722         int db_connection;
 723 };
 724 </programlisting>
 725 first way of doing it:
 726 <programlisting>
 727 static int example_connect(vfs_handle_struct *handle,
 728         connection_struct *conn, const char *service,
 729         const char* user)
 730 {
 731         struct example_privates *data = NULL;
 732
 733         /* alloc our private data */
 734         data = (struct example_privates *)talloc_zero(conn-&gt;mem_ctx, sizeof(struct example_privates));
 735         if (!data) {
 736                 DEBUG(0,(&quot;talloc_zero() failed\n&quot;));
 737                 return -1;
 738         }
 739
 740         /* init out private data */
 741         data-&gt;some_string = talloc_strdup(conn-&gt;mem_ctx,&quot;test&quot;);
 742         if (!data-&gt;some_string) {
 743                 DEBUG(0,(&quot;talloc_strdup() failed\n&quot;));
 744                 return -1;
 745         }
 746
 747         data-&gt;db_connection = open_db_conn();
 748
 749         /* and now store the private data pointer in handle-&gt;data
 750          * we don't need to specify a free_function here because
 751          * we use the connection TALLOC context.
 752          * (return -1 if something failed.)
 753          */
 754         VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
 755
 756         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
 757 }
 758
 759 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 760 {
 761         struct example_privates *data = NULL;
 762
 763         /* get the pointer to our private data
 764          * return -1 if something failed
 765          */
 766         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
 767
 768         /* do something here...*/
 769         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
 770
 771         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 772 }
 773 </programlisting>
 774 second way of doing it:
 775 <programlisting>
 776 static void free_example_privates(void **datap)
 777 {
 778         struct example_privates *data = (struct example_privates *)*datap;
 779
 780         SAFE_FREE(data-&gt;some_string);
 781         SAFE_FREE(data);
 782
 783         *datap = NULL;
 784
 785         return;
 786 }
 787
 788 static int example_connect(vfs_handle_struct *handle,
 789         connection_struct *conn, const char *service,
 790         const char* user)
 791 {
 792         struct example_privates *data = NULL;
 793
 794         /* alloc our private data */
 795         data = (struct example_privates *)malloc(sizeof(struct example_privates));
 796         if (!data) {
 797                 DEBUG(0,(&quot;malloc() failed\n&quot;));
 798                 return -1;
 799         }
 800
 801         /* init out private data */
 802         data-&gt;some_string = strdup(&quot;test&quot;);
 803         if (!data-&gt;some_string) {
 804                 DEBUG(0,(&quot;strdup() failed\n&quot;));
 805                 return -1;
 806         }
 807
 808         data-&gt;db_connection = open_db_conn();
 809
 810         /* and now store the private data pointer in handle-&gt;data
 811          * we need to specify a free_function because we used malloc() and strdup().
 812          * (return -1 if something failed.)
 813          */
 814         SMB_VFS_HANDLE_SET_DATA(handle, data, free_example_privates, struct example_privates, return -1);
 815
 816         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
 817 }
 818
 819 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 820 {
 821         struct example_privates *data = NULL;
 822
 823         /* get the pointer to our private data
 824          * return -1 if something failed
 825          */
 826         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
 827
 828         /* do something here...*/
 829         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
 830
 831         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 832 }
 833 </programlisting>
 834 </para></listitem>
 835
 836 <listitem><para>
 837 To make it easy to build 3rd party modules it would be useful to provide
 838 configure.in, (configure), install.sh and Makefile.in with the module.
 839 (Take a look at the example in <filename>examples/VFS</filename>.)
 840 </para>
 841
 842 <para>
 843 The configure script accepts <option>--with-samba-source</option> to specify
 844 the path to the samba source tree.
 845 It also accept <option>--enable-developer</option> which lets the compiler
 846 give you more warnings.
 847 </para>
 848
 849 <para>
 850 The idea is that you can extend this
 851 <filename>configure.in</filename> and <filename>Makefile.in</filename> scripts
 852 for your module.
 853 </para></listitem>
 854
 855 <listitem><para>
 856 Compiling &amp; Testing...
 857 <simplelist>
 858 <member><userinput>./configure <option>--enable-developer</option></userinput> ...</member>
 859 <member><userinput>make</userinput></member>
 860 <member>Try to fix all compiler warnings</member>
 861 <member><userinput>make</userinput></member>
 862 <member>Testing, Testing, Testing ...</member>
 863 </simplelist>
 864 </para></listitem>
 865 </orderedlist>
 866 </sect2>
 867
 868 </sect1>
 869
 870 <sect1>
 871 <title>Some Notes</title>
 872
 873 <sect2>
 874 <title>Implement TRANSPARENT functions</title>
 875
 876 <para>
 877 Avoid writing functions like this:
 878
 879 <programlisting>
 880 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 881 {
 882         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 883 }
 884 </programlisting>
 885
 886 Overload only the functions you really need to!
 887 </para>
 888
 889 </sect2>
 890
 891 <sect2>
 892 <title>Implement OPAQUE functions</title>
 893
 894 <para>
 895 If you want to just implement a better version of a
 896 default samba opaque function
 897 (e.g. like a disk_free() function for a special filesystem)
 898 it's ok to just overload that specific function.
 899 </para>
 900
 901 <para>
 902 If you want to implement a database filesystem or
 903 something different from a posix filesystem.
 904 Make sure that you overload every vfs operation!!!
 905 </para>
 906 <para>
 907 Functions your FS does not support should be overloaded by something like this:
 908 e.g. for a readonly filesystem.
 909 </para>
 910
 911 <programlisting>
 912 static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
 913                         char *oldname, char *newname)
 914 {
 915         DEBUG(10,(&quot;function rename() not allowed on vfs 'example'\n&quot;));
 916         errno = ENOSYS;
 917         return -1;
 918 }
 919 </programlisting>
 920
 921 </sect2>
 922
 923 </sect1>
 924
 925 </chapter>