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