summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--hurd/libnetfs.mdwn34
1 files changed, 17 insertions, 17 deletions
diff --git a/hurd/libnetfs.mdwn b/hurd/libnetfs.mdwn
index 41f39521..404ae3f0 100644
--- a/hurd/libnetfs.mdwn
+++ b/hurd/libnetfs.mdwn
@@ -10,7 +10,7 @@ is included in the section entitled
#libnetfs
-WHAT IS THIS
+##What This Is
This document is an attempt at a short overview of the main concepts
used in the process of development of translators using
@@ -20,7 +20,7 @@ required callbacks (for this take a look at
will **not** find a complete example of code either (usually,
*unionfs* is suggested as an example)
-WHAT IS LIBNETFS
+##What libnetfs Is
*libnetfs* is a Hurd library used in writing translators providing
some virtual directory structures. For example, if you would like to
@@ -37,7 +37,7 @@ make an archive look unpacked). As different from *libtrivfs*, using
*libnetfs*, you can show to your clients not just a single file, but a
whole directory tree.
-HOW IT WORKS: SHORT DESCRIPTION
+##How It Works: Short Description
With the aid of *libnetfs* a translator (supposedly) publishes a
directory tree. All lookups in this directory tree are directed to the
@@ -49,13 +49,13 @@ implement the required functionality in the corresponding callback or
just return an appropriate error code (for example, EOPNOTSUPP), if
the callback is compulsory.
-THE MAIN CONCEPTS: NODES
+##The Main Concepts: Nodes
The most fundamental thing to understand about *libnetfs* is the
notion of a **node**. Nearly always there are two types of nodes in a
*libnetfs*-based translator:
-* Generic **node**, defined in *<hurd/netfs.h>*. This node contains
+* Generic **node**, defined in *&lt;hurd/netfs.h&gt;*. This node contains
information read and written by the programmer (like field
*nn_stat*), as well as some internal information (like fields
*references* and *transbox*). Of course, the programmer is free to
@@ -71,7 +71,7 @@ operation. To some extent of certainty, a *libnetfs* node can be
perceived similarly to a filesystem node -- the building-brick out of
which everything is composed.
-As it can be seen from the definition in *<hurd/netfs.h>*, a reference
+As it can be seen from the definition in *&lt;hurd/netfs.h&gt;*, a reference
to a netnode is stored in each generic node. In a way, a netnode can
be perceived as the custom attachment to the information contained in
a generic node. The link between these is quite strong. At first this
@@ -119,10 +119,10 @@ to share netnodes, one would not be able to store additional
information per a *libnetfs* node, and this is quite a serious problem
in most practical problems.
-WHY A LIBNETFS NODE IS NOT QUITE A FILESYSTEM NODE
+##Why a libnetfs Node Is Not Quit a Filesystem Node
The most demonstrative argument in this case is the definition of
-*struct node* in *<hurd/netfs.h>*. If you try to find in this
+*struct node* in *&lt;hurd/netfs.h&gt;*. If you try to find in this
definition some reference to other generic node called *parent*, or an
array of references called *children* (which would be quite classical
for a member of a hierarchy), you will fail. There are fields *next*
@@ -148,7 +148,7 @@ result. Therefore, it is not quite right to perceive *libnetfs* nodes
as filesystem nodes. Instead, the focus of attention should stay upon
light nodes.
-HOW IT WORKS: A MORE VERBOSE DESCRIPTION
+##How It Wors: A More Verbose Description
At first let us see how the a *libnetfs*-based translator responds to
lookup requests. At the beginning the *netfs_attempt_lookup* callback
@@ -219,14 +219,14 @@ parameters to the corresponding *io_read* and *io_write* functions.
While browsing the code of very many *libnetfs*-based translators, you
might notice that they define callbacks starting with
-*netfs_S_*. Usually a name similar to that of one of the file
-management function follows (like netfs_S_*dir_lookup). These
+*netfs&#95;S&#95;*. Usually a name similar to that of one of the file
+management function follows (like netfs&#95;S&#95;*dir_lookup*). These
callbacks are triggered when the corresponding functions are called on
files shown by the translator. Such translators override parts of the
core functionality provided by *libnetfs* to achieve better
performance or to solve specific problems.
-SYNCHRONIZATION IS CRUCIAL
+##Synchronization is Crucial
A *libnetfs* programmer shall always keep in mind that, as different
from *libtrivfs*-based translators, *libnetfs*-based translators are
@@ -235,7 +235,7 @@ incorporates a lock. Moreover, each light node usually contains a
lock, too. This happens because *libnetfs* nodes and light nodes are
loosely coupled and are often processed separately.
-NODE CACHE
+##Node Cache
Most of *libnetfs* translators organize a *node cache*. However, this
structure is not a real cache. The idea is to hold some control over
@@ -254,7 +254,7 @@ overgrown, the nodes located at the tail of the list are removed from
the cache and the references to them are dropped. This triggers their
destruction (undertaken by *libnetfs*).
-WHAT FILES ARE USUALLY CREATED
+##What Files Are Usually Created
If you take into a look at the sources *ftpfs* or *unionfs* you will
notice files with names similar to the following:
@@ -270,10 +270,10 @@ notice files with names similar to the following:
* options.{c,h} -- here the option parsing mechanism is usually
placed. Argp parsers are implemented here.
-* <*translator_name*>.{c,h}, netfs.c -- the implementation of *netfs_\**
+* &lt;*translator_name*&gt;.{c,h}, netfs.c -- the implementation of *netfs_\**
callbacks will most probably lie in these files.
-WHAT NETNODES AND LIGHT NODES USUALLY CONTAIN
+##What Netnodes and Light Nodes Usually Contain
A **netnode** usually contains a reference to a light node, some flags
describing the state of the associated generic *libnetfs* node, and
@@ -289,7 +289,7 @@ hierarchical way, they contain a reference to their parent, a
reference to their first child, and references to their siblings
(usually not very descriptively called *next* and *prevp*).
-THE END
+##The End
I very much hope this piece of text was at least a little
helpful. Here I tried to explain the things which I understood least