docs/docbook/devdoc/vfs.xml

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