From: Alexander Bokovoy Date: Tue, 15 Apr 2008 14:53:18 +0000 (+0000) Subject: Next update of VFS modules development guide X-Git-Tag: samba-3.3.0pre1~1484 X-Git-Url: http://git.samba.org/?a=commitdiff_plain;h=d2c86fef8ce46e6ff265d472af3de671962c1a58;p=samba.git Next update of VFS modules development guide --- diff --git a/docs/Samba3-Developers-Guide/vfs.xml b/docs/Samba3-Developers-Guide/vfs.xml index 9005f5fd52d..44e0bd68636 100644 --- a/docs/Samba3-Developers-Guide/vfs.xml +++ b/docs/Samba3-Developers-Guide/vfs.xml @@ -22,39 +22,138 @@ The Samba (Posix) VFS layer -While most of Samba deployments are done using POSIX-compatible operating systems, -there is clearly more to a file system than what is required by POSIX when it comes to -adopting semantics of NT file system. Since Samba 2.2 all file-system related operations -go through an abstraction layer for virtual file system (VFS) that is modelled after -both POSIX and additional functions needed to transform NTFS semantics. +While most of Samba deployments are done using POSIX-compatible +operating systems, there is clearly more to a file system than what is +required by POSIX when it comes to adopting semantics of NT file +system. Since Samba 2.2 all file-system related operations go through +an abstraction layer for virtual file system (VFS) that is modelled +after both POSIX and additional functions needed to transform NTFS +semantics. -This abstraction layer now provides more features than a regular POSIX file system could -fill in. It is not required that all of them should be implemented by your -particular file system. However, when those features are available, Samba would advertize them to a -CIFS client and they might be used by an application and in case of Windows client that -might mean a client expects even more additional functionality when it encounters -those features. There is a practical reason to allow handling of this snowfall without modifying -the Samba core and it is fulfilled by providing an infrastructure to dynamically load -VFS modules at run time. +This abstraction layer now provides more features than a regular POSIX +file system could fill in. It is not required that all of them should +be implemented by your particular file system. However, when those +features are available, Samba would advertize them to a CIFS client +and they might be used by an application and in case of Windows client +that might mean a client expects even more additional functionality +when it encounters those features. There is a practical reason to +allow handling of this snowfall without modifying the Samba core and +it is fulfilled by providing an infrastructure to dynamically load VFS +modules at run time. -Each VFS module could implement a number of VFS operations. The way it does it is -irrelevant, only two things actually matter: whether specific implementation wants to cooperate -with other modules' implementations or not, and whether module needs to store additional -information that is specific to a context it is operating in. Multiple VFS modules could -be loaded at the same time and it is even possible to load several instances of the same -VFS module with different parameters. +Each VFS module could implement a number of VFS operations. The +way it does it is irrelevant, only two things actually matter: whether +specific implementation wants to cooperate with other modules' +implementations or not, and whether module needs to store additional +information that is specific to a context it is operating in. Multiple +VFS modules could be loaded at the same time and it is even possible +to load several instances of the same VFS module with different +parameters. The general interface +A VFS module has three major components: + +An initialization function that is +called during the module load to register implemented +operations. +An operations table representing a +mapping between statically defined module functions and VFS layer +operations. +Module functions that do actual +work. + + + +While this structure has been first applied to the VFS +subsystem, it is now commonly used across all Samba 3 subsystems that +support loadable modules. In fact, one module could provide a number +of interfaces to different subsystems by exposing different +operation tables through separate +initialization functions. + +An initialization function is used to +register module with Samba run-time. As Samba internal structures and +API are changed over lifetime, each released version has a VFS +interface version that is increased as VFS development progresses or +any of underlying Samba structures are changed in binary-incompatible +way. When VFS module is compiled in, VFS interface version of that +Samba environment is embedded into the module's binary object and is +checked by the Samba core upon module load. If VFS interface number +reported by the module isn't the same Samba core knows about, version +conflict is detected and module dropped to avoid any potential memory +corruption when accessing (changed) Samba structures. + + +Therefore, initialization function passes three parameters to the +VFS registration function, smb_register_vfs() + + interface version number, as constant + SMB_VFS_INTERFACE_VERSION, + module name, under which Samba core + will know it, and + an operations' table. + + + +The operations' table defines which +functions in the module would correspond to specific VFS operations +and how those functions would co-operate with the rest of VFS +subsystem. Each operation could perform in a following ways: + + transparent, meaning that while + operation is overriden, the module will still call a previous + implementation, before or after its own action. This mode is + indicated by the constant + SMB_VFS_LAYER_TRANSPARENT; + + opaque, for the implementations that + are terminating sequence of actions. For example, it is used to + implement POSIX operation on top of non-POSIX file system or even + not a file system at all, like a database for a personal audio + collection. Use constant SMB_VFS_LAYER_OPAQUE for + this mode; + splitter, a way when some file system + activity is done in addition to the transparently calling previous + implentation. This usually involves mangling the result of that call + before returning it back to the caller. This mode is selected by + SMB_VFS_LAYER_SPLITTER constant; + logger does not change anything or + performs any additional VFS operations. When + logger module acts, information about + operations is logged somewhere using an external facility (or + Samba's own debugging tools) but not the VFS layer. In order to + describe this type of activity use constant + SMB_VFS_LAYER_LOGGER; + + On contrary, scanner module does call + other VFS operations while processing the data that goes through the + system. This type of operation is indicated by the + SMB_VFS_LAYER_SCANNER constant. + + + +Fundamentally, there are three types: +transparent, opaque, and +logger. Splitter and +scanner may confuse developers (and indeed they +are confused as our experience has shown) but this separation is to +better expose the nature of a module's actions. Most of modules +developed so far are either one of those three fundamental types with +transparent and opaque being prevalent. + + -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.) +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.)