Work in progress. I'm still working on documenting many of the fs hooks, but I just wanted to commit this to quiet down the amount of warnings that are produced.

git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@21257 a95241bf-73f2-0310-859d-f6bbb57e9c96
2007-05-28 08:18:43 +00:00
parent c24f6c7e26
commit 8ace9affed
2 changed files with 1560 additions and 677 deletions
@@ -1,13 +1,21 @@
 /*
 * Copyright 2007 Haiku Inc. All rights reserved.
 * Distributed under the terms of the MIT License.
 *
 * Authors:
 *   Ingo Weinhold 
 */
 /*!
  \page fs_modules File System Modules
-To support a particular file system (FS), a kernel module implementing a special
+  To support a particular file system (FS), a kernel module implementing a
-interface (\c file_system_module_info defined in \c <fs_interface.h>) has to be
+  special interface (\c file_system_module_info defined in \c <fs_interface.h>)
-provided. As for any other module the
+  has to be provided. As for any other module the \c std_ops() hook is invoked
-\c std_ops() hook is invoked with \c B_MODULE_INIT directly after the FS module
+  with \c B_MODULE_INIT directly after the FS module has been loaded by the
-has been loaded by the kernel, and with \c B_MODULE_UNINIT before it is
+  kernel, and with \c B_MODULE_UNINIT before it is unloaded, thus providing
-unloaded, thus providing a simple mechanism for one-time module initializations.
+  a simple mechanism for one-time module initializations. The same module is
-The same module is used for accessing any volume of that FS type.
+  used for accessing any volume of that FS type.
  \section objects File System Objects
@@ -17,13 +25,14 @@ indirectly:
  - A \em volume is an instance of a file system. For a disk-based file
    system it corresponds to a disk, partition, or disk image file. When
-  mounting a volume the virtual file system layer (VFS) assigns a unique number
+    mounting a volume the virtual file system layer (VFS) assigns a unique
-  (ID, of type \c mount_id aka \c dev_t) to it and a handle (type
+    number (ID, of type \c mount_id aka \c dev_t) to it and a handle (type
    \c fs_volume, in fact \c void*) provided by
    the file system. Whenever the FS requests a volume-related service from the
    kernel, it has to pass the volume ID, and whenever the VFS asks the FS to
-  perform an operation, it supplies the handle. Normally the handle is a pointer
+    perform an operation, it supplies the handle. Normally the handle is a
-  to a data structure the FS allocates to associate data with the volume.
+    pointer to a data structure the FS allocates to associate data with the
    volume.
  - A \em node is contained by a volume. It can be of type file, directory, or
    symbolic link (symlink). Just as volumes nodes are associated with an ID
@@ -31,32 +40,33 @@ indirectly:
    (type \c fs_vnode, in fact \c void*).
    Unlike the volume ID the node ID is defined by the FS. It often
    has a meaning to the FS, e.g. file systems using inodes might choose the
-  inode number corresponding to the node. As long as the volume is mounted and
+    inode number corresponding to the node. As long as the volume is mounted
-  the node is known to the VFS, its node ID must not change. The node handle is
+    and the node is known to the VFS, its node ID must not change. The node
-  again a pointer to a data structure allocated by the FS.
+    handle is again a pointer to a data structure allocated by the FS.
  - A \em vnode (VFS node) is the VFS representation of a node. A volume may
-  contain a great number of nodes, but at a time only a few are represented by
+    contain a great number of nodes, but at a time only a few are represented
-  vnodes, usually only those that are currently in use (sometimes a few more).
+    by vnodes, usually only those that are currently in use (sometimes a few
    more).
- An \em entry (directory entry) belongs to a directory, has a name, and refers
+  - An \em entry (directory entry) belongs to a directory, has a name, and
-  to a node. It is important to understand the difference between entries and
+    refers to a node. It is important to understand the difference between
-  nodes: A node doesn't have a name, only the entries that refer to it have.
+    entries and nodes: A node doesn't have a name, only the entries that refer
-  If a FS supports to have more than one entry refer to a single node, it is
+    to it have. If a FS supports to have more than one entry refer to a single
-  also said to support "hard links". It is possible that no entry refers
+    node, it is also said to support "hard links". It is possible that no entry
-  to a node. This happens when a node (e.g. a file) is still open, but the last
+    refers to a node. This happens when a node (e.g. a file) is still open, but
-  entry referring to it has been removed (the node will be deleted when the
+    the last entry referring to it has been removed (the node will be deleted
-  it is closed). While entries are to be understood as independent entities,
+    when the it is closed). While entries are to be understood as independent
-  the FS interface does not use IDs or handles to refer to them; it always uses
+    entities, the FS interface does not use IDs or handles to refer to them;
-  directory and entry name pairs to do that.
+    it always uses directory and entry name pairs to do that.
  - An \em attribute is a named and typed data container belonging to a node. A
    node may have any number of attributes; they are organized in a (virtual or
    actually existing) attribute directory, through which one can iterate.
- An \em index is supposed to provide fast searching capabilities for attributes
+  - An \em index is supposed to provide fast searching capabilities for
-  with a certain name. A volume's index directory allows for iterating through
+    attributes with a certain name. A volume's index directory allows for
-  the indices.
+    iterating through the indices.
  - A \em query is a fully virtual object for searching for entries via an
    expression matching entry name, node size, node modification date, and/or
@@ -78,26 +88,28 @@ a few concepts that apply to several groups of them:
    <tt>free*_cookie()</tt>. The <tt>open*()</tt> hook is passed all that is
    needed to identify the object to be opened and, in some cases, additional
    parameters e.g. specifying a particular opening mode. The implementation
-  is required to return a cookie (type \c fs_cookie, in fact \c void*), usually
+    is required to return a cookie (type \c fs_cookie, in fact \c void*),
-  a pointer to a data structure the FS allocates. In some cases (e.g. when an
+    usually a pointer to a data structure the FS allocates. In some cases (e.g.
-  iteration state is associated with the cookie) a new cookie must be allocated
+    when an iteration state is associated with the cookie) a new cookie must
-  for each instance of opening the object. The cookie is passed to all hooks
+    be allocated for each instance of opening the object. The cookie is passed
-  that operate on a thusly opened object. The <tt>close*()</tt> hook is invoked
+    to all hooks that operate on a thusly opened object. The <tt>close*()</tt>
-  to signal that the cookie is to be closed. At this point the cookie might
+    hook is invoked to signal that the cookie is to be closed. At this point
-  still be in use. Blocking FS hooks (e.g. blocking read/write operations)
+    the cookie might still be in use. Blocking FS hooks (e.g. blocking
-  using the same cookie have to be unblocked. When the cookie stops being in
+    read/write operations) using the same cookie have to be unblocked. When
-  use the <tt>free*_cookie()</tt> hook is called; it has to free the cookie.
+    the cookie stops being in use the <tt>free*_cookie()</tt> hook is called;
    it has to free the cookie.
- <em>Entry Iteration</em>: For the FS objects serving as containers for other
+  - <em>Entry Iteration</em>: For the FS objects serving as containers for
-  objects, i.e. directories, attribute directories, the index directory,
+    other objects, i.e. directories, attribute directories, the index
-  and queries, the cookie mechanism is used for a stateful iteration through
+    directory, and queries, the cookie mechanism is used for a stateful
-  the contained objects. The <tt>read_*()</tt> hook reads the next one or more
+    iteration through the contained objects. The <tt>read_*()</tt> hook reads
-  entries into a <tt>struct dirent</tt> buffer. The <tt>rewind_*()</tt> hook
+    the next one or more entries into a <tt>struct dirent</tt> buffer. The
-  resets the iteration state to the first entry.
+    <tt>rewind_*()</tt> hook resets the iteration state to the first entry.
  - <em>Stat Information</em>: In case of nodes, attributes, and indices
-  detailed information about an object are requested via a <tt>read*_stat()</tt>
+    detailed information about an object are requested via a
-  hook and must be written into a <tt>struct stat</tt> buffer.
+    <tt>read*_stat()</tt> hook and must be written into a <tt>struct stat</tt>
    buffer.
  \section vnodes VNodes
@@ -106,15 +118,15 @@ A vnode is the VFS representation of a node. As soon as an access to a node
  is requested, the VFS creates a corresponding vnode. The requesting entity
  gets a reference to the vnode for the time it works with the vnode and
  releases the reference when done. When the last reference to a vnode has been
-surrendered, the vnode is unused and the VFS can decide to destroy it (usually
+  surrendered, the vnode is unused and the VFS can decide to destroy it
-it is cached for a while longer).
+  (usually it is cached for a while longer).
  When the VFS creates a vnode, it invokes the FS's
  \link file_system_module_info::get_vnode get_vnode() \endlink
  hook to let it create the respective node handle (unless the FS requests the
-creation of the vnode explicitely by calling publish_vnode()). That's the only
+  creation of the vnode explicitely by calling publish_vnode()). That's the
-hook that specifies a node by ID; to all other node-related hooks the node
+  only hook that specifies a node by ID; to all other node-related hooks the
-handle is passed. When the VFS deletes the vnode, it invokes the FS's
+  node handle is passed. When the VFS deletes the vnode, it invokes the FS's
  \link file_system_module_info::put_vnode put_vnode() \endlink
  hook or, if the node was marked removed,
  \link file_system_module_info::remove_vnode remove_vnode() \endlink.
@@ -122,17 +134,16 @@ hook or, if the node was marked removed,
  There are only four FS hooks through which the VFS gains knowledge of the
  existence of a node. The first one is the
  \link file_system_module_info::mount mount() \endlink
-hook. It is supposed to call \c publish_vnode() for the root node of the volume
+  hook. It is supposed to call \c publish_vnode() for the root node of the
-and return its ID. The second one is the
+  volume and return its ID. The second one is the
  \link file_system_module_info::lookup lookup() \endlink
  hook. Given a node handle of a directory and an entry name, it is supposed to
  call \c get_vnode() for the node the entry refers to and return the node ID.
  The remaining two hooks,
-\link file_system_module_info::read_dir read_dir() \endlink
+  \link file_system_module_info::read_dir read_dir() \endlink and
 and
  \link file_system_module_info::read_query read_query() \endlink,
-both return entries in a <tt>struct dirent</tt> structure, which also contains
+  both return entries in a <tt>struct dirent</tt> structure, which also
-the ID of the node the entry refers to.
+  contains the ID of the node the entry refers to.
  \section mandatory_hooks Mandatory Hooks
@@ -167,18 +178,20 @@ must implement:
    Open and close a node as explained in \ref concepts.
  - \link file_system_module_info::read read() \endlink:
-  Read data from an opened node (file). Even if the FS does not feature files,
+    Read data from an opened node (file). Even if the FS does not feature
-  the hook has to be present anyway; it should return an error in this case.
+    files, the hook has to be present anyway; it should return an error in this
    case.
  - \link file_system_module_info::open_dir open_dir() \endlink,
    \link file_system_module_info::close_dir close_dir() \endlink, and
    \link file_system_module_info::free_dir_cookie free_dir_cookie() \endlink:
-  Open and close a directory for entry iteration as explained in \ref concepts.
+    Open and close a directory for entry iteration as explained in
    \ref concepts.
  - \link file_system_module_info::read_dir read_dir() \endlink and
    \link file_system_module_info::rewind_dir rewind_dir() \endlink:
-  Read the next entry/entries from a directory, respectively reset the iterator
+    Read the next entry/entries from a directory, respectively reset the
-  to the first entry, as explained in \ref concepts.
+    iterator to the first entry, as explained in \ref concepts.
  Although not strictly mandatory, a FS should additionally implement the
  following hooks:
@@ -189,11 +202,11 @@ following hooks:
    supports.
  - \link file_system_module_info::read_symlink read_symlink() \endlink:
-  Read the value of a symbolic link. Needed only, if the FS and volume support
+    Read the value of a symbolic link. Needed only, if the FS and volume
-  symbolic links at all. If absent symbolic links stored on the volume won't
+    support symbolic links at all. If absent symbolic links stored on the
-  be interpreted.
+    volume won't be interpreted.
  - \link file_system_module_info::access access() \endlink:
-  Return whether the current user has the given access permissions for a node.
+    Return whether the current user has the given access permissions for a
-  If the hook is absent the user is considerd to have all permissions.
+    node. If the hook is absent the user is considerd to have all permissions.
 */