VFS Modules

diff -Npur --exclude=CVS --exclude=*.bak --exclude=*.o --exclude=*.po --exclude=*.so --exclude=.#* --exclude=Makefile --exclude=stamp-h --exclude=configure --exclude=findsmb --exclude=*proto*.h --exclude=build_env.h --exclude=tdbsam2_parse_info.h --exclude=config.* --exclude=bin --exclude=*.configure --exclude=autom4te.cache --exclude=build_options.c* 3_0/docs/docbook/devdoc/vfs.xml 3_0-vfs/docs/docbook/devdoc/vfs.xml --- 3_0/docs/docbook/devdoc/vfs.xml Thu Jan 1 01:00:00 1970 +++ 3_0-vfs/docs/docbook/devdoc/vfs.xml Mon May 19 12:46:34 2003 @@ -0,0 +1,786 @@ + + + + StefanMetzmacher + +

metze@metzemix.de

+ + + 27 April 2003 + + +VFS Modules + + +The Samba (Posix) VFS layer + + +The general interface + + +Each VFS operation has a vfs_op_type, a function pointer and a handle pointer in the +struct vfs_ops and tree macros to make it easier to call the operations. +(Take a look at include/vfs.h and include/vfs_macros.h.) + + + +typedef enum _vfs_op_type { + SMB_VFS_OP_NOOP = -1, + + ... + + /* File operations */ + + SMB_VFS_OP_OPEN, + SMB_VFS_OP_CLOSE, + SMB_VFS_OP_READ, + SMB_VFS_OP_WRITE, + SMB_VFS_OP_LSEEK, + SMB_VFS_OP_SENDFILE, + + ... + + SMB_VFS_OP_LAST +} vfs_op_type; + + +This struct contains the function and handle pointers for all operations. +struct vfs_ops { + struct vfs_fn_pointers { + ... + + /* File operations */ + + int (*open)(struct vfs_handle_struct *handle, + struct connection_struct *conn, + const char *fname, int flags, mode_t mode); + int (*close)(struct vfs_handle_struct *handle, + struct files_struct *fsp, int fd); + ssize_t (*read)(struct vfs_handle_struct *handle, + struct files_struct *fsp, int fd, void *data, size_t n); + ssize_t (*write)(struct vfs_handle_struct *handle, + struct files_struct *fsp, int fd, + const void *data, size_t n); + SMB_OFF_T (*lseek)(struct vfs_handle_struct *handle, + struct files_struct *fsp, int fd, + SMB_OFF_T offset, int whence); + ssize_t (*sendfile)(struct vfs_handle_struct *handle, + int tofd, files_struct *fsp, int fromfd, + const DATA_BLOB *header, SMB_OFF_T offset, size_t count); + + ... + } ops; + + struct vfs_handles_pointers { + ... + + /* File operations */ + + struct vfs_handle_struct *open; + struct vfs_handle_struct *close; + struct vfs_handle_struct *read; + struct vfs_handle_struct *write; + struct vfs_handle_struct *lseek; + struct vfs_handle_struct *sendfile; + + ... + } handles; +}; + + + +This macros SHOULD be used to call any vfs operation. +DO NOT ACCESS conn->vfs.ops.* directly !!! + +... + +/* File operations */ +#define SMB_VFS_OPEN(conn, fname, flags, mode) \ + ((conn)->vfs.ops.open((conn)->vfs.handles.open,\ + (conn), (fname), (flags), (mode))) +#define SMB_VFS_CLOSE(fsp, fd) \ + ((fsp)->conn->vfs.ops.close(\ + (fsp)->conn->vfs.handles.close, (fsp), (fd))) +#define SMB_VFS_READ(fsp, fd, data, n) \ + ((fsp)->conn->vfs.ops.read(\ + (fsp)->conn->vfs.handles.read,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_WRITE(fsp, fd, data, n) \ + ((fsp)->conn->vfs.ops.write(\ + (fsp)->conn->vfs.handles.write,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_LSEEK(fsp, fd, offset, whence) \ + ((fsp)->conn->vfs.ops.lseek(\ + (fsp)->conn->vfs.handles.lseek,\ + (fsp), (fd), (offset), (whence))) +#define SMB_VFS_SENDFILE(tofd, fsp, fromfd, header, offset, count) \ + ((fsp)->conn->vfs.ops.sendfile(\ + (fsp)->conn->vfs.handles.sendfile,\ + (tofd), (fsp), (fromfd), (header), (offset), (count))) + +... + + + + + +Possible VFS operation layers + + +These values are used by the VFS subsystem when building the conn->vfs +and conn->vfs_opaque structs for a connection with multiple VFS modules. +Internally, Samba differentiates only opaque and transparent layers at this process. +Other types are used for providing better diagnosing facilities. + + + +Most modules will provide transparent layers. Opaque layer is for modules +which implement actual file system calls (like DB-based VFS). For example, +default POSIX VFS which is built in into Samba is an opaque VFS module. + + + +Other layer types (logger, splitter, scanner) were designed to provide different +degree of transparency and for diagnosing VFS module behaviour. + + + +Each module can implement several layers at the same time provided that only +one layer is used per each operation. + + + +typedef enum _vfs_op_layer { + SMB_VFS_LAYER_NOOP = -1, /* - For using in VFS module to indicate end of array */ + /* of operations description */ + SMB_VFS_LAYER_OPAQUE = 0, /* - Final level, does not call anything beyond itself */ + SMB_VFS_LAYER_TRANSPARENT, /* - Normal operation, calls underlying layer after */ + /* possibly changing passed data */ + SMB_VFS_LAYER_LOGGER, /* - Logs data, calls underlying layer, logging may not */ + /* use Samba VFS */ + SMB_VFS_LAYER_SPLITTER, /* - Splits operation, calls underlying layer _and_ own facility, */ + /* then combines result */ + SMB_VFS_LAYER_SCANNER /* - Checks data and possibly initiates additional */ + /* file activity like logging to files _inside_ samba VFS */ +} vfs_op_layer; + + + + + + + +The Interaction between the Samba VFS subsystem and the modules + + +Initialization and registration + + +As each Samba module a VFS module should have a +NTSTATUS vfs_example_init(void); function if it's staticly linked to samba or +NTSTATUS init_module(void); function if it's a shared module. + + + +This should be the only non static function inside the module. +Global variables should also be static! + + + +The module should register its functions via the + +NTSTATUS smb_register_vfs(int version, const char *name, vfs_op_tuple *vfs_op_tuples); + function. + + + + +version +should be filled with SMB_VFS_INTERFACE_VERSION + + +name +this is the name witch can be listed in the +vfs objects parameter to use this module. + + +vfs_op_tuples + +this is an array of vfs_op_tuple's. +(vfs_op_tuples is descripted in details below.) + + + + + + +For each operation the module wants to provide it has a entry in the +vfs_op_tuple array. + + + +typedef struct _vfs_op_tuple { + void* op; + vfs_op_type type; + vfs_op_layer layer; +} vfs_op_tuple; + + + + +op +the function pointer to the specified function. + + +type +the vfs_op_type of the function to specified witch operation the function provides. + + +layer +the vfs_op_layer in witch the function operates. + + + + +A simple example: + + +static vfs_op_tuple example_op_tuples[] = { + {SMB_VFS_OP(example_connect), SMB_VFS_OP_CONNECT, SMB_VFS_LAYER_TRANSPARENT}, + {SMB_VFS_OP(example_disconnect), SMB_VFS_OP_DISCONNECT, SMB_VFS_LAYER_TRANSPARENT}, + + {SMB_VFS_OP(example_rename), SMB_VFS_OP_RENAME, SMB_VFS_LAYER_OPAQUE}, + + /* This indicates the end of the array */ + {NULL, SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP} +}; + +NTSTATUS init_module(void) +{ + return smb_register_vfs(SMB_VFS_INTERFACE_VERSION, "example", example_op_tuples); +} + + + + + +How the Modules handle per connection data + +Each VFS function has as first parameter a pointer to the modules vfs_handle_struct. + + + +typedef struct vfs_handle_struct { + struct vfs_handle_struct *next, *prev; + const char *param; + struct vfs_ops vfs_next; + struct connection_struct *conn; + void *data; + void (*free_data)(void **data); +} vfs_handle_struct; + + + + +param +this is the module parameter specified in the vfs objects parameter. +e.g. for 'vfs objects = example:test' param would be "test". + + +vfs_next +This vfs_ops struct contains the information for calling the next module operations. +Use the vfs_next_* macros to call a next module operations and +don't access handle->vfs_next.ops.* directly! + + +conn +This is a pointer back to the connection_struct to witch the handle belongs. + + +data +This is a pointer for holding module private data. +You can alloc data with connection life time on the handle->conn->mem_ctx TALLOC_CTX. +But you can also manage the memory allocation yourself. + + +free_data +This is a function pointer to a function that free's the module private data. +If you talloc your private data on the TALLOC_CTX handle->conn->mem_ctx, +you can set this function pointer to NULL. + + + + +Some usefull MACROS for handle private data. + + + +#define SMB_VFS_HANDLE_GET_DATA(handle, datap, type, ret) { \ + if (!(handle)||((datap=(type *)(handle)->data)==NULL)) { \ + DEBUG(0,("%s() failed to get vfs_handle->data!\n",FUNCTION_MACRO)); \ + ret; \ + } \ +} + +#define SMB_VFS_HANDLE_SET_DATA(handle, datap, free_fn, type, ret) { \ + if (!(handle)) { \ + DEBUG(0,("%s() failed to set handle->data!\n",FUNCTION_MACRO)); \ + ret; \ + } else { \ + if ((handle)->free_data) { \ + (handle)->free_data(&(handle)->data); \ + } \ + (handle)->data = (void *)datap; \ + (handle)->free_data = free_fn; \ + } \ +} + +#define SMB_VFS_HANDLE_FREE_DATA(handle) { \ + if ((handle) && (handle)->free_data) { \ + (handle)->free_data(&(handle)->data); \ + } \ +} + + +How SMB_VFS_LAYER_TRANSPARENT functions can call the SMB_VFS_LAYER_OPAQUE functions. + +The easiest way to do this is to use the SMB_VFS_OPAQUE_* macros. + + + +... +/* File operations */ +#define SMB_VFS_OPAQUE_OPEN(conn, fname, flags, mode) \ + ((conn)->vfs_opaque.ops.open(\ + (conn)->vfs_opaque.handles.open,\ + (conn), (fname), (flags), (mode))) +#define SMB_VFS_OPAQUE_CLOSE(fsp, fd) \ + ((fsp)->conn->vfs_opaque.ops.close(\ + (fsp)->conn->vfs_opaque.handles.close,\ + (fsp), (fd))) +#define SMB_VFS_OPAQUE_READ(fsp, fd, data, n) \ + ((fsp)->conn->vfs_opaque.ops.read(\ + (fsp)->conn->vfs_opaque.handles.read,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_OPAQUE_WRITE(fsp, fd, data, n) \ + ((fsp)->conn->vfs_opaque.ops.write(\ + (fsp)->conn->vfs_opaque.handles.write,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_OPAQUE_LSEEK(fsp, fd, offset, whence) \ + ((fsp)->conn->vfs_opaque.ops.lseek(\ + (fsp)->conn->vfs_opaque.handles.lseek,\ + (fsp), (fd), (offset), (whence))) +#define SMB_VFS_OPAQUE_SENDFILE(tofd, fsp, fromfd, header, offset, count) \ + ((fsp)->conn->vfs_opaque.ops.sendfile(\ + (fsp)->conn->vfs_opaque.handles.sendfile,\ + (tofd), (fsp), (fromfd), (header), (offset), (count))) +... + + +How SMB_VFS_LAYER_TRANSPARENT functions can call the next modules functions. + +The easiest way to do this is to use the SMB_VFS_NEXT_* macros. + + + +... +/* File operations */ +#define SMB_VFS_NEXT_OPEN(handle, conn, fname, flags, mode) \ + ((handle)->vfs_next.ops.open(\ + (handle)->vfs_next.handles.open,\ + (conn), (fname), (flags), (mode))) +#define SMB_VFS_NEXT_CLOSE(handle, fsp, fd) \ + ((handle)->vfs_next.ops.close(\ + (handle)->vfs_next.handles.close,\ + (fsp), (fd))) +#define SMB_VFS_NEXT_READ(handle, fsp, fd, data, n) \ + ((handle)->vfs_next.ops.read(\ + (handle)->vfs_next.handles.read,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_NEXT_WRITE(handle, fsp, fd, data, n) \ + ((handle)->vfs_next.ops.write(\ + (handle)->vfs_next.handles.write,\ + (fsp), (fd), (data), (n))) +#define SMB_VFS_NEXT_LSEEK(handle, fsp, fd, offset, whence) \ + ((handle)->vfs_next.ops.lseek(\ + (handle)->vfs_next.handles.lseek,\ + (fsp), (fd), (offset), (whence))) +#define SMB_VFS_NEXT_SENDFILE(handle, tofd, fsp, fromfd, header, offset, count) \ + ((handle)->vfs_next.ops.sendfile(\ + (handle)->vfs_next.handles.sendfile,\ + (tofd), (fsp), (fromfd), (header), (offset), (count))) +... + + + + + + + +Upgrading to the New VFS Interface + + +Upgrading from 2.2.* and 3.0aplha modules + + + +Add "vfs_handle_struct *handle, " as first parameter to all vfs operation functions. +e.g. example_connect(connection_struct *conn, const char *service, const char *user); +-> example_connect(vfs_handle_struct *handle, connection_struct *conn, const char *service, const char *user); + + + +Replace "default_vfs_ops." with "vfs_next_". +e.g. default_vfs_ops.connect(conn, service, user); +-> vfs_next_connect(conn, service, user); + + + +Uppercase all "vfs_next_*" functions. +e.g. vfs_next_connect(conn, service, user); +-> SMB_VFS_NEXT_CONNECT(conn, service, user); + + + +Add "handle, " as first parameter to all SMB_VFS_NEXT_*() calls. +e.g. SMB_VFS_NEXT_CONNECT(conn, service, user); +-> SMB_VFS_NEXT_CONNECT(handle, conn, service, user); + + + +(Only for 2.2.* modules) +Convert the old struct vfs_ops example_ops to +a vfs_op_tuple example_op_tuples[] array. +e.g. + +struct vfs_ops example_ops = { + /* Disk operations */ + example_connect, /* connect */ + example_disconnect, /* disconnect */ + NULL, /* disk free * + /* Directory operations */ + NULL, /* opendir */ + NULL, /* readdir */ + NULL, /* mkdir */ + NULL, /* rmdir */ + NULL, /* closedir */ + /* File operations */ + NULL, /* open */ + NULL, /* close */ + NULL, /* read */ + NULL, /* write */ + NULL, /* lseek */ + NULL, /* sendfile */ + NULL, /* rename */ + NULL, /* fsync */ + example_stat, /* stat */ + example_fstat, /* fstat */ + example_lstat, /* lstat */ + NULL, /* unlink */ + NULL, /* chmod */ + NULL, /* fchmod */ + NULL, /* chown */ + NULL, /* fchown */ + NULL, /* chdir */ + NULL, /* getwd */ + NULL, /* utime */ + NULL, /* ftruncate */ + NULL, /* lock */ + NULL, /* symlink */ + NULL, /* readlink */ + NULL, /* link */ + NULL, /* mknod */ + NULL, /* realpath */ + NULL, /* fget_nt_acl */ + NULL, /* get_nt_acl */ + NULL, /* fset_nt_acl */ + NULL, /* set_nt_acl */ + + NULL, /* chmod_acl */ + NULL, /* fchmod_acl */ + + NULL, /* sys_acl_get_entry */ + NULL, /* sys_acl_get_tag_type */ + NULL, /* sys_acl_get_permset */ + NULL, /* sys_acl_get_qualifier */ + NULL, /* sys_acl_get_file */ + NULL, /* sys_acl_get_fd */ + NULL, /* sys_acl_clear_perms */ + NULL, /* sys_acl_add_perm */ + NULL, /* sys_acl_to_text */ + NULL, /* sys_acl_init */ + NULL, /* sys_acl_create_entry */ + NULL, /* sys_acl_set_tag_type */ + NULL, /* sys_acl_set_qualifier */ + NULL, /* sys_acl_set_permset */ + NULL, /* sys_acl_valid */ + NULL, /* sys_acl_set_file */ + NULL, /* sys_acl_set_fd */ + NULL, /* sys_acl_delete_def_file */ + NULL, /* sys_acl_get_perm */ + NULL, /* sys_acl_free_text */ + NULL, /* sys_acl_free_acl */ + NULL /* sys_acl_free_qualifier */ +}; + +-> + +static vfs_op_tuple example_op_tuples[] = { + {SMB_VFS_OP(example_connect), SMB_VFS_OP_CONNECT, SMB_VFS_LAYER_TRANSPARENT}, + {SMB_VFS_OP(example_disconnect), SMB_VFS_OP_DISCONNECT, SMB_VFS_LAYER_TRANSPARENT}, + + {SMB_VFS_OP(example_fstat), SMB_VFS_OP_FSTAT, SMB_VFS_LAYER_TRANSPARENT}, + {SMB_VFS_OP(example_stat), SMB_VFS_OP_STAT, SMB_VFS_LAYER_TRANSPARENT}, + {SMB_VFS_OP(example_lstat), SMB_VFS_OP_LSTAT, SMB_VFS_LAYER_TRANSPARENT}, + + {NULL, SMB_VFS_OP_NOOP, SMB_VFS_LAYER_NOOP} +}; + + + + +Move the example_op_tuples[] array to the end of the file. + + + +Add the init_module() function at the end of the file. +e.g. + +NTSTATUS init_module(void) +{ + return smb_register_vfs(SMB_VFS_INTERFACE_VERSION,"example",example_op_tuples); +} + + + + +Check if your vfs_init() function does more then just prepare the vfs_ops structs or +remember the struct smb_vfs_handle_struct. +- If NOT you can remove the vfs_init() function. +- 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(). + e.g. + - a debug class registration should go into init_module(). + - the allocation of private data should go to example_connect(). + + + +(Only for 3.0aplha* modules) +Check if your vfs_done() function contains needed code. +- If NOT you can remove the vfs_done() function. +- 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 MODULES section of the Samba-Developer-HOWTO.) + And then remove vfs_done(). + e.g. the freeing of private data should go to example_disconnect(). + + + +Check if you have any global variables left. +- Decide if it wouldn't be better to have this data on a connection basis. + - If NOT leave them as they are. + (e.g. this could be the variable for the private debug class.) + - 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. + + e.g. if you have such a struct: + +struct example_privates { + char *some_string; + int db_connection; +}; + +1st way of doing it: + +static int example_connect(vfs_handle_struct *handle, + connection_struct *conn, const char *service, + const char* user) +{ + struct example_privates *data = NULL; + + /* alloc our private data */ + data = (struct example_privates *)talloc_zero(conn->mem_ctx, sizeof(struct example_privates)); + if (!data) { + DEBUG(0,("talloc_zero() failed\n")); + return -1; + } + + /* init out private data */ + data->some_string = talloc_strdup(conn->mem_ctx,"test"); + if (!data->some_string) { + DEBUG(0,("talloc_strdup() failed\n")); + return -1; + } + + data->db_connection = open_db_conn(); + + /* and now store the private data pointer in handle->data + * we don't need to specify a free_function here because + * we use the connection TALLOC context. + * (return -1 if something failed.) + */ + VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1); + + return SMB_VFS_NEXT_CONNECT(handle,conn,service,user); +} + +static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) +{ + struct example_privates *data = NULL; + + /* get the pointer to our private data + * return -1 if something failed + */ + VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1); + + /* do something here...*/ + DEBUG(0,("some_string: %s\n",data->some_string)); + + return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); +} + +2nd way of doing it: + +static void free_example_privates(void **datap) +{ + struct example_privates *data = (struct example_privates *)*datap; + + SAFE_FREE(data->some_string); + SAFE_FREE(data); + + datap = NULL; + + return; +} + +static int example_connect(vfs_handle_struct *handle, + connection_struct *conn, const char *service, + const char* user) +{ + struct example_privates *data = NULL; + + /* alloc our private data */ + data = (struct example_privates *)malloc(sizeof(struct example_privates)); + if (!data) { + DEBUG(0,("malloc() failed\n")); + return -1; + } + + /* init out private data */ + data->some_string = strdup(conn->mem_ctx,"test"); + if (!data->some_string) { + DEBUG(0,("strdup() failed\n")); + return -1; + } + + data->db_connection = open_db_conn(); + + /* and now store the private data pointer in handle->data + * we need to specify a free_function because we used malloc() and strdup(). + * (return -1 if something failed.) + */ + VFS_HANDLE_SET_DATA(handle, data, NULL, struct example_privates, return -1); + + return SMB_VFS_NEXT_CONNECT(handle,conn,service,user); +} + +static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) +{ + struct example_privates *data = NULL; + + /* get the pointer to our private data + * return -1 if something failed + */ + VFS_HANDLE_GET_DATA(handle, data, struct example_privates, return -1); + + /* do something here...*/ + DEBUG(0,("some_string: %s\n",data->some_string)); + + return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); +} + + + + +To make it easy to build 3rd party modules it would be usefull to provide +configure.in, (configure), install.sh and Makefile.in with the module. +(Take a look at the example in examples/VFS.) + +The configure script accept --with-samba-source to specify the path to +the samba source tree. +It also accept --enable-developer witch let the compiler give you more warnings. + +The idea is that you can extend this configure.in and Makefile.in scripts +for your module. + + + +Compiling & Testing... +- configure --enable-developer ... +- make +- Try to fiy all compiler warnings +- make +- Testing, Testing, Testing ... + + + + + + + +Some Notes + + +Implement TRANSPARENT functions + + +Avoid to functions loke this: + + +static int example_close(vfs_handle_struct *handle, files_struct *fsp, int fd) +{ + return SMB_VFS_NEXT_CLOSE(handle, fsp, fd); +} + + +Overload only the functions you really need to! + + + + + +Implement OPAQUE functions + + +If you want just implement only a better version of a +default samba opaque function +(e.g. like a disk_free() function for a speciall filesystem) +it's ok to just overload this specific function. + + + +If you want to implement a database filesystem or +something different from a posix filesystem. +Make sure that you overload every vfs operation!!! + + +Functions your FS didn't support should be overloaded by something like this: +e.g. for a readonly filesystem. + + + +static int example_rename(vfs_handle_struct *handle, connection_struct *conn, + char *oldname, char *newname) +{ + DEBUG(10,("function rename() not allowed on vfs 'example'\n")); + errno = ENOSYS; + return -1; +} + + + + + + +