docs: Rename Samba3-Developers-Guide to Samba-Developers-Guide
[bbaumbach/samba-autobuild/.git] / 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>