| blob | f70fc96f37299efbd1f01391fd2177f095139623 |
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>
20 <title>VFS Modules</title>
22 <sect1>
23 <title>The Samba (Posix) VFS layer</title>
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>
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>
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>
57 <sect2>
58 <title>The general interface</title>
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>
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>
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>
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>
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 overriden, 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>
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>
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>
160 <para><programlisting>
161 typedef enum _vfs_op_type {
162 SMB_VFS_OP_NOOP = -1,
164 ...
166 /* File operations */
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,
175 ...
177 SMB_VFS_OP_LAST
178 } vfs_op_type;
179 </programlisting></para>
181 <para>This struct contains the function and handle pointers for all operations.<programlisting>
182 struct vfs_ops {
183 struct vfs_fn_pointers {
184 ...
186 /* File operations */
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);
205 ...
206 } ops;
208 struct vfs_handles_pointers {
209 ...
211 /* File operations */
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;
220 ...
221 } handles;
222 };
223 </programlisting></para>
225 <para>
226 This macros SHOULD be used to call any vfs operation.
227 DO NOT ACCESS conn->vfs.ops.* directly !!!
228 <programlisting>
229 ...
231 /* File operations */
232 #define SMB_VFS_OPEN(conn, fname, flags, mode) \
233 ((conn)->vfs.ops.open((conn)->vfs.handles.open,\
234 (conn), (fname), (flags), (mode)))
235 #define SMB_VFS_CLOSE(fsp, fd) \
236 ((fsp)->conn->vfs.ops.close(\
237 (fsp)->conn->vfs.handles.close, (fsp), (fd)))
238 #define SMB_VFS_READ(fsp, fd, data, n) \
239 ((fsp)->conn->vfs.ops.read(\
240 (fsp)->conn->vfs.handles.read,\
241 (fsp), (fd), (data), (n)))
242 #define SMB_VFS_WRITE(fsp, fd, data, n) \
243 ((fsp)->conn->vfs.ops.write(\
244 (fsp)->conn->vfs.handles.write,\
245 (fsp), (fd), (data), (n)))
246 #define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
247 ((fsp)->conn->vfs.ops.lseek(\
248 (fsp)->conn->vfs.handles.lseek,\
249 (fsp), (fd), (offset), (whence)))
250 #define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
251 ((fsp)->conn->vfs.ops.sendfile(\
252 (fsp)->conn->vfs.handles.sendfile,\
253 (tofd), (fsp), (fromfd), (header), (offset), (count)))
255 ...
256 </programlisting></para>
258 </sect2>
260 <sect2>
261 <title>Possible VFS operation layers</title>
263 <para>
264 These values are used by the VFS subsystem when building the conn->vfs
265 and conn->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>
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>
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>
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>
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>
302 </sect2>
304 </sect1>
306 <sect1>
307 <title>The Interaction between the Samba VFS subsystem and the modules</title>
309 <sect2>
310 <title>Initialization and registration</title>
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>
318 <para>
319 This should be the only non static function inside the module.
320 Global variables should also be static!
321 </para>
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>
330 <variablelist>
332 <varlistentry><term>version</term>
333 <listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
334 </varlistentry>
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>
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>
348 </variablelist>
350 <para>
351 For each operation the module wants to provide it has a entry in the
352 vfs_op_tuple array.
353 </para>
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>
363 <variablelist>
365 <varlistentry><term>op</term>
366 <listitem><para>the function pointer to the specified function.</para></listitem>
367 </varlistentry>
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>
373 <varlistentry><term>layer</term>
374 <listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
375 </varlistentry>
377 </variablelist>
379 <para>A simple example:</para>
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},
386 {SMB_VFS_OP(example_rename), SMB_VFS_OP_RENAME, SMB_VFS_LAYER_OPAQUE},
388 /* This indicates the end of the array */
389 {SMB_VFS_OP(NULL), SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP}
390 };
392 NTSTATUS init_module(void)
393 {
394 return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples);
395 }
396 </programlisting>
398 </sect2>
400 <sect2>
401 <title>How the Modules handle per connection data</title>
403 <para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
404 </para>
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>
417 <variablelist>
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 "test".</para></listitem>
422 </varlistentry>
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->vfs_next.ops.* directly!</para></listitem>
428 </varlistentry>
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>
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->conn->mem_ctx TALLOC_CTX.
437 But you can also manage the memory allocation yourself.</para></listitem>
438 </varlistentry>
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->conn->mem_ctx,
443 you can set this function pointer to NULL.</para></listitem>
444 </varlistentry>
446 </variablelist>
448 <para>Some useful MACROS for handle private data.
449 </para>
451 <programlisting>
452 #define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
453 if (!(handle)||((datap=(type *)(handle)->data)==NULL)) { \
454 DEBUG(0,("%s() failed to get vfs_handle->data!\n",FUNCTION_MACRO)); \
455 ret; \
456 } \
457 }
459 #define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
460 if (!(handle)) { \
461 DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \
462 ret; \
463 } else { \
464 if ((handle)->free_data) { \
465 (handle)->free_data(&(handle)->data); \
466 } \
467 (handle)->data = (void *)datap; \
468 (handle)->free_data = free_fn; \
469 } \
470 }
472 #define SMB_VFS_HANDLE_FREE_DATA(handle) { \
473 if ((handle) && (handle)->free_data) { \
474 (handle)->free_data(&(handle)->data); \
475 } \
476 }
477 </programlisting>
479 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
481 <para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
482 </para>
484 <programlisting>
485 ...
486 /* File operations */
487 #define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
488 ((conn)->vfs_opaque.ops.open(\
489 (conn)->vfs_opaque.handles.open,\
490 (conn), (fname), (flags), (mode)))
491 #define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
492 ((fsp)->conn->vfs_opaque.ops.close(\
493 (fsp)->conn->vfs_opaque.handles.close,\
494 (fsp), (fd)))
495 #define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
496 ((fsp)->conn->vfs_opaque.ops.read(\
497 (fsp)->conn->vfs_opaque.handles.read,\
498 (fsp), (fd), (data), (n)))
499 #define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
500 ((fsp)->conn->vfs_opaque.ops.write(\
501 (fsp)->conn->vfs_opaque.handles.write,\
502 (fsp), (fd), (data), (n)))
503 #define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
504 ((fsp)->conn->vfs_opaque.ops.lseek(\
505 (fsp)->conn->vfs_opaque.handles.lseek,\
506 (fsp), (fd), (offset), (whence)))
507 #define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
508 ((fsp)->conn->vfs_opaque.ops.sendfile(\
509 (fsp)->conn->vfs_opaque.handles.sendfile,\
510 (tofd), (fsp), (fromfd), (header), (offset), (count)))
511 ...
512 </programlisting>
514 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
516 <para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
517 </para>
519 <programlisting>
520 ...
521 /* File operations */
522 #define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
523 ((handle)->vfs_next.ops.open(\
524 (handle)->vfs_next.handles.open,\
525 (conn), (fname), (flags), (mode)))
526 #define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
527 ((handle)->vfs_next.ops.close(\
528 (handle)->vfs_next.handles.close,\
529 (fsp), (fd)))
530 #define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
531 ((handle)->vfs_next.ops.read(\
532 (handle)->vfs_next.handles.read,\
533 (fsp), (fd), (data), (n)))
534 #define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
535 ((handle)->vfs_next.ops.write(\
536 (handle)->vfs_next.handles.write,\
537 (fsp), (fd), (data), (n)))
538 #define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
539 ((handle)->vfs_next.ops.lseek(\
540 (handle)->vfs_next.handles.lseek,\
541 (fsp), (fd), (offset), (whence)))
542 #define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
543 ((handle)->vfs_next.ops.sendfile(\
544 (handle)->vfs_next.handles.sendfile,\
545 (tofd), (fsp), (fromfd), (header), (offset), (count)))
546 ...
547 </programlisting>
549 </sect2>
551 </sect1>
553 <sect1>
554 <title>Upgrading to the New VFS Interface</title>
556 <sect2>
557 <title>Upgrading from 2.2.* and 3.0alpha modules</title>
559 <orderedlist>
560 <listitem><para>
561 Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions.
562 e.g. example_connect(connection_struct *conn, const char *service, const char *user);
563 -> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
564 </para></listitem>
566 <listitem><para>
567 Replace "default_vfs_ops." with "smb_vfs_next_".
568 e.g. default_vfs_ops.connect(conn, service, user);
569 -> smb_vfs_next_connect(conn, service, user);
570 </para></listitem>
572 <listitem><para>
573 Uppercase all "smb_vfs_next_*" functions.
574 e.g. smb_vfs_next_connect(conn, service, user);
575 -> SMB_VFS_NEXT_CONNECT(conn, service, user);
576 </para></listitem>
578 <listitem><para>
579 Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls.
580 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
581 -> SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
582 </para></listitem>
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 */
633 NULL, /* chmod_acl */
634 NULL, /* fchmod_acl */
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 ->
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},
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},
670 {SMB_VFS_OP(NULL), SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP}
671 };
672 </programlisting>
673 </para></listitem>
675 <listitem><para>
676 Move the example_op_tuples[] array to the end of the file.
677 </para></listitem>
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,"example",example_op_tuples);
686 }
687 </programlisting>
688 </para></listitem>
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>
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>
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->data to point to such a struct on a per connection basis.</member>
716 </simplelist>
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;
733 /* alloc our private data */
734 data = (struct example_privates *)talloc_zero(conn->mem_ctx, sizeof(struct example_privates));
735 if (!data) {
736 DEBUG(0,("talloc_zero() failed\n"));
737 return -1;
738 }
740 /* init out private data */
741 data->some_string = talloc_strdup(conn->mem_ctx,"test");
742 if (!data->some_string) {
743 DEBUG(0,("talloc_strdup() failed\n"));
744 return -1;
745 }
747 data->db_connection = open_db_conn();
749 /* and now store the private data pointer in handle->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);
756 return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
757 }
759 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
760 {
761 struct example_privates *data = NULL;
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);
768 /* do something here...*/
769 DEBUG(0,("some_string: %s\n",data->some_string));
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;
780 SAFE_FREE(data->some_string);
781 SAFE_FREE(data);
783 *datap = NULL;
785 return;
786 }
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;
794 /* alloc our private data */
795 data = (struct example_privates *)malloc(sizeof(struct example_privates));
796 if (!data) {
797 DEBUG(0,("malloc() failed\n"));
798 return -1;
799 }
801 /* init out private data */
802 data->some_string = strdup("test");
803 if (!data->some_string) {
804 DEBUG(0,("strdup() failed\n"));
805 return -1;
806 }
808 data->db_connection = open_db_conn();
810 /* and now store the private data pointer in handle->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);
816 return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
817 }
819 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
820 {
821 struct example_privates *data = NULL;
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);
828 /* do something here...*/
829 DEBUG(0,("some_string: %s\n",data->some_string));
831 return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
832 }
833 </programlisting>
834 </para></listitem>
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>
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>
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>
855 <listitem><para>
856 Compiling & 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>
868 </sect1>
870 <sect1>
871 <title>Some Notes</title>
873 <sect2>
874 <title>Implement TRANSPARENT functions</title>
876 <para>
877 Avoid writing functions like this:
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>
886 Overload only the functions you really need to!
887 </para>
889 </sect2>
891 <sect2>
892 <title>Implement OPAQUE functions</title>
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>
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>
911 <programlisting>
912 static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
913 char *oldname, char *newname)
914 {
915 DEBUG(10,("function rename() not allowed on vfs 'example'\n"));
916 errno = ENOSYS;
917 return -1;
918 }
919 </programlisting>
921 </sect2>
923 </sect1>
925 </chapter>