vfs/HACKING

   1 Intended audience
   2 =================
   3
   4 This document is intended for everybody who wants to understand VFS
   5 code.  Knowledge of programming is a must.
   6
   7
   8 Preface
   9 =======
  10
  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
  13 showing its age.
  14
  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.
  20
  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.
  24
  25
  26 Basics of code organization
  27 ===========================
  28
  29 VFS code it to a certain extent object oriented.  The code dealing with
  30 a certain type of data (e.g. tar archives of SMB shares) 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
  34 code for archives.
  35
  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.
  39
  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".
  45
  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.
  49
  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.
  53
  54
  55 Hierarchy of classes
  56 ====================
  57
  58 vfs ---- direntry ---- cpio  } archives
  59    |            | ---- tar   }
  60    |            |
  61    |            | ---- fish  } remote systems
  62    |            | ---- ftpfs }
  63    |
  64    |---- extfs ---- extfs archives
  65    |---- localfs ---- sfs ---- sfs archives
  66    |---- mcfs
  67    |---- smbfs
  68    |---- undelfs
  69
  70
  71 Properties of classes
  72 =====================
  73
  74                    read only    inode->entry   local cache   full tree
  75                                 mapping                      loaded
  76
  77 cpio               yes*         yes*           no            yes
  78 tar                yes*         yes*           no            yes
  79 fish               no           yes            yes           no
  80 ftpfs              no           yes            yes           no
  81 extfs              no           no             yes           yes
  82 localfs            no           no             N/A           N/A
  83 sfs                no           yes            yes           N/A
  84 mcfs               no           yes            no            no
  85 smbfs              no           yes            no            no
  86 undelfs            no           yes            no            yes
  87
  88
  89 "*" means that this property should change during further development.
  90 Mapping from inode to entry prevents implementing hard links.  It is
  91 permissible for directories, which cannot be hardlinked.  Not loading
  92 the full tree speeds up access to large archives and conserves memory.
  93
  94
  95 Stamping
  96 ========
  97
  98 Stamping is the VFS equivalent of garbage collection.  It's purpose is
  99 to destroy unreferenced VFS objects, in other words close archives or
 100 connections once they are unused for some time.  There is a tree of
 101 items representing VFS objects.  The common layer doesn't know the
 102 structure of the pointers, but it knows the class that should handle the
 103 pointer.  Every item has a timestamp.  Once the timestamp becomes too
 104 old, the object is freed.
 105
 106 There are ways to keep objects alive if they are used.  Also, objects
 107 can have parent objects, which are freed together with there original
 108 object if they are otherwise unreferenced.