1Intended audience 2================= 3 4This document is intended for everybody who wants to understand VFS 5code. Knowledge of programming is a must. 6 7 8Preface 9======= 10 11While VFS should be considered an excellent idea, which came ahead of 12its time, the implementation used in GNU Midnight Commander is now 13showing its age. 14 15The VFS code was left us without any decent documentation. Most 16functions don't have comments explaining what they do. Most comments 17describe quirks and implementation details, rather than the intended 18functionality of the code. This document is an attempt to reconstruct 19understanding of the VFS code and help its future developers. 20 21Being the part of GNU Midnight Commander most exposed to potential 22security threats, the VFS code needs to be kept is a good shape. 23Understanding the code is the key to making and keeping it secure. 24 25 26Basics of code organization 27=========================== 28 29VFS code it to a certain extent object oriented. The code dealing with 30a certain type of data (e.g. tar archives of SMB shares) can be thought 31of as a class in the terms of object oriented programming. They may 32reuse some code from their parent classes. For instance, tar and cpio 33archives have a common parent class direntry, which contains some common 34code for archives. 35 36Individual archives or connections can be considered as instances of 37those classes. They provide POSIX like interface to their structure, 38but don't expose that structure directly to the common VFS layer. 39 40Each VFS object has a directory tree associated with it. The tree 41consists of entries for files and directories. In some VFS classes, the 42entries have names and a are associated with nameless inodes, which 43contain information such as size, timestamps and other data normally 44contained in POSIX "struct stat". 45 46File vfs.c serves as a multiplexor. It exports functions similar to 47POSIX but with "mc_" prepended to them. For example, mc_open() will act 48like open(), but will treat VFS names in a special way. 49 50Common utility functions not intended to be used outside the VFS code 51should go to utilvfs.c and possibly to other files. Presently, there is 52a lot of such code in vfs.c. 53 54 55Hierarchy of classes 56==================== 57 58vfs ---- direntry ---- cpio } archives 59 | | ---- tar } 60 | | 61 | | ---- fish } remote systems 62 | | ---- ftpfs } 63 | 64 |---- extfs ---- extfs archives 65 |---- localfs ---- sfs ---- sfs archives 66 |---- smbfs 67 |---- undelfs 68 69 70Properties of classes 71===================== 72 73 read only inode->entry local cache full tree 74 mapping loaded 75 76cpio yes* yes* no yes 77tar yes* yes* no yes 78fish no yes yes no 79ftpfs no yes yes no 80extfs no no yes yes 81localfs no no N/A N/A 82sfs no yes yes N/A 83smbfs no yes no no 84undelfs no yes no yes 85 86 87"*" means that this property should change during further development. 88Mapping from inode to entry prevents implementing hard links. It is 89permissible for directories, which cannot be hardlinked. Not loading 90the full tree speeds up access to large archives and conserves memory. 91 92 93Stamping 94======== 95 96Stamping is the VFS equivalent of garbage collection. It's purpose is 97to destroy unreferenced VFS objects, in other words close archives or 98connections once they are unused for some time. There is a tree of 99items representing VFS objects. The common layer doesn't know the 100structure of the pointers, but it knows the class that should handle the 101pointer. Every item has a timestamp. Once the timestamp becomes too 102old, the object is freed. 103 104There are ways to keep objects alive if they are used. Also, objects 105can have parent objects, which are freed together with there original 106object if they are otherwise unreferenced. 107