Merge branch 'master' into master-news_next

10 files changed, 289 insertions, 63 deletions

diff --git a/hurd/debugging/rpctrace.mdwn b/hurd/debugging/rpctrace.mdwn
index 63b72ee0..46f40508 100644
--- a/hurd/debugging/rpctrace.mdwn
+++ b/hurd/debugging/rpctrace.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -24,7 +25,6 @@ See `rpctrace --help` about how to use it.
   * <http://savannah.gnu.org/patch/?1633> -- terminated with `C-c` `rpctrace`d
     programs hang
 * <http://savannah.gnu.org/patch/?5580> -- more readable output
-* <http://savannah.gnu.org/bugs/?20612> -- heisenbug
 
 
 # TODO
diff --git a/hurd/glibc.mdwn b/hurd/glibc.mdwn
index e975a239..454b8e34 100644
--- a/hurd/glibc.mdwn
+++ b/hurd/glibc.mdwn
@@ -1,4 +1,5 @@
-[[!meta copyright="Copyright © 2007, 2008 Free Software Foundation, Inc."]]
+[[!meta copyright="Copyright © 2007, 2008, 2009 Free Software Foundation,
+Inc."]]
 
 [[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
 id="license" text="Permission is granted to copy, distribute and/or modify this
@@ -16,3 +17,5 @@ For information about how the glibc integrates into the system, see sections
 [[Hurd-specific_API]].
 
 [[Debugging_glibc|debugging/glibc]].
+
+[[Internals.]]
diff --git a/hurd/glibc/internals.mdwn b/hurd/glibc/internals.mdwn
new file mode 100644
index 00000000..2ced0543
--- /dev/null
+++ b/hurd/glibc/internals.mdwn
@@ -0,0 +1,21 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled [[GNU Free Documentation
+License|/fdl]]."]]"""]]
+
+Some bits about this, some bits about that.
+
+---
+
+Hurd controlling tty behavior is generally consistent with BSD's, including
+`TIOCSCTTY`.  Linux also has `TIOCSCTTY` and it is harmless to use it there.
+But BSD and Hurd never do an implicit `TIOCSCTTY` (hence our `O_NOCTTY` is
+zero).
+
+C.f. <http://lists.gnu.org/archive/html/bug-hurd/2009-10/msg00030.html> and the
+following messages.
diff --git a/hurd/running/debian/faq/apt_umount.mdwn b/hurd/running/debian/faq/apt_umount.mdwn
index f2889f3e..db0dbfd1 100644
--- a/hurd/running/debian/faq/apt_umount.mdwn
+++ b/hurd/running/debian/faq/apt_umount.mdwn
@@ -22,4 +22,4 @@ Give executable permission to the script.
     # chmod +x /usr/bin/umount
 
 In `/etc/fstab` add a trailing `/` after cdrom like `/cdrom/` since apt uses a
-traing `/`.
+trailing `/`.
diff --git a/hurd/running/gnu/create_an_image.mdwn b/hurd/running/gnu/create_an_image.mdwn
index 2cdb8e27..c7a97a4e 100644
--- a/hurd/running/gnu/create_an_image.mdwn
+++ b/hurd/running/gnu/create_an_image.mdwn
@@ -27,7 +27,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
     create the necessary partitions (root and swap partitions boot, home ... if
     required)
 
-4. Create a file syatem for the root partiotion
+4. Create a file system for the root partition
 
         mke2fs /dev/hda1
 
@@ -39,7 +39,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
 6. Copy the file system from the host machine to the mounted directory (use a
     compressed file system to make the copying faster)
 
-    Grab the GNU spapshot from ams' site
+    Grab the GNU snapshot from ams' site
     <http://www.update.uu.se/~ams/home/slask/GNU/>
 
         scp <user>@<host>:<path to the compressed file system> disk
@@ -58,7 +58,7 @@ Creating a bootable qemu image from a root filesystem and bootloader
 
         poweroff
 
-10. To make the file syatem bootable download a grub floppy image
+10. To make the file system bootable download a grub floppy image
 
         <http://hurd.in/pub/Hurd/HurdOnVMware/grub.img>
 
diff --git a/hurd/running/gnu/setup.mdwn b/hurd/running/gnu/setup.mdwn
index 57a19054..2fb30c7b 100644
--- a/hurd/running/gnu/setup.mdwn
+++ b/hurd/running/gnu/setup.mdwn
@@ -8,7 +8,7 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-Setup is very easy (You need a GNU/Linux system to install GNU, we are developing an installer for GNU and if you want to help us join us on [[http://lists.gnu.org/mailman/listinfo/gnu-system-discuss][gnu-system-discuss]]), just follow these steps ...
+Setup is very easy (You need a GNU/Linux system to install GNU, we are developing an installer for GNU and if you want to help us join us on [gnu-system-discuss](http://lists.gnu.org/mailman/listinfo/gnu-system-discuss)), just follow these steps ...
 
 ## Step 1: Find a home for GNU 
 
diff --git a/hurd/translator.mdwn b/hurd/translator.mdwn
index 4995a005..e567938f 100644
--- a/hurd/translator.mdwn
+++ b/hurd/translator.mdwn
@@ -33,6 +33,17 @@ kernel and thus have absolute access to the machine.
 As the protocols do not require any special privilege
 to implement, this is not an issue on the Hurd.
 
+In Mach parlance, a *translator* is what they name a *server*: a process that
+participates in [[RPC]] interactions.  In the Hurd, a translator is a server
+that is additionally attached to a filesystem node.  Thus, it is quite common,
+even in the Hurd context, to speak about *server*s if you're stressing the RPC
+part, and on the other hand about *translator*s if you're stressing the
+filesystem part: a translator implements the [[interface/fs]] and
+[[interface/io]] interfaces.  For example: *the [[pfinet]] server implements
+the socket API calls (which are mapped by [[glibc]] to equivalent RPC calls)*,
+compared to *a [[libdiskfs]]-based translator implements a filesystem, based on
+a backing store*.
+
 To learn how to write a translator, read the code!
 It is well documented, in particular, the header files.
 The [[Hurd_Hacking_Guide]] also has a tutorial.
@@ -73,7 +84,7 @@ Read about translator [[short-circuiting]].
 * [[cvsfs]]
 * [[tmpfs]]
 * [[procfs]]
-* [[unionmount]]
+* [[nsmux]]
 * ...
 
 
diff --git a/hurd/translator/nsmux.mdwn b/hurd/translator/nsmux.mdwn
new file mode 100644
index 00000000..c07a30bd
--- /dev/null
+++ b/hurd/translator/nsmux.mdwn
@@ -0,0 +1,117 @@
+[[!meta copyright="Copyright © 2009 Free Software Foundation, Inc."]]
+
+[[!meta license="""[[!toggle id="license" text="GFDL 1.2+"]][[!toggleable
+id="license" text="Permission is granted to copy, distribute and/or modify this
+document under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no Invariant
+Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
+is included in the section entitled
+[[GNU Free Documentation License|/fdl]]."]]"""]]
+
+# nsmux
+
+`nsmux` implements the simplest use-case of namespace-based translator
+selection (see below).
+
+To use `nsmux` do the following:
+
+    $ settrans -a <node> nsmux <directory>
+
+After this operation `<node>` will be a mirror of `<directory>` with
+namespace-based translator selection functionality enabled.
+
+Please note that due to some details `nsmux` may complain a lot when
+run as a normal user.  This matter is the most urgent on the TODO
+list.
+
+## Source
+
+`nsmux` translator can be obtained with the following command:
+
+    $ git clone git://github.com/scolobb/nsmux.git
+
+`filter` translator can be obtained with the following command:
+
+    $ git clone git://github.com/scolobb/filter.git
+
+The filter is not yet working.
+
+It is highly probable that soon the code will be moved to Savannah.
+
+## Namespace-based Translator Selection
+
+Namespace-based translator selection is the special technique of using
+"magic" filenames for both accessing the file and setting translators
+on it.
+
+A "magic" filename is a filename which contains an unescaped sequence
+of two commas: ",,".  This sequence can be escaped by adding another
+comma: ",,,".  In the magic filename the part up to the first double
+commas is interpreted as the filename itself; the remaining segments
+into which the string is split by occurrences of ",," are treated as
+names of translators located under `/hurd/`.
+
+The simplest advantage before traditional way of setting
+translators is shown in the following examples.  Compare this
+
+    $ settrans -a file translator1
+    $ settrans -a file translator2
+    $ cat file
+
+to this:
+    
+    $ cat file,,translator1,,translator2
+   
+One simple command versus three more lengthy ones is an obvious
+improvement.  However, this advantage is not the only one and,
+probably, not even the most important.
+
+What is a good candidate for the most important advantage is that
+translators requested via "magic" filenames are session-bound.  In
+other words, by running `cat file,,translator` we set a translator
+visible *only* to `cat`, while the original file remains untranslated.
+Such session-specific translators are called **dynamic** and there is
+no (theoretical) way for a client to get a port to a dynamic
+translator requested by another client.
+
+Obviously, dynamic translators can be stacked, similarly to static
+translators.  Also, dynamic translator stacks may reside on top of
+static translator stacks.
+
+An important operation of namespace-based translator selection is
+*filtering*.  Filtering basically consists in looking up a translator
+by name in the stack and ignoring translators located on top of it.
+Note that filtering does not mean dropping some translators: in the
+current implementation a filter is expected to be a normal dynamic
+translator, included in the dynamic translator stack similarly to
+other translators.
+
+An important detail is that filtering is not limited to dynamic
+translator stacks: a filter should be able to descend into static
+translator stacks as well.
+
+Although the concept of filtering may seem purely abstract in the
+simplest use-case of setting dynamic translators on top of files, the
+situation changes greatly when dynamic translator stacks on top of
+directories are considered.  In this case, the implementation of
+namespace-based translator selection is expected to be able to
+propagate the dynamic translators associated with the directory down
+the directory structure.  That is, all files located under a directory
+opened with magic syntax, are expected to be translated by the same
+set of translators.  In this case having the possibility to
+specifically discard some of the translators set up on top of certain
+files is very useful.
+
+Note that the implementation of propagation of dynamic translators
+down directories is not fully conceived at the moment.  The
+fundamental problem is distinguishing between situations when the
+dynamic translators are to be set on the underlying files of the
+directory or on the directory itself.
+
+## Currently Implemented
+
+Currently there a working (though not heavily tested) implementation
+of the simplest use-case of namespace-based translator selection in
+the form of translator `nsmux`.  The filter is partially implemented
+and this is the immediate goal.  Propagating translators down
+directories is the next objective.
diff --git a/hurd/translator/unionfs.mdwn b/hurd/translator/unionfs.mdwn
index b177b874..331ad19f 100644
--- a/hurd/translator/unionfs.mdwn
+++ b/hurd/translator/unionfs.mdwn
@@ -8,17 +8,140 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
+# `unionfs`
+
+*Unionfs allows you to simply union one directory or translator into another one, so you see the files of both of them side by side.*
+
 Source repository: <http://git.savannah.gnu.org/cgit/hurd/unionfs.git/>
 
+Right now there are some problems with syncing, so please be aware
+that it might not work as expected.
 
-<a name="stowfs"></a>
-# `stowfs`
+<a name="unionmount"></a>
+# `unionmount`
 
 ... is a special mode of `unionfs`.
 
-# See Also
+## Project Idea
+
+When setting a translator on Hurd -- similar to mounting a file system on UNIX
+-- the new node(s) exported by the translator are obscuring the original node
+where the translator is set, and any nodes below it in the directory tree. The
+translator itself can access the underlying node (which is a very nice feature,
+as it allows translators presenting the contents of the node in a different
+format); but it's no longer accessible from the "outside".
+
+Plan9 has a feature where a file system can be mounted in union mode: the new
+file system doesn't obscure the mount point in this case, but instead the
+contents are combined. (This feature has also been under discussion in Linux
+for a couple of years now, under the label "VFS-based union mounts".)
+
+This kind of union mounts is generally useful, as it's sometimes more
+convenient than unioning existing filesystem locations with unionfs -- it's not
+necessary to mount a file system that is to be unioned at some external
+location first: just union-mount it directly at the target location.
+
+But union mounts also allow creating passive translator hierarchies: If there
+is a passive translator on a parent node, and further passive translators on
+child nodes, the union mount allows the child nodes with the further translator
+settings still to be visible after the parent translator has started.
+
+This could be useful for device nodes for example: let's say we have an
+ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
+directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
+the main /dev/veth node in the translator command line. It would be more
+elegant however to store the virtual nodes direcly below the main multiplexer
+node -- /dev/veth/0, /dev/veth/1 etc.
+
+There are two possible approaches how union mounts could be implemented in the
+Hurd. The first one is to let the various translators handle union mounts
+internally, i.e. let them present the underlying nodes to the clients in
+addition to the actual nodes they export themselfs. This probably can be
+implemented as some kind of extension to the existing netfs and diskfs
+libraries.
+
+The other possible apporach is less efficient and probably more tricky, but
+probably also more generic: create a special unionmount translator, which
+serves as a kind of proxy: setting the union-mounted translator on some
+internal node; and at the actual mount location, presenting a union of the
+nodes exported by this translator, and the nodes from the underlying file
+system.
+
+The goal of this project is implementing union mounts using either of the
+approaches described above. (Though it might be useful initially to prototype
+both for comparision.) The ethernet multiplexer shall serve as an example use
+case -- any changes necessary to allow using it with the union mount
+functionality are also to be considered part of the task.
+
+## Implementation
+
+### Source
+
+Union mounts are currently implemented as two additional command line
+options of the `unionfs` translator.  This implementation resides in
+the master-unionmount branch of the unionfs git repository.  To
+checkout the code, do the following:
+
+    $ git clone git://git.sv.gnu.org/hurd/unionfs.git
+    $ cd unionfs
+    $ git checkout -b master-unionmount
+    $ git pull origin master-unionmount
+
+You can skip the checkout step if you don't mind that the
+`master-unionmount` branch gets merged into the `master` branch.
+
+### Short Documentation
 
-  * [[unionmount]]
+The `unionmount` project adds options "--mount" and "--no-mount" to
+`unionfs` (short versions: "-t" and "-n" correspondingly).  Both
+options are used to implement union-mounting, but the first option
+will create a *transparent* union mount, while the second option will
+create a *nontransparent* union mount.
+
+One can create a transparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `<translator>`, not the
+`unionfs` translator.  Although this might seem the only natural way
+to do union mounts, one must keep in mind that such transparency
+deprives one of the possibility to modify the unioned virtual
+filesystem exported by `unionfs` at run-time (via `fsysopts`).
+
+One can create a nontransparent union mount with the following command:
+
+    $ settrans -a <node> unionfs --underlying --no-mount=<translator>
+
+When running
+
+    $ fsysopts <node>
+
+one will see the information about the `unionfs` translator.  Although
+this way allows modifying the contents of the unioned filesystem
+exported by `unionfs` at runtime, the access to `<translator>` is
+blocked.
+
+The filesystem exported by the *mountee* (`<translator>`) is actually
+treated like a normal filesystem within `unionfs`, which means that
+one can assign priorities to the *mountee* to achieve the desired
+order of layering of the unioned directories.  The following will make
+`unionfs` query the underlying filesystem first and then the
+*mountee*:
+
+    $ settrans -a <node> unionfs --priority=2 --underlying --priority=1 --mount=<translator>
+
+Note that the same functionality can also be achieved by assigning
+priority 1 to the underlying filesystem and keeping the priority of
+the *mountee* at 0.
+
+<a name="stowfs"></a>
+# `stowfs`
+
+... is a special mode of `unionfs`.
 
 # External Links
 
diff --git a/hurd/translator/unionmount.mdwn b/hurd/translator/unionmount.mdwn
index 47a3d85d..7384afc7 100644
--- a/hurd/translator/unionmount.mdwn
+++ b/hurd/translator/unionmount.mdwn
@@ -8,53 +8,4 @@ Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license
 is included in the section entitled
 [[GNU Free Documentation License|/fdl]]."]]"""]]
 
-[[!meta title="Union Mounts"]]
-
-When setting a translator on Hurd -- similar to mounting a file system on UNIX
--- the new node(s) exported by the translator are obscuring the original node
-where the translator is set, and any nodes below it in the directory tree. The
-translator itself can access the underlying node (which is a very nice feature,
-as it allows translators presenting the contents of the node in a different
-format); but it's no longer accessible from the "outside".
-
-Plan9 has a feature where a file system can be mounted in union mode: the new
-file system doesn't obscure the mount point in this case, but instead the
-contents are combined. (This feature has also been under discussion in Linux
-for a couple of years now, under the label "VFS-based union mounts".)
-
-This kind of union mounts is generally useful, as it's sometimes more
-convenient than unioning existing filesystem locations with unionfs -- it's not
-necessary to mount a file system that is to be unioned at some external
-location first: just union-mount it directly at the target location.
-
-But union mounts also allow creating passive translator hierarchies: If there
-is a passive translator on a parent node, and further passive translators on
-child nodes, the union mount allows the child nodes with the further translator
-settings still to be visible after the parent translator has started.
-
-This could be useful for device nodes for example: let's say we have an
-ethernet multiplexer at /dev/veth. Now the virtual subnodes could all be
-directly under /dev, i.e. /dev/veth0, /dev/veth1 etc., and explicitely refer to
-the main /dev/veth node in the translator command line. It would be more
-elegant however to store the virtual nodes direcly below the main multiplexer
-node -- /dev/veth/0, /dev/veth/1 etc.
-
-There are two possible approaches how union mounts could be implemented in the
-Hurd. The first one is to let the various translators handle union mounts
-internally, i.e. let them present the underlying nodes to the clients in
-addition to the actual nodes they export themselfs. This probably can be
-implemented as some kind of extension to the existing netfs and diskfs
-libraries.
-
-The other possible apporach is less efficient and probably more tricky, but
-probably also more generic: create a special unionmount translator, which
-serves as a kind of proxy: setting the union-mounted translator on some
-internal node; and at the actual mount location, presenting a union of the
-nodes exported by this translator, and the nodes from the underlying file
-system.
-
-The goal of this project is implementing union mounts using either of the
-approaches described above. (Though it might be useful initially to prototype
-both for comparision.) The ethernet multiplexer shall serve as an example use
-case -- any changes necessary to allow using it with the union mount
-functionality are also to be considered part of the task.
+[[!meta redir=unionfs#unionmount]]