docs/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 <sect2>
  26 <title>The general interface</title>
  27
  28 <para>
  29 Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the
  30 struct vfs_ops and tree macros to make it easier to call the operations.
  31 (Take a look at <filename>include/vfs.h</filename> and <filename>include/vfs_macros.h</filename>.)
  32 </para>
  33
  34 <para><programlisting>
  35 typedef enum _vfs_op_type {
  36         SMB_VFS_OP_NOOP = -1,
  37
  38         ...
  39
  40         /* File operations */
  41
  42         SMB_VFS_OP_OPEN,
  43         SMB_VFS_OP_CLOSE,
  44         SMB_VFS_OP_READ,
  45         SMB_VFS_OP_WRITE,
  46         SMB_VFS_OP_LSEEK,
  47         SMB_VFS_OP_SENDFILE,
  48
  49         ...
  50
  51         SMB_VFS_OP_LAST
  52 } vfs_op_type;
  53 </programlisting></para>
  54
  55 <para>This struct contains the function and handle pointers for all operations.<programlisting>
  56 struct vfs_ops {
  57         struct vfs_fn_pointers {
  58                 ...
  59
  60                 /* File operations */
  61
  62                 int (*open)(struct vfs_handle_struct *handle,
  63                         struct connection_struct *conn,
  64                         const char *fname, int flags, mode_t mode);
  65                 int (*close)(struct vfs_handle_struct *handle,
  66                         struct files_struct *fsp, int fd);
  67                 ssize_t (*read)(struct vfs_handle_struct *handle,
  68                         struct files_struct *fsp, int fd, void *data, size_t n);
  69                 ssize_t (*write)(struct vfs_handle_struct *handle,
  70                         struct files_struct *fsp, int fd,
  71                         const void *data, size_t n);
  72                 SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle,
  73                         struct files_struct *fsp, int fd,
  74                         SMB_OFF_T offset, int whence);
  75                 ssize_t (*sendfile)(struct vfs_handle_struct *handle,
  76                         int tofd, files_struct *fsp, int fromfd,
  77                         const DATA_BLOB *header, SMB_OFF_T offset, size_t count);
  78
  79                 ...
  80         } ops;
  81
  82         struct vfs_handles_pointers {
  83                 ...
  84
  85                 /* File operations */
  86
  87                 struct vfs_handle_struct *open;
  88                 struct vfs_handle_struct *close;
  89                 struct vfs_handle_struct *read;
  90                 struct vfs_handle_struct *write;
  91                 struct vfs_handle_struct *lseek;
  92                 struct vfs_handle_struct *sendfile;
  93
  94                 ...
  95         } handles;
  96 };
  97 </programlisting></para>
  98
  99 <para>
 100 This macros SHOULD be used to call any vfs operation.
 101 DO NOT ACCESS conn-&gt;vfs.ops.* directly !!!
 102 <programlisting>
 103 ...
 104
 105 /* File operations */
 106 #define SMB_VFS_OPEN(conn, fname, flags, mode) \
 107         ((conn)-&gt;vfs.ops.open((conn)-&gt;vfs.handles.open,\
 108          (conn), (fname), (flags), (mode)))
 109 #define SMB_VFS_CLOSE(fsp, fd) \
 110         ((fsp)-&gt;conn-&gt;vfs.ops.close(\
 111         (fsp)-&gt;conn-&gt;vfs.handles.close, (fsp), (fd)))
 112 #define SMB_VFS_READ(fsp, fd, data, n) \
 113         ((fsp)-&gt;conn-&gt;vfs.ops.read(\
 114         (fsp)-&gt;conn-&gt;vfs.handles.read,\
 115          (fsp), (fd), (data), (n)))
 116 #define SMB_VFS_WRITE(fsp, fd, data, n) \
 117         ((fsp)-&gt;conn-&gt;vfs.ops.write(\
 118         (fsp)-&gt;conn-&gt;vfs.handles.write,\
 119          (fsp), (fd), (data), (n)))
 120 #define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
 121         ((fsp)-&gt;conn-&gt;vfs.ops.lseek(\
 122         (fsp)-&gt;conn-&gt;vfs.handles.lseek,\
 123          (fsp), (fd), (offset), (whence)))
 124 #define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
 125         ((fsp)-&gt;conn-&gt;vfs.ops.sendfile(\
 126         (fsp)-&gt;conn-&gt;vfs.handles.sendfile,\
 127          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 128
 129 ...
 130 </programlisting></para>
 131
 132 </sect2>
 133
 134 <sect2>
 135 <title>Possible VFS operation layers</title>
 136
 137 <para>
 138 These values are used by the VFS subsystem when building the conn-&gt;vfs
 139 and conn-&gt;vfs_opaque structs for a connection with multiple VFS modules.
 140 Internally, Samba differentiates only opaque and transparent layers at this process.
 141 Other types are used for providing better diagnosing facilities.
 142 </para>
 143
 144 <para>
 145 Most modules will provide transparent layers. Opaque layer is for modules
 146 which implement actual file system calls (like DB-based VFS). For example,
 147 default POSIX VFS which is built in into Samba is an opaque VFS module.
 148 </para>
 149
 150 <para>
 151 Other layer types (logger, splitter, scanner) were designed to provide different
 152 degree of transparency and for diagnosing VFS module behaviour.
 153 </para>
 154
 155 <para>
 156 Each module can implement several layers at the same time provided that only
 157 one layer is used per each operation.
 158 </para>
 159
 160 <para><programlisting>
 161 typedef enum _vfs_op_layer {
 162         SMB_VFS_LAYER_NOOP = -1,        /* - For using in VFS module to indicate end of array */
 163                                         /*   of operations description */
 164         SMB_VFS_LAYER_OPAQUE = 0,       /* - Final level, does not call anything beyond itself */
 165         SMB_VFS_LAYER_TRANSPARENT,      /* - Normal operation, calls underlying layer after */
 166                                         /*   possibly changing passed data */
 167         SMB_VFS_LAYER_LOGGER,           /* - Logs data, calls underlying layer, logging may not */
 168                                         /*   use Samba VFS */
 169         SMB_VFS_LAYER_SPLITTER,         /* - Splits operation, calls underlying layer _and_ own facility, */
 170                                         /*   then combines result */
 171         SMB_VFS_LAYER_SCANNER           /* - Checks data and possibly initiates additional */
 172                                         /*   file activity like logging to files _inside_ samba VFS */
 173 } vfs_op_layer;
 174 </programlisting></para>
 175
 176 </sect2>
 177
 178 </sect1>
 179
 180 <sect1>
 181 <title>The Interaction between the Samba VFS subsystem and the modules</title>
 182
 183 <sect2>
 184 <title>Initialization and registration</title>
 185
 186 <para>
 187 As each Samba module a VFS module should have a
 188 <programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or
 189 <programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module.
 190 </para>
 191
 192 <para>
 193 This should be the only non static function inside the module.
 194 Global variables should also be static!
 195 </para>
 196
 197 <para>
 198 The module should register its functions via the
 199 <programlisting>
 200 NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
 201 </programlisting> function.
 202 </para>
 203
 204 <variablelist>
 205
 206 <varlistentry><term>version</term>
 207 <listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
 208 </varlistentry>
 209
 210 <varlistentry><term>name</term>
 211 <listitem><para>this is the name witch can be listed in the
 212 <command>vfs objects</command> parameter to use this module.</para></listitem>
 213 </varlistentry>
 214
 215 <varlistentry><term>vfs_op_tuples</term>
 216 <listitem><para>
 217 this is an array of vfs_op_tuple's.
 218 (vfs_op_tuples is descripted in details below.)
 219 </para></listitem>
 220 </varlistentry>
 221
 222 </variablelist>
 223
 224 <para>
 225 For each operation the module wants to provide it has a entry in the
 226 vfs_op_tuple array.
 227 </para>
 228
 229 <programlisting>
 230 typedef struct _vfs_op_tuple {
 231         void* op;
 232         vfs_op_type type;
 233         vfs_op_layer layer;
 234 } vfs_op_tuple;
 235 </programlisting>
 236
 237 <variablelist>
 238
 239 <varlistentry><term>op</term>
 240 <listitem><para>the function pointer to the specified function.</para></listitem>
 241 </varlistentry>
 242
 243 <varlistentry><term>type</term>
 244 <listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
 245 </varlistentry>
 246
 247 <varlistentry><term>layer</term>
 248 <listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
 249 </varlistentry>
 250
 251 </variablelist>
 252
 253 <para>A simple example:</para>
 254
 255 <programlisting>
 256 static vfs_op_tuple example_op_tuples[] = {
 257         {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
 258         {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
 259
 260         {SMB_VFS_OP(example_rename),    SMB_VFS_OP_RENAME,      SMB_VFS_LAYER_OPAQUE},
 261
 262         /* This indicates the end of the array */
 263         {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
 264 };
 265
 266 NTSTATUS init_module(void)
 267 {
 268         return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, &quot;example&quot;, example_op_tuples);
 269 }
 270 </programlisting>
 271
 272 </sect2>
 273
 274 <sect2>
 275 <title>How the Modules handle per connection data</title>
 276
 277 <para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
 278 </para>
 279
 280 <programlisting>
 281 typedef struct vfs_handle_struct {
 282         struct vfs_handle_struct  *next, *prev;
 283         const char *param;
 284         struct vfs_ops vfs_next;
 285         struct connection_struct *conn;
 286         void *data;
 287         void (*free_data)(void **data);
 288 } vfs_handle_struct;
 289 </programlisting>
 290
 291 <variablelist>
 292
 293 <varlistentry><term>param</term>
 294 <listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para>
 295 <para>e.g. for 'vfs objects = example:test' param would be &quot;test&quot;.</para></listitem>
 296 </varlistentry>
 297
 298 <varlistentry><term>vfs_next</term>
 299 <listitem><para>This vfs_ops struct contains the information for calling the next module operations.
 300 Use the SMB_VFS_NEXT_* macros to call a next module operations and
 301 don't access handle-&gt;vfs_next.ops.* directly!</para></listitem>
 302 </varlistentry>
 303
 304 <varlistentry><term>conn</term>
 305 <listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
 306 </varlistentry>
 307
 308 <varlistentry><term>data</term>
 309 <listitem><para>This is a pointer for holding module private data.
 310 You can alloc data with connection life time on the handle-&gt;conn-&gt;mem_ctx TALLOC_CTX.
 311 But you can also manage the memory allocation yourself.</para></listitem>
 312 </varlistentry>
 313
 314 <varlistentry><term>free_data</term>
 315 <listitem><para>This is a function pointer to a function that free's the module private data.
 316 If you talloc your private data on the TALLOC_CTX handle-&gt;conn-&gt;mem_ctx,
 317 you can set this function pointer to NULL.</para></listitem>
 318 </varlistentry>
 319
 320 </variablelist>
 321
 322 <para>Some useful MACROS for handle private data.
 323 </para>
 324
 325 <programlisting>
 326 #define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
 327         if (!(handle)||((datap=(type *)(handle)-&gt;data)==NULL)) { \
 328                 DEBUG(0,(&quot;%s() failed to get vfs_handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
 329                 ret; \
 330         } \
 331 }
 332
 333 #define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
 334         if (!(handle)) { \
 335                 DEBUG(0,(&quot;%s() failed to set handle-&gt;data!\n&quot;,FUNCTION_MACRO)); \
 336                 ret; \
 337         } else { \
 338                 if ((handle)-&gt;free_data) { \
 339                         (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
 340                 } \
 341                 (handle)-&gt;data = (void *)datap; \
 342                 (handle)-&gt;free_data = free_fn; \
 343         } \
 344 }
 345
 346 #define SMB_VFS_HANDLE_FREE_DATA(handle) { \
 347         if ((handle) &amp;&amp; (handle)-&gt;free_data) { \
 348                 (handle)-&gt;free_data(&amp;(handle)-&gt;data); \
 349         } \
 350 }
 351 </programlisting>
 352
 353 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
 354
 355 <para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
 356 </para>
 357
 358 <programlisting>
 359 ...
 360 /* File operations */
 361 #define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
 362         ((conn)-&gt;vfs_opaque.ops.open(\
 363         (conn)-&gt;vfs_opaque.handles.open,\
 364          (conn), (fname), (flags), (mode)))
 365 #define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
 366         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.close(\
 367         (fsp)-&gt;conn-&gt;vfs_opaque.handles.close,\
 368          (fsp), (fd)))
 369 #define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
 370         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.read(\
 371         (fsp)-&gt;conn-&gt;vfs_opaque.handles.read,\
 372          (fsp), (fd), (data), (n)))
 373 #define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
 374         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.write(\
 375         (fsp)-&gt;conn-&gt;vfs_opaque.handles.write,\
 376          (fsp), (fd), (data), (n)))
 377 #define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
 378         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.lseek(\
 379         (fsp)-&gt;conn-&gt;vfs_opaque.handles.lseek,\
 380          (fsp), (fd), (offset), (whence)))
 381 #define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
 382         ((fsp)-&gt;conn-&gt;vfs_opaque.ops.sendfile(\
 383         (fsp)-&gt;conn-&gt;vfs_opaque.handles.sendfile,\
 384          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 385 ...
 386 </programlisting>
 387
 388 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
 389
 390 <para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
 391 </para>
 392
 393 <programlisting>
 394 ...
 395 /* File operations */
 396 #define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
 397         ((handle)-&gt;vfs_next.ops.open(\
 398         (handle)-&gt;vfs_next.handles.open,\
 399          (conn), (fname), (flags), (mode)))
 400 #define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
 401         ((handle)-&gt;vfs_next.ops.close(\
 402         (handle)-&gt;vfs_next.handles.close,\
 403          (fsp), (fd)))
 404 #define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
 405         ((handle)-&gt;vfs_next.ops.read(\
 406         (handle)-&gt;vfs_next.handles.read,\
 407          (fsp), (fd), (data), (n)))
 408 #define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
 409         ((handle)-&gt;vfs_next.ops.write(\
 410         (handle)-&gt;vfs_next.handles.write,\
 411          (fsp), (fd), (data), (n)))
 412 #define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
 413         ((handle)-&gt;vfs_next.ops.lseek(\
 414         (handle)-&gt;vfs_next.handles.lseek,\
 415          (fsp), (fd), (offset), (whence)))
 416 #define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
 417         ((handle)-&gt;vfs_next.ops.sendfile(\
 418         (handle)-&gt;vfs_next.handles.sendfile,\
 419          (tofd), (fsp), (fromfd), (header), (offset), (count)))
 420 ...
 421 </programlisting>
 422
 423 </sect2>
 424
 425 </sect1>
 426
 427 <sect1>
 428 <title>Upgrading to the New VFS Interface</title>
 429
 430 <sect2>
 431 <title>Upgrading from 2.2.* and 3.0aplha modules</title>
 432
 433 <orderedlist>
 434 <listitem><para>
 435 Add &quot;vfs_handle_struct *handle, &quot; as first parameter to all vfs operation functions.
 436 e.g. example_connect(connection_struct *conn, const char *service, const char *user);
 437 -&gt;   example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
 438 </para></listitem>
 439
 440 <listitem><para>
 441 Replace &quot;default_vfs_ops.&quot; with &quot;smb_vfs_next_&quot;.
 442 e.g. default_vfs_ops.connect(conn, service, user);
 443 -&gt;   smb_vfs_next_connect(conn, service, user);
 444 </para></listitem>
 445
 446 <listitem><para>
 447 Uppercase all &quot;smb_vfs_next_*&quot; functions.
 448 e.g. smb_vfs_next_connect(conn, service, user);
 449 -&gt;   SMB_VFS_NEXT_CONNECT(conn, service, user);
 450 </para></listitem>
 451
 452 <listitem><para>
 453 Add &quot;handle, &quot; as first parameter to all SMB_VFS_NEXT_*() calls.
 454 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
 455 -&gt;   SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
 456 </para></listitem>
 457
 458 <listitem><para>
 459 (Only for 2.2.* modules)
 460 Convert the old struct vfs_ops example_ops to
 461 a vfs_op_tuple example_op_tuples[] array.
 462 e.g.
 463 <programlisting>
 464 struct vfs_ops example_ops = {
 465         /* Disk operations */
 466         example_connect,                /* connect */
 467         example_disconnect,             /* disconnect */
 468         NULL,                           /* disk free *
 469         /* Directory operations */
 470         NULL,                           /* opendir */
 471         NULL,                           /* readdir */
 472         NULL,                           /* mkdir */
 473         NULL,                           /* rmdir */
 474         NULL,                           /* closedir */
 475         /* File operations */
 476         NULL,                           /* open */
 477         NULL,                           /* close */
 478         NULL,                           /* read  */
 479         NULL,                           /* write */
 480         NULL,                           /* lseek */
 481         NULL,                           /* sendfile */
 482         NULL,                           /* rename */
 483         NULL,                           /* fsync */
 484         example_stat,                   /* stat  */
 485         example_fstat,                  /* fstat */
 486         example_lstat,                  /* lstat */
 487         NULL,                           /* unlink */
 488         NULL,                           /* chmod */
 489         NULL,                           /* fchmod */
 490         NULL,                           /* chown */
 491         NULL,                           /* fchown */
 492         NULL,                           /* chdir */
 493         NULL,                           /* getwd */
 494         NULL,                           /* utime */
 495         NULL,                           /* ftruncate */
 496         NULL,                           /* lock */
 497         NULL,                           /* symlink */
 498         NULL,                           /* readlink */
 499         NULL,                           /* link */
 500         NULL,                           /* mknod */
 501         NULL,                           /* realpath */
 502         NULL,                           /* fget_nt_acl */
 503         NULL,                           /* get_nt_acl */
 504         NULL,                           /* fset_nt_acl */
 505         NULL,                           /* set_nt_acl */
 506
 507         NULL,                           /* chmod_acl */
 508         NULL,                           /* fchmod_acl */
 509
 510         NULL,                           /* sys_acl_get_entry */
 511         NULL,                           /* sys_acl_get_tag_type */
 512         NULL,                           /* sys_acl_get_permset */
 513         NULL,                           /* sys_acl_get_qualifier */
 514         NULL,                           /* sys_acl_get_file */
 515         NULL,                           /* sys_acl_get_fd */
 516         NULL,                           /* sys_acl_clear_perms */
 517         NULL,                           /* sys_acl_add_perm */
 518         NULL,                           /* sys_acl_to_text */
 519         NULL,                           /* sys_acl_init */
 520         NULL,                           /* sys_acl_create_entry */
 521         NULL,                           /* sys_acl_set_tag_type */
 522         NULL,                           /* sys_acl_set_qualifier */
 523         NULL,                           /* sys_acl_set_permset */
 524         NULL,                           /* sys_acl_valid */
 525         NULL,                           /* sys_acl_set_file */
 526         NULL,                           /* sys_acl_set_fd */
 527         NULL,                           /* sys_acl_delete_def_file */
 528         NULL,                           /* sys_acl_get_perm */
 529         NULL,                           /* sys_acl_free_text */
 530         NULL,                           /* sys_acl_free_acl */
 531         NULL                            /* sys_acl_free_qualifier */
 532 };
 533 </programlisting>
 534 -&gt;
 535 <programlisting>
 536 static vfs_op_tuple example_op_tuples[] = {
 537         {SMB_VFS_OP(example_connect),   SMB_VFS_OP_CONNECT,     SMB_VFS_LAYER_TRANSPARENT},
 538         {SMB_VFS_OP(example_disconnect),        SMB_VFS_OP_DISCONNECT,  SMB_VFS_LAYER_TRANSPARENT},
 539
 540         {SMB_VFS_OP(example_fstat),     SMB_VFS_OP_FSTAT,       SMB_VFS_LAYER_TRANSPARENT},
 541         {SMB_VFS_OP(example_stat),              SMB_VFS_OP_STAT,        SMB_VFS_LAYER_TRANSPARENT},
 542         {SMB_VFS_OP(example_lstat),     SMB_VFS_OP_LSTAT,       SMB_VFS_LAYER_TRANSPARENT},
 543
 544         {SMB_VFS_OP(NULL),                              SMB_VFS_OP_NOOP,        SMB_VFS_LAYER_NOOP}
 545 };
 546 </programlisting>
 547 </para></listitem>
 548
 549 <listitem><para>
 550 Move the example_op_tuples[] array to the end of the file.
 551 </para></listitem>
 552
 553 <listitem><para>
 554 Add the init_module() function at the end of the file.
 555 e.g.
 556 <programlisting>
 557 NTSTATUS init_module(void)
 558 {
 559         return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,&quot;example&quot;,example_op_tuples);
 560 }
 561 </programlisting>
 562 </para></listitem>
 563
 564 <listitem><para>
 565 Check if your vfs_init() function does more then just prepare the vfs_ops structs or
 566 remember the struct smb_vfs_handle_struct.
 567 <simplelist>
 568 <member>If NOT you can remove the vfs_init() function.</member>
 569 <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().
 570   e.g. a debug class registration should go into init_module() and the allocation of private data should go to example_connect().</member>
 571 </simplelist>
 572 </para></listitem>
 573
 574 <listitem><para>
 575 (Only for 3.0alpha* modules)
 576 Check if your vfs_done() function contains needed code.
 577 <simplelist>
 578 <member>If NOT you can remove the vfs_done() function.</member>
 579 <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().
 580 </member>
 581 </simplelist>
 582 </para></listitem>
 583
 584 <listitem><para>
 585 Check if you have any global variables left.
 586 Decide if it wouldn't be better to have this data on a connection basis.
 587 <simplelist>
 588   <member>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</member>
 589   <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>
 590 </simplelist>
 591
 592   e.g. if you have such a struct:
 593 <programlisting>
 594 struct example_privates {
 595         char *some_string;
 596         int db_connection;
 597 };
 598 </programlisting>
 599 first way of doing it:
 600 <programlisting>
 601 static int example_connect(vfs_handle_struct *handle,
 602         connection_struct *conn, const char *service,
 603         const char* user)
 604 {
 605         struct example_privates *data = NULL;
 606
 607         /* alloc our private data */
 608         data = (struct example_privates *)talloc_zero(conn-&gt;mem_ctx, sizeof(struct example_privates));
 609         if (!data) {
 610                 DEBUG(0,(&quot;talloc_zero() failed\n&quot;));
 611                 return -1;
 612         }
 613
 614         /* init out private data */
 615         data-&gt;some_string = talloc_strdup(conn-&gt;mem_ctx,&quot;test&quot;);
 616         if (!data-&gt;some_string) {
 617                 DEBUG(0,(&quot;talloc_strdup() failed\n&quot;));
 618                 return -1;
 619         }
 620
 621         data-&gt;db_connection = open_db_conn();
 622
 623         /* and now store the private data pointer in handle-&gt;data
 624          * we don't need to specify a free_function here because
 625          * we use the connection TALLOC context.
 626          * (return -1 if something failed.)
 627          */
 628         VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
 629
 630         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
 631 }
 632
 633 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 634 {
 635         struct example_privates *data = NULL;
 636
 637         /* get the pointer to our private data
 638          * return -1 if something failed
 639          */
 640         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
 641
 642         /* do something here...*/
 643         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
 644
 645         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 646 }
 647 </programlisting>
 648 second way of doing it:
 649 <programlisting>
 650 static void free_example_privates(void **datap)
 651 {
 652         struct example_privates *data = (struct example_privates *)*datap;
 653
 654         SAFE_FREE(data-&gt;some_string);
 655         SAFE_FREE(data);
 656
 657         *datap = NULL;
 658
 659         return;
 660 }
 661
 662 static int example_connect(vfs_handle_struct *handle,
 663         connection_struct *conn, const char *service,
 664         const char* user)
 665 {
 666         struct example_privates *data = NULL;
 667
 668         /* alloc our private data */
 669         data = (struct example_privates *)malloc(sizeof(struct example_privates));
 670         if (!data) {
 671                 DEBUG(0,(&quot;malloc() failed\n&quot;));
 672                 return -1;
 673         }
 674
 675         /* init out private data */
 676         data-&gt;some_string = strdup(&quot;test&quot;);
 677         if (!data-&gt;some_string) {
 678                 DEBUG(0,(&quot;strdup() failed\n&quot;));
 679                 return -1;
 680         }
 681
 682         data-&gt;db_connection = open_db_conn();
 683
 684         /* and now store the private data pointer in handle-&gt;data
 685          * we need to specify a free_function because we used malloc() and strdup().
 686          * (return -1 if something failed.)
 687          */
 688         SMB_VFS_HANDLE_SET_DATA(handle, data, free_example_privates, struct example_privates, return -1);
 689
 690         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
 691 }
 692
 693 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 694 {
 695         struct example_privates *data = NULL;
 696
 697         /* get the pointer to our private data
 698          * return -1 if something failed
 699          */
 700         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
 701
 702         /* do something here...*/
 703         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
 704
 705         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 706 }
 707 </programlisting>
 708 </para></listitem>
 709
 710 <listitem><para>
 711 To make it easy to build 3rd party modules it would be usefull to provide
 712 configure.in, (configure), install.sh and Makefile.in with the module.
 713 (Take a look at the example in <filename>examples/VFS</filename>.)
 714 </para>
 715
 716 <para>
 717 The configure script accepts <option>--with-samba-source</option> to specify
 718 the path to the samba source tree.
 719 It also accept <option>--enable-developer</option> which lets the compiler
 720 give you more warnings.
 721 </para>
 722
 723 <para>
 724 The idea is that you can extend this
 725 <filename>configure.in</filename> and <filename>Makefile.in</filename> scripts
 726 for your module.
 727 </para></listitem>
 728
 729 <listitem><para>
 730 Compiling &amp; Testing...
 731 <simplelist>
 732 <member><userinput>./configure <option>--enable-developer</option></userinput> ...</member>
 733 <member><userinput>make</userinput></member>
 734 <member>Try to fix all compiler warnings</member>
 735 <member><userinput>make</userinput></member>
 736 <member>Testing, Testing, Testing ...</member>
 737 </simplelist>
 738 </para></listitem>
 739 </orderedlist>
 740 </sect2>
 741
 742 </sect1>
 743
 744 <sect1>
 745 <title>Some Notes</title>
 746
 747 <sect2>
 748 <title>Implement TRANSPARENT functions</title>
 749
 750 <para>
 751 Avoid writing functions like this:
 752
 753 <programlisting>
 754 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
 755 {
 756         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
 757 }
 758 </programlisting>
 759
 760 Overload only the functions you really need to!
 761 </para>
 762
 763 </sect2>
 764
 765 <sect2>
 766 <title>Implement OPAQUE functions</title>
 767
 768 <para>
 769 If you want to just implement a better version of a
 770 default samba opaque function
 771 (e.g. like a disk_free() function for a special filesystem)
 772 it's ok to just overload that specific function.
 773 </para>
 774
 775 <para>
 776 If you want to implement a database filesystem or
 777 something different from a posix filesystem.
 778 Make sure that you overload every vfs operation!!!
 779 </para>
 780 <para>
 781 Functions your FS does not support should be overloaded by something like this:
 782 e.g. for a readonly filesystem.
 783 </para>
 784
 785 <programlisting>
 786 static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
 787                         char *oldname, char *newname)
 788 {
 789         DEBUG(10,(&quot;function rename() not allowed on vfs 'example'\n&quot;));
 790         errno = ENOSYS;
 791         return -1;
 792 }
 793 </programlisting>
 794
 795 </sect2>
 796
 797 </sect1>
 798
 799 </chapter>