| blob | 96d512c8f34a2f2f7f0f6daefedb8a8c7e5d71a4 |
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><emphasis>An initialization function</emphasis> that is
63 called during the module load to register implemented
64 operations.</listitem>
65 <listitem><emphasis>An operations table</emphasis> representing a
66 mapping between statically defined module functions and VFS layer
67 operations.</listitem>
68 <listitem><emphasis>Module functions</emphasis> that do actual
69 work.</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><emphasis>interface version number</emphasis>, as constant
97 <literal>SMB_VFS_INTERFACE_VERSION</literal>, </listitem>
98 <listitem><emphasis>module name</emphasis>, under which Samba core
99 will know it, and</listitem>
100 <listitem><emphasis>an operations' table</emphasis>.</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><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>;
114 </listitem>
115 <listitem><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;</listitem>
121 <listitem><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;</listitem>
126 <listitem><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 </listitem>
134 <listitem>On contrary, <emphasis>scanner</emphasis> module does call
135 other VFS operations while processing the data that goes through the
136 system. This type of operation is indicated by the
137 <literal>SMB_VFS_LAYER_SCANNER</literal> constant.</listitem>
138 </itemizedlist>
139 </para>
141 <para>Fundamentally, there are three types:
142 <emphasis>transparent</emphasis>, <emphasis>opaque</emphasis>, and
143 <emphasis>logger</emphasis>. <emphasis>Splitter</emphasis> and
144 <emphasis>scanner</emphasis> may confuse developers (and indeed they
145 are confused as our experience has shown) but this separation is to
146 better expose the nature of a module's actions. Most of modules
147 developed so far are either one of those three fundamental types with
148 transparent and opaque being prevalent.
149 </para>
151 <para>
152 Each VFS operation has a vfs_op_type, a function pointer and a handle
153 pointer in the struct vfs_ops and tree macros to make it easier to
154 call the operations. (Take a look at
155 <filename>include/vfs.h</filename> and
156 <filename>include/vfs_macros.h</filename>.)
157 </para>
159 <para><programlisting>
160 typedef enum _vfs_op_type {
161 SMB_VFS_OP_NOOP = -1,
163 ...
165 /* File operations */
167 SMB_VFS_OP_OPEN,
168 SMB_VFS_OP_CLOSE,
169 SMB_VFS_OP_READ,
170 SMB_VFS_OP_WRITE,
171 SMB_VFS_OP_LSEEK,
172 SMB_VFS_OP_SENDFILE,
174 ...
176 SMB_VFS_OP_LAST
177 } vfs_op_type;
178 </programlisting></para>
180 <para>This struct contains the function and handle pointers for all operations.<programlisting>
181 struct vfs_ops {
182 struct vfs_fn_pointers {
183 ...
185 /* File operations */
187 int (*open)(struct vfs_handle_struct *handle,
188 struct connection_struct *conn,
189 const char *fname, int flags, mode_t mode);
190 int (*close)(struct vfs_handle_struct *handle,
191 struct files_struct *fsp, int fd);
192 ssize_t (*read)(struct vfs_handle_struct *handle,
193 struct files_struct *fsp, int fd, void *data, size_t n);
194 ssize_t (*write)(struct vfs_handle_struct *handle,
195 struct files_struct *fsp, int fd,
196 const void *data, size_t n);
197 SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle,
198 struct files_struct *fsp, int fd,
199 SMB_OFF_T offset, int whence);
200 ssize_t (*sendfile)(struct vfs_handle_struct *handle,
201 int tofd, files_struct *fsp, int fromfd,
202 const DATA_BLOB *header, SMB_OFF_T offset, size_t count);
204 ...
205 } ops;
207 struct vfs_handles_pointers {
208 ...
210 /* File operations */
212 struct vfs_handle_struct *open;
213 struct vfs_handle_struct *close;
214 struct vfs_handle_struct *read;
215 struct vfs_handle_struct *write;
216 struct vfs_handle_struct *lseek;
217 struct vfs_handle_struct *sendfile;
219 ...
220 } handles;
221 };
222 </programlisting></para>
224 <para>
225 This macros SHOULD be used to call any vfs operation.
226 DO NOT ACCESS conn->vfs.ops.* directly !!!
227 <programlisting>
228 ...
230 /* File operations */
231 #define SMB_VFS_OPEN(conn, fname, flags, mode) \
232 ((conn)->vfs.ops.open((conn)->vfs.handles.open,\
233 (conn), (fname), (flags), (mode)))
234 #define SMB_VFS_CLOSE(fsp, fd) \
235 ((fsp)->conn->vfs.ops.close(\
236 (fsp)->conn->vfs.handles.close, (fsp), (fd)))
237 #define SMB_VFS_READ(fsp, fd, data, n) \
238 ((fsp)->conn->vfs.ops.read(\
239 (fsp)->conn->vfs.handles.read,\
240 (fsp), (fd), (data), (n)))
241 #define SMB_VFS_WRITE(fsp, fd, data, n) \
242 ((fsp)->conn->vfs.ops.write(\
243 (fsp)->conn->vfs.handles.write,\
244 (fsp), (fd), (data), (n)))
245 #define SMB_VFS_LSEEK(fsp, fd, offset, whence) \
246 ((fsp)->conn->vfs.ops.lseek(\
247 (fsp)->conn->vfs.handles.lseek,\
248 (fsp), (fd), (offset), (whence)))
249 #define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
250 ((fsp)->conn->vfs.ops.sendfile(\
251 (fsp)->conn->vfs.handles.sendfile,\
252 (tofd), (fsp), (fromfd), (header), (offset), (count)))
254 ...
255 </programlisting></para>
257 </sect2>
259 <sect2>
260 <title>Possible VFS operation layers</title>
262 <para>
263 These values are used by the VFS subsystem when building the conn->vfs
264 and conn->vfs_opaque structs for a connection with multiple VFS modules.
265 Internally, Samba differentiates only opaque and transparent layers at this process.
266 Other types are used for providing better diagnosing facilities.
267 </para>
269 <para>
270 Most modules will provide transparent layers. Opaque layer is for modules
271 which implement actual file system calls (like DB-based VFS). For example,
272 default POSIX VFS which is built in into Samba is an opaque VFS module.
273 </para>
275 <para>
276 Other layer types (logger, splitter, scanner) were designed to provide different
277 degree of transparency and for diagnosing VFS module behaviour.
278 </para>
280 <para>
281 Each module can implement several layers at the same time provided that only
282 one layer is used per each operation.
283 </para>
285 <para><programlisting>
286 typedef enum _vfs_op_layer {
287 SMB_VFS_LAYER_NOOP = -1, /* - For using in VFS module to indicate end of array */
288 /* of operations description */
289 SMB_VFS_LAYER_OPAQUE = 0, /* - Final level, does not call anything beyond itself */
290 SMB_VFS_LAYER_TRANSPARENT, /* - Normal operation, calls underlying layer after */
291 /* possibly changing passed data */
292 SMB_VFS_LAYER_LOGGER, /* - Logs data, calls underlying layer, logging may not */
293 /* use Samba VFS */
294 SMB_VFS_LAYER_SPLITTER, /* - Splits operation, calls underlying layer _and_ own facility, */
295 /* then combines result */
296 SMB_VFS_LAYER_SCANNER /* - Checks data and possibly initiates additional */
297 /* file activity like logging to files _inside_ samba VFS */
298 } vfs_op_layer;
299 </programlisting></para>
301 </sect2>
303 </sect1>
305 <sect1>
306 <title>The Interaction between the Samba VFS subsystem and the modules</title>
308 <sect2>
309 <title>Initialization and registration</title>
311 <para>
312 As each Samba module a VFS module should have a
313 <programlisting>NTSTATUS vfs_example_init(void);</programlisting> function if it's staticly linked to samba or
314 <programlisting>NTSTATUS init_module(void);</programlisting> function if it's a shared module.
315 </para>
317 <para>
318 This should be the only non static function inside the module.
319 Global variables should also be static!
320 </para>
322 <para>
323 The module should register its functions via the
324 <programlisting>
325 NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
326 </programlisting> function.
327 </para>
329 <variablelist>
331 <varlistentry><term>version</term>
332 <listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
333 </varlistentry>
335 <varlistentry><term>name</term>
336 <listitem><para>this is the name witch can be listed in the
337 <command>vfs objects</command> parameter to use this module.</para></listitem>
338 </varlistentry>
340 <varlistentry><term>vfs_op_tuples</term>
341 <listitem><para>
342 this is an array of vfs_op_tuple's.
343 (vfs_op_tuples is descripted in details below.)
344 </para></listitem>
345 </varlistentry>
347 </variablelist>
349 <para>
350 For each operation the module wants to provide it has a entry in the
351 vfs_op_tuple array.
352 </para>
354 <programlisting>
355 typedef struct _vfs_op_tuple {
356 void* op;
357 vfs_op_type type;
358 vfs_op_layer layer;
359 } vfs_op_tuple;
360 </programlisting>
362 <variablelist>
364 <varlistentry><term>op</term>
365 <listitem><para>the function pointer to the specified function.</para></listitem>
366 </varlistentry>
368 <varlistentry><term>type</term>
369 <listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
370 </varlistentry>
372 <varlistentry><term>layer</term>
373 <listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
374 </varlistentry>
376 </variablelist>
378 <para>A simple example:</para>
380 <programlisting>
381 static vfs_op_tuple example_op_tuples[] = {
382 {SMB_VFS_OP(example_connect), SMB_VFS_OP_CONNECT, SMB_VFS_LAYER_TRANSPARENT},
383 {SMB_VFS_OP(example_disconnect), SMB_VFS_OP_DISCONNECT, SMB_VFS_LAYER_TRANSPARENT},
385 {SMB_VFS_OP(example_rename), SMB_VFS_OP_RENAME, SMB_VFS_LAYER_OPAQUE},
387 /* This indicates the end of the array */
388 {SMB_VFS_OP(NULL), SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP}
389 };
391 NTSTATUS init_module(void)
392 {
393 return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples);
394 }
395 </programlisting>
397 </sect2>
399 <sect2>
400 <title>How the Modules handle per connection data</title>
402 <para>Each VFS function has as first parameter a pointer to the modules vfs_handle_struct.
403 </para>
405 <programlisting>
406 typedef struct vfs_handle_struct {
407 struct vfs_handle_struct *next, *prev;
408 const char *param;
409 struct vfs_ops vfs_next;
410 struct connection_struct *conn;
411 void *data;
412 void (*free_data)(void **data);
413 } vfs_handle_struct;
414 </programlisting>
416 <variablelist>
418 <varlistentry><term>param</term>
419 <listitem><para>this is the module parameter specified in the <command>vfs objects</command> parameter.</para>
420 <para>e.g. for 'vfs objects = example:test' param would be "test".</para></listitem>
421 </varlistentry>
423 <varlistentry><term>vfs_next</term>
424 <listitem><para>This vfs_ops struct contains the information for calling the next module operations.
425 Use the SMB_VFS_NEXT_* macros to call a next module operations and
426 don't access handle->vfs_next.ops.* directly!</para></listitem>
427 </varlistentry>
429 <varlistentry><term>conn</term>
430 <listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
431 </varlistentry>
433 <varlistentry><term>data</term>
434 <listitem><para>This is a pointer for holding module private data.
435 You can alloc data with connection life time on the handle->conn->mem_ctx TALLOC_CTX.
436 But you can also manage the memory allocation yourself.</para></listitem>
437 </varlistentry>
439 <varlistentry><term>free_data</term>
440 <listitem><para>This is a function pointer to a function that free's the module private data.
441 If you talloc your private data on the TALLOC_CTX handle->conn->mem_ctx,
442 you can set this function pointer to NULL.</para></listitem>
443 </varlistentry>
445 </variablelist>
447 <para>Some useful MACROS for handle private data.
448 </para>
450 <programlisting>
451 #define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \
452 if (!(handle)||((datap=(type *)(handle)->data)==NULL)) { \
453 DEBUG(0,("%s() failed to get vfs_handle->data!\n",FUNCTION_MACRO)); \
454 ret; \
455 } \
456 }
458 #define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
459 if (!(handle)) { \
460 DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \
461 ret; \
462 } else { \
463 if ((handle)->free_data) { \
464 (handle)->free_data(&(handle)->data); \
465 } \
466 (handle)->data = (void *)datap; \
467 (handle)->free_data = free_fn; \
468 } \
469 }
471 #define SMB_VFS_HANDLE_FREE_DATA(handle) { \
472 if ((handle) && (handle)->free_data) { \
473 (handle)->free_data(&(handle)->data); \
474 } \
475 }
476 </programlisting>
478 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions.</para>
480 <para>The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros.
481 </para>
483 <programlisting>
484 ...
485 /* File operations */
486 #define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \
487 ((conn)->vfs_opaque.ops.open(\
488 (conn)->vfs_opaque.handles.open,\
489 (conn), (fname), (flags), (mode)))
490 #define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \
491 ((fsp)->conn->vfs_opaque.ops.close(\
492 (fsp)->conn->vfs_opaque.handles.close,\
493 (fsp), (fd)))
494 #define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \
495 ((fsp)->conn->vfs_opaque.ops.read(\
496 (fsp)->conn->vfs_opaque.handles.read,\
497 (fsp), (fd), (data), (n)))
498 #define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \
499 ((fsp)->conn->vfs_opaque.ops.write(\
500 (fsp)->conn->vfs_opaque.handles.write,\
501 (fsp), (fd), (data), (n)))
502 #define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \
503 ((fsp)->conn->vfs_opaque.ops.lseek(\
504 (fsp)->conn->vfs_opaque.handles.lseek,\
505 (fsp), (fd), (offset), (whence)))
506 #define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \
507 ((fsp)->conn->vfs_opaque.ops.sendfile(\
508 (fsp)->conn->vfs_opaque.handles.sendfile,\
509 (tofd), (fsp), (fromfd), (header), (offset), (count)))
510 ...
511 </programlisting>
513 <para>How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions.</para>
515 <para>The easiest way to do this is to use the SMB_VFS_NEXT_* macros.
516 </para>
518 <programlisting>
519 ...
520 /* File operations */
521 #define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \
522 ((handle)->vfs_next.ops.open(\
523 (handle)->vfs_next.handles.open,\
524 (conn), (fname), (flags), (mode)))
525 #define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \
526 ((handle)->vfs_next.ops.close(\
527 (handle)->vfs_next.handles.close,\
528 (fsp), (fd)))
529 #define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \
530 ((handle)->vfs_next.ops.read(\
531 (handle)->vfs_next.handles.read,\
532 (fsp), (fd), (data), (n)))
533 #define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \
534 ((handle)->vfs_next.ops.write(\
535 (handle)->vfs_next.handles.write,\
536 (fsp), (fd), (data), (n)))
537 #define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \
538 ((handle)->vfs_next.ops.lseek(\
539 (handle)->vfs_next.handles.lseek,\
540 (fsp), (fd), (offset), (whence)))
541 #define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \
542 ((handle)->vfs_next.ops.sendfile(\
543 (handle)->vfs_next.handles.sendfile,\
544 (tofd), (fsp), (fromfd), (header), (offset), (count)))
545 ...
546 </programlisting>
548 </sect2>
550 </sect1>
552 <sect1>
553 <title>Upgrading to the New VFS Interface</title>
555 <sect2>
556 <title>Upgrading from 2.2.* and 3.0alpha modules</title>
558 <orderedlist>
559 <listitem><para>
560 Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions.
561 e.g. example_connect(connection_struct *conn, const char *service, const char *user);
562 -> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user);
563 </para></listitem>
565 <listitem><para>
566 Replace "default_vfs_ops." with "smb_vfs_next_".
567 e.g. default_vfs_ops.connect(conn, service, user);
568 -> smb_vfs_next_connect(conn, service, user);
569 </para></listitem>
571 <listitem><para>
572 Uppercase all "smb_vfs_next_*" functions.
573 e.g. smb_vfs_next_connect(conn, service, user);
574 -> SMB_VFS_NEXT_CONNECT(conn, service, user);
575 </para></listitem>
577 <listitem><para>
578 Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls.
579 e.g. SMB_VFS_NEXT_CONNECT(conn, service, user);
580 -> SMB_VFS_NEXT_CONNECT(handle, conn, service, user);
581 </para></listitem>
583 <listitem><para>
584 (Only for 2.2.* modules)
585 Convert the old struct vfs_ops example_ops to
586 a vfs_op_tuple example_op_tuples[] array.
587 e.g.
588 <programlisting>
589 struct vfs_ops example_ops = {
590 /* Disk operations */
591 example_connect, /* connect */
592 example_disconnect, /* disconnect */
593 NULL, /* disk free *
594 /* Directory operations */
595 NULL, /* opendir */
596 NULL, /* readdir */
597 NULL, /* mkdir */
598 NULL, /* rmdir */
599 NULL, /* closedir */
600 /* File operations */
601 NULL, /* open */
602 NULL, /* close */
603 NULL, /* read */
604 NULL, /* write */
605 NULL, /* lseek */
606 NULL, /* sendfile */
607 NULL, /* rename */
608 NULL, /* fsync */
609 example_stat, /* stat */
610 example_fstat, /* fstat */
611 example_lstat, /* lstat */
612 NULL, /* unlink */
613 NULL, /* chmod */
614 NULL, /* fchmod */
615 NULL, /* chown */
616 NULL, /* fchown */
617 NULL, /* chdir */
618 NULL, /* getwd */
619 NULL, /* utime */
620 NULL, /* ftruncate */
621 NULL, /* lock */
622 NULL, /* symlink */
623 NULL, /* readlink */
624 NULL, /* link */
625 NULL, /* mknod */
626 NULL, /* realpath */
627 NULL, /* fget_nt_acl */
628 NULL, /* get_nt_acl */
629 NULL, /* fset_nt_acl */
630 NULL, /* set_nt_acl */
632 NULL, /* chmod_acl */
633 NULL, /* fchmod_acl */
635 NULL, /* sys_acl_get_entry */
636 NULL, /* sys_acl_get_tag_type */
637 NULL, /* sys_acl_get_permset */
638 NULL, /* sys_acl_get_qualifier */
639 NULL, /* sys_acl_get_file */
640 NULL, /* sys_acl_get_fd */
641 NULL, /* sys_acl_clear_perms */
642 NULL, /* sys_acl_add_perm */
643 NULL, /* sys_acl_to_text */
644 NULL, /* sys_acl_init */
645 NULL, /* sys_acl_create_entry */
646 NULL, /* sys_acl_set_tag_type */
647 NULL, /* sys_acl_set_qualifier */
648 NULL, /* sys_acl_set_permset */
649 NULL, /* sys_acl_valid */
650 NULL, /* sys_acl_set_file */
651 NULL, /* sys_acl_set_fd */
652 NULL, /* sys_acl_delete_def_file */
653 NULL, /* sys_acl_get_perm */
654 NULL, /* sys_acl_free_text */
655 NULL, /* sys_acl_free_acl */
656 NULL /* sys_acl_free_qualifier */
657 };
658 </programlisting>
659 ->
660 <programlisting>
661 static vfs_op_tuple example_op_tuples[] = {
662 {SMB_VFS_OP(example_connect), SMB_VFS_OP_CONNECT, SMB_VFS_LAYER_TRANSPARENT},
663 {SMB_VFS_OP(example_disconnect), SMB_VFS_OP_DISCONNECT, SMB_VFS_LAYER_TRANSPARENT},
665 {SMB_VFS_OP(example_fstat), SMB_VFS_OP_FSTAT, SMB_VFS_LAYER_TRANSPARENT},
666 {SMB_VFS_OP(example_stat), SMB_VFS_OP_STAT, SMB_VFS_LAYER_TRANSPARENT},
667 {SMB_VFS_OP(example_lstat), SMB_VFS_OP_LSTAT, SMB_VFS_LAYER_TRANSPARENT},
669 {SMB_VFS_OP(NULL), SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP}
670 };
671 </programlisting>
672 </para></listitem>
674 <listitem><para>
675 Move the example_op_tuples[] array to the end of the file.
676 </para></listitem>
678 <listitem><para>
679 Add the init_module() function at the end of the file.
680 e.g.
681 <programlisting>
682 NTSTATUS init_module(void)
683 {
684 return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,"example",example_op_tuples);
685 }
686 </programlisting>
687 </para></listitem>
689 <listitem><para>
690 Check if your vfs_init() function does more then just prepare the vfs_ops structs or
691 remember the struct smb_vfs_handle_struct.
692 <simplelist>
693 <member>If NOT you can remove the vfs_init() function.</member>
694 <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().
695 e.g. a debug class registration should go into init_module() and the allocation of private data should go to example_connect().</member>
696 </simplelist>
697 </para></listitem>
699 <listitem><para>
700 (Only for 3.0alpha* modules)
701 Check if your vfs_done() function contains needed code.
702 <simplelist>
703 <member>If NOT you can remove the vfs_done() function.</member>
704 <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().
705 </member>
706 </simplelist>
707 </para></listitem>
709 <listitem><para>
710 Check if you have any global variables left.
711 Decide if it wouldn't be better to have this data on a connection basis.
712 <simplelist>
713 <member>If NOT leave them as they are. (e.g. this could be the variable for the private debug class.)</member>
714 <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>
715 </simplelist>
717 e.g. if you have such a struct:
718 <programlisting>
719 struct example_privates {
720 char *some_string;
721 int db_connection;
722 };
723 </programlisting>
724 first way of doing it:
725 <programlisting>
726 static int example_connect(vfs_handle_struct *handle,
727 connection_struct *conn, const char *service,
728 const char* user)
729 {
730 struct example_privates *data = NULL;
732 /* alloc our private data */
733 data = (struct example_privates *)talloc_zero(conn->mem_ctx, sizeof(struct example_privates));
734 if (!data) {
735 DEBUG(0,("talloc_zero() failed\n"));
736 return -1;
737 }
739 /* init out private data */
740 data->some_string = talloc_strdup(conn->mem_ctx,"test");
741 if (!data->some_string) {
742 DEBUG(0,("talloc_strdup() failed\n"));
743 return -1;
744 }
746 data->db_connection = open_db_conn();
748 /* and now store the private data pointer in handle->data
749 * we don't need to specify a free_function here because
750 * we use the connection TALLOC context.
751 * (return -1 if something failed.)
752 */
753 VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
755 return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
756 }
758 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
759 {
760 struct example_privates *data = NULL;
762 /* get the pointer to our private data
763 * return -1 if something failed
764 */
765 SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
767 /* do something here...*/
768 DEBUG(0,("some_string: %s\n",data->some_string));
770 return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
771 }
772 </programlisting>
773 second way of doing it:
774 <programlisting>
775 static void free_example_privates(void **datap)
776 {
777 struct example_privates *data = (struct example_privates *)*datap;
779 SAFE_FREE(data->some_string);
780 SAFE_FREE(data);
782 *datap = NULL;
784 return;
785 }
787 static int example_connect(vfs_handle_struct *handle,
788 connection_struct *conn, const char *service,
789 const char* user)
790 {
791 struct example_privates *data = NULL;
793 /* alloc our private data */
794 data = (struct example_privates *)malloc(sizeof(struct example_privates));
795 if (!data) {
796 DEBUG(0,("malloc() failed\n"));
797 return -1;
798 }
800 /* init out private data */
801 data->some_string = strdup("test");
802 if (!data->some_string) {
803 DEBUG(0,("strdup() failed\n"));
804 return -1;
805 }
807 data->db_connection = open_db_conn();
809 /* and now store the private data pointer in handle->data
810 * we need to specify a free_function because we used malloc() and strdup().
811 * (return -1 if something failed.)
812 */
813 SMB_VFS_HANDLE_SET_DATA(handle, data, free_example_privates, struct example_privates, return -1);
815 return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
816 }
818 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
819 {
820 struct example_privates *data = NULL;
822 /* get the pointer to our private data
823 * return -1 if something failed
824 */
825 SMB_VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1);
827 /* do something here...*/
828 DEBUG(0,("some_string: %s\n",data->some_string));
830 return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
831 }
832 </programlisting>
833 </para></listitem>
835 <listitem><para>
836 To make it easy to build 3rd party modules it would be useful to provide
837 configure.in, (configure), install.sh and Makefile.in with the module.
838 (Take a look at the example in <filename>examples/VFS</filename>.)
839 </para>
841 <para>
842 The configure script accepts <option>--with-samba-source</option> to specify
843 the path to the samba source tree.
844 It also accept <option>--enable-developer</option> which lets the compiler
845 give you more warnings.
846 </para>
848 <para>
849 The idea is that you can extend this
850 <filename>configure.in</filename> and <filename>Makefile.in</filename> scripts
851 for your module.
852 </para></listitem>
854 <listitem><para>
855 Compiling & Testing...
856 <simplelist>
857 <member><userinput>./configure <option>--enable-developer</option></userinput> ...</member>
858 <member><userinput>make</userinput></member>
859 <member>Try to fix all compiler warnings</member>
860 <member><userinput>make</userinput></member>
861 <member>Testing, Testing, Testing ...</member>
862 </simplelist>
863 </para></listitem>
864 </orderedlist>
865 </sect2>
867 </sect1>
869 <sect1>
870 <title>Some Notes</title>
872 <sect2>
873 <title>Implement TRANSPARENT functions</title>
875 <para>
876 Avoid writing functions like this:
878 <programlisting>
879 static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
880 {
881 return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
882 }
883 </programlisting>
885 Overload only the functions you really need to!
886 </para>
888 </sect2>
890 <sect2>
891 <title>Implement OPAQUE functions</title>
893 <para>
894 If you want to just implement a better version of a
895 default samba opaque function
896 (e.g. like a disk_free() function for a special filesystem)
897 it's ok to just overload that specific function.
898 </para>
900 <para>
901 If you want to implement a database filesystem or
902 something different from a posix filesystem.
903 Make sure that you overload every vfs operation!!!
904 </para>
905 <para>
906 Functions your FS does not support should be overloaded by something like this:
907 e.g. for a readonly filesystem.
908 </para>
910 <programlisting>
911 static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
912 char *oldname, char *newname)
913 {
914 DEBUG(10,("function rename() not allowed on vfs 'example'\n"));
915 errno = ENOSYS;
916 return -1;
917 }
918 </programlisting>
920 </sect2>
922 </sect1>
924 </chapter>