First version of VFS API developers documentation. Needs work on both formatting...
[samba.git] / 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 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 usefull 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>
443
444 <listitem><para>
445 Uppercase all &quot;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 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 - If NOT you can remove the vfs_init() function.
566 - If YES decide if you want to move the code to the example_connect() operation or to the init_module().
567   And then remove vfs_init().
568   e.g. 
569   - a debug class registration should go into init_module().
570   - the allocation of private data should go to example_connect().
571 </para></listitem>
572
573 <listitem><para>
574 (Only for 3.0aplha* modules) 
575 Check if your vfs_done() function contains needed code.
576 - If NOT you can remove the vfs_done() function.
577 - If YES decide if you can move the code to the example_disconnect() operation.
578   Otherwise register a SMB_EXIT_EVENT with smb_register_exit_event();
579   (Described in the MODULES section of the Samba-Developer-HOWTO.)
580   And then remove vfs_done(). 
581   e.g. the freeing of private data should go to example_disconnect().
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   - If NOT leave them as they are.
588     (e.g. this could be the variable for the private debug class.)
589   - If YES pack all this data into a struct.
590     You can use handle-&gt;data to point to such a struct on a
591     per connection basis.
592
593   e.g. if you have such a struct:
594 <programlisting>    
595 struct example_privates {
596         char *some_string;
597         int db_connection;
598 };
599 </programlisting>       
600 1st way of doing it:
601 <programlisting>
602 static int example_connect(vfs_handle_struct *handle,
603         connection_struct *conn, const char *service, 
604         const char* user)
605 {
606         struct example_privates *data = NULL;
607
608         /* alloc our private data */
609         data = (struct example_privates *)talloc_zero(conn-&gt;mem_ctx, sizeof(struct example_privates));
610         if (!data) {
611                 DEBUG(0,(&quot;talloc_zero() failed\n&quot;));
612                 return -1;
613         }
614
615         /* init out private data */
616         data-&gt;some_string = talloc_strdup(conn-&gt;mem_ctx,&quot;test&quot;);
617         if (!data-&gt;some_string) {
618                 DEBUG(0,(&quot;talloc_strdup() failed\n&quot;));
619                 return -1;
620         }
621
622         data-&gt;db_connection = open_db_conn();
623
624         /* and now store the private data pointer in handle-&gt;data
625          * we don't need to specify a free_function here because
626          * we use the connection TALLOC context.
627          * (return -1 if something failed.)
628          */
629         VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
630
631         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
632 }
633
634 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
635 {
636         struct example_privates *data = NULL;
637         
638         /* get the pointer to our private data
639          * return -1 if something failed
640          */
641         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
642         
643         /* do something here...*/
644         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
645         
646         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
647 }
648 </programlisting>
649 2nd way of doing it:
650 <programlisting>
651 static void free_example_privates(void **datap)
652 {
653         struct example_privates *data = (struct example_privates *)*datap;
654         
655         SAFE_FREE(data-&gt;some_string);
656         SAFE_FREE(data);
657         
658         datap = NULL;
659         
660         return;
661 }
662
663 static int example_connect(vfs_handle_struct *handle, 
664         connection_struct *conn, const char *service, 
665         const char* user)
666 {
667         struct example_privates *data = NULL;
668
669         /* alloc our private data */
670         data = (struct example_privates *)malloc(sizeof(struct example_privates));
671         if (!data) {
672                 DEBUG(0,(&quot;malloc() failed\n&quot;));
673                 return -1;
674         }
675
676         /* init out private data */
677         data-&gt;some_string = strdup(conn-&gt;mem_ctx,&quot;test&quot;);
678         if (!data-&gt;some_string) {
679                 DEBUG(0,(&quot;strdup() failed\n&quot;));
680                 return -1;
681         }
682
683         data-&gt;db_connection = open_db_conn();
684
685         /* and now store the private data pointer in handle-&gt;data
686          * we need to specify a free_function because we used malloc() and strdup().
687          * (return -1 if something failed.)
688          */
689         SMB_VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
690
691         return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
692 }
693
694 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
695 {
696         struct example_privates *data = NULL;
697         
698         /* get the pointer to our private data
699          * return -1 if something failed
700          */
701         SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
702         
703         /* do something here...*/
704         DEBUG(0,(&quot;some_string: %s\n&quot;,data-&gt;some_string));
705         
706         return VFS_NEXT_CLOSE(handle, fsp, fd);
707 }
708 </programlisting>
709 </para></listitem>
710
711 <listitem><para>
712 To make it easy to build 3rd party modules it would be usefull to provide
713 configure.in, (configure), install.sh and Makefile.in with the module.
714 (Take a look at the example in <filename>examples/VFS</filename>.)
715
716 The configure script accept --with-samba-source to specify the path to
717 the samba source tree.
718 It also accept --enable-developer witch let the compiler give you more warnings.  
719
720 The idea is that you can extend this configure.in and Makefile.in scripts
721 for your module.
722 </para></listitem>
723
724 <listitem><para>
725 Compiling & Testing...
726 - configure --enable-developer ...
727 - make
728 - Try to fiy all compiler warnings
729 - make
730 - Testing, Testing, Testing ...
731 </para></listitem>
732 </orderedlist>
733 </sect2>
734
735 </sect1>
736
737 <sect1>
738 <title>Some Notes</title>
739
740 <sect2>
741 <title>Implement TRANSPARENT functions</title>
742
743 <para>
744 Avoid writting functions like this:
745
746 <programlisting>
747 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
748 {
749         return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
750 }
751 </programlisting>
752
753 Overload only the functions you really need to!
754 </para>
755
756 </sect2>
757
758 <sect2>
759 <title>Implement OPAQUE functions</title>
760
761 <para>
762 If you want just implement only a better version of a 
763 default samba opaque function
764 (e.g. like a disk_free() function for a speciall filesystem) 
765 it's ok to just overload that specific function.
766 </para>
767
768 <para>
769 If you want to implement a database filesystem or
770 something different from a posix filesystem.
771 Make sure that you overload every vfs operation!!!
772 </para>
773 <para>
774 Functions your FS does not support should be overloaded by something like this:
775 e.g. for a readonly filesystem.
776 </para>
777
778 <programlisting>
779 static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
780                         char *oldname, char *newname)
781 {
782         DEBUG(10,(&quot;function rename() not allowed on vfs 'example'\n&quot;));
783         errno = ENOSYS;
784         return -1;
785 }
786 </programlisting>
787
788 </sect2>
789
790 </sect1>
791
792 </chapter>