HACKING 4.1 KB

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