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">
6
<firstname>Alexander</firstname><surname>Bokovoy</surname>
8
<address><email>ab@samba.org</email></address>
12
<firstname>Stefan</firstname><surname>Metzmacher</surname>
14
<address><email>metze@samba.org</email></address>
17
<pubdate> 27 May 2003 </pubdate>
20
<title>VFS Modules</title>
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
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
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
58
<title>The general interface</title>
60
<para>A VFS module has three major components:
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
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.
93
<para>Therefore, initialization function passes three parameters to the
94
VFS registration function, <literal>smb_register_vfs()</literal>
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>
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:
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>;
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>;
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>
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.
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>.)
159
<para><programlisting>
160
typedef enum _vfs_op_type {
161
SMB_VFS_OP_NOOP = -1,
165
/* File operations */
178
</programlisting></para>
180
<para>This struct contains the function and handle pointers for all operations.<programlisting>
182
struct vfs_fn_pointers {
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);
207
struct vfs_handles_pointers {
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;
222
</programlisting></para>
225
This macros SHOULD be used to call any vfs operation.
226
DO NOT ACCESS conn->vfs.ops.* directly !!!
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)))
255
</programlisting></para>
260
<title>Possible VFS operation layers</title>
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.
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.
276
Other layer types (logger, splitter, scanner) were designed to provide different
277
degree of transparency and for diagnosing VFS module behaviour.
281
Each module can implement several layers at the same time provided that only
282
one layer is used per each operation.
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 */
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 */
299
</programlisting></para>
306
<title>The Interaction between the Samba VFS subsystem and the modules</title>
309
<title>Initialization and registration</title>
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.
318
This should be the only non static function inside the module.
319
Global variables should also be static!
323
The module should register its functions via the
325
NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples);
326
</programlisting> function.
331
<varlistentry><term>version</term>
332
<listitem><para>should be filled with SMB_VFS_INTERFACE_VERSION</para></listitem>
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>
340
<varlistentry><term>vfs_op_tuples</term>
342
this is an array of vfs_op_tuple's.
343
(vfs_op_tuples is descripted in details below.)
350
For each operation the module wants to provide it has a entry in the
355
typedef struct _vfs_op_tuple {
364
<varlistentry><term>op</term>
365
<listitem><para>the function pointer to the specified function.</para></listitem>
368
<varlistentry><term>type</term>
369
<listitem><para>the vfs_op_type of the function to specified witch operation the function provides.</para></listitem>
372
<varlistentry><term>layer</term>
373
<listitem><para>the vfs_op_layer in whitch the function operates.</para></listitem>
378
<para>A simple example:</para>
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}
391
NTSTATUS init_module(void)
393
return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples);
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.
406
typedef struct vfs_handle_struct {
407
struct vfs_handle_struct *next, *prev;
409
struct vfs_ops vfs_next;
410
struct connection_struct *conn;
412
void (*free_data)(void **data);
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>
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>
429
<varlistentry><term>conn</term>
430
<listitem><para>This is a pointer back to the connection_struct to witch the handle belongs.</para></listitem>
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>
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>
447
<para>Some useful MACROS for handle private data.
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)); \
458
#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \
460
DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \
463
if ((handle)->free_data) { \
464
(handle)->free_data(&(handle)->data); \
466
(handle)->data = (void *)datap; \
467
(handle)->free_data = free_fn; \
471
#define SMB_VFS_HANDLE_FREE_DATA(handle) { \
472
if ((handle) && (handle)->free_data) { \
473
(handle)->free_data(&(handle)->data); \
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.
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,\
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)))
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.
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,\
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)))
553
<title>Upgrading to the New VFS Interface</title>
556
<title>Upgrading from 2.2.* and 3.0alpha modules</title>
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);
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);
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);
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);
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.
589
struct vfs_ops example_ops = {
590
/* Disk operations */
591
example_connect, /* connect */
592
example_disconnect, /* disconnect */
594
/* Directory operations */
600
/* File operations */
609
example_stat, /* stat */
610
example_fstat, /* fstat */
611
example_lstat, /* lstat */
620
NULL, /* ftruncate */
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 */
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}
675
Move the example_op_tuples[] array to the end of the file.
679
Add the init_module() function at the end of the file.
682
NTSTATUS init_module(void)
684
return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,"example",example_op_tuples);
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.
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>
700
(Only for 3.0alpha* modules)
701
Check if your vfs_done() function contains needed code.
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().
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.
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>
717
e.g. if you have such a struct:
719
struct example_privates {
724
first way of doing it:
726
static int example_connect(vfs_handle_struct *handle,
727
connection_struct *conn, const char *service,
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));
735
DEBUG(0,("talloc_zero() failed\n"));
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"));
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.)
753
VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1);
755
return SMB_VFS_NEXT_CONNECT(handle,conn,service,user);
758
static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
760
struct example_privates *data = NULL;
762
/* get the pointer to our private data
763
* return -1 if something failed
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);
773
second way of doing it:
775
static void free_example_privates(void **datap)
777
struct example_privates *data = (struct example_privates *)*datap;
779
SAFE_FREE(data->some_string);
787
static int example_connect(vfs_handle_struct *handle,
788
connection_struct *conn, const char *service,
791
struct example_privates *data = NULL;
793
/* alloc our private data */
794
data = (struct example_privates *)malloc(sizeof(struct example_privates));
796
DEBUG(0,("malloc() failed\n"));
800
/* init out private data */
801
data->some_string = strdup("test");
802
if (!data->some_string) {
803
DEBUG(0,("strdup() failed\n"));
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.)
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);
818
static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
820
struct example_privates *data = NULL;
822
/* get the pointer to our private data
823
* return -1 if something failed
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);
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>.)
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.
849
The idea is that you can extend this
850
<filename>configure.in</filename> and <filename>Makefile.in</filename> scripts
855
Compiling & Testing...
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>
870
<title>Some Notes</title>
873
<title>Implement TRANSPARENT functions</title>
876
Avoid writing functions like this:
879
static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd)
881
return SMB_VFS_NEXT_CLOSE(handle, fsp, fd);
885
Overload only the functions you really need to!
891
<title>Implement OPAQUE functions</title>
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.
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!!!
906
Functions your FS does not support should be overloaded by something like this:
907
e.g. for a readonly filesystem.
911
static int example_rename(vfs_handle_struct *handle, connection_struct *conn,
912
char *oldname, char *newname)
914
DEBUG(10,("function rename() not allowed on vfs 'example'\n"));