lib/vfs/README

   1 NOTE: Although vfs has been meant to be implemented as a separate
   2 entity redistributable under the LGPL in its current implementation it
   3 uses GPLed code from src/. So there are two possibilities if you want
   4 to use vfs:
   5
   6 1. Distribute your copy of vfs under the GPL. Then you can freely
   7 include the GPLed functions from the rest of the mc source code.
   8
   9 2. Distribute your copy of vfs under the LGPL. Then you cannot include
  10 the functions outside the vfs subdirectory. You must then either
  11 rewrite them or work around them in other ways.
  12
  13 ========================================================================
  14
  15 Hi!
  16
  17 I'm midnight commander's vfs layer. Before you start hacking me,
  18 please read this file. I'm integral part of midnight commander, but I
  19 try to go out and live my life myself as a shared library, too. That
  20 means that I should try to use as little functions from midnight as
  21 possible (so I'm tiny, nice and people like me), that I should not
  22 pollute name space by unnecessary symbols (so I do not crash fellow
  23 programs) and that I should have a clean interface between myself and
  24 midnight.
  25
  26 Because I'm trying to live life on my own as libvfs.so, try to:
  27
  28 * Make sure all exported symbols are defined in vfs.h and begin with
  29 'vfs_'.
  30
  31 * Do not make any references from midnight into modules like tar. It
  32 would probably pollute name space and midnight would depend on concrete
  33 configuration of libvfs. mc_setctl() and mc_ctl() are your
  34 friends. (And mine too :-).
  35
  36                                                          Pavel Machek
  37                                                          pavel@ucw.cz
  38
  39 Preface
  40 =======
  41
  42 While VFS should be considered an excellent idea, which came ahead of
  43 its time, the implementation used in GNU Midnight Commander is now
  44 showing its age.
  45
  46 The VFS code was left us without any decent documentation.  Most
  47 functions don't have comments explaining what they do.  Most comments
  48 describe quirks and implementation details, rather than the intended
  49 functionality of the code.  This document is an attempt to reconstruct
  50 understanding of the VFS code and help its future developers.
  51
  52 Being the part of GNU Midnight Commander most exposed to potential
  53 security threats, the VFS code needs to be kept is a good shape.
  54 Understanding the code is the key to making and keeping it secure.
  55
  56
  57 Basics of code organization
  58 ===========================
  59
  60 VFS code it to a certain extent object oriented.  The code dealing with
  61 a certain type of data (e.g. tar archives) can be thought
  62 of as a class in the terms of object oriented programming.  They may
  63 reuse some code from their parent classes.  For instance, tar and cpio
  64 archives have a common parent class direntry, which contains some common
  65 code for archives.
  66
  67 Individual archives or connections can be considered as instances of
  68 those classes.  They provide POSIX like interface to their structure,
  69 but don't expose that structure directly to the common VFS layer.
  70
  71 Each VFS object has a directory tree associated with it.  The tree
  72 consists of entries for files and directories.  In some VFS classes, the
  73 entries have names and a are associated with nameless inodes, which
  74 contain information such as size, timestamps and other data normally
  75 contained in POSIX "struct stat".
  76
  77 File vfs.c serves as a multiplexor.  It exports functions similar to
  78 POSIX but with "mc_" prepended to them.  For example, mc_open() will act
  79 like open(), but will treat VFS names in a special way.
  80
  81 Common utility functions not intended to be used outside the VFS code
  82 should go to utilvfs.c and possibly to other files.  Presently, there is
  83 a lot of such code in vfs.c.
  84
  85
  86 Hierarchy of classes
  87 ====================
  88
  89 vfs ---- direntry ---- cpio  } archives
  90    |            | ---- tar   }
  91    |            |
  92    |            | ---- fish  } remote systems
  93    |            | ---- ftpfs }
  94    |
  95    |---- extfs ---- extfs archives
  96    |---- localfs ---- sfs ---- sfs archives
  97    |---- undelfs
  98
  99
 100 Properties of classes
 101 =====================
 102
 103                    read only    inode->entry   local cache   full tree
 104                                 mapping                      loaded
 105
 106 cpio               yes*         yes*           no            yes
 107 tar                yes*         yes*           no            yes
 108 fish               no           yes            yes           no
 109 ftpfs              no           yes            yes           no
 110 extfs              no           no             yes           yes
 111 localfs            no           no             N/A           N/A
 112 sfs                no           yes            yes           N/A
 113 undelfs            no           yes            no            yes
 114
 115
 116 "*" means that this property should change during further development.
 117 Mapping from inode to entry prevents implementing hard links.  It is
 118 permissible for directories, which cannot be hardlinked.  Not loading
 119 the full tree speeds up access to large archives and conserves memory.
 120
 121
 122 Stamping
 123 ========
 124
 125 Stamping is the VFS equivalent of garbage collection.  It's purpose is
 126 to destroy unreferenced VFS objects, in other words close archives or
 127 connections once they are unused for some time.  There is a tree of
 128 items representing VFS objects.  The common layer doesn't know the
 129 structure of the pointers, but it knows the class that should handle the
 130 pointer.  Every item has a timestamp.  Once the timestamp becomes too
 131 old, the object is freed.
 132
 133 There are ways to keep objects alive if they are used.  Also, objects
 134 can have parent objects, which are freed together with there original
 135 object if they are otherwise unreferenced.