Hurd server manual (first chunk)

[Marcus Brinkmann]

Hi,

I started to document the Hurd server interfaces in the style of a reference
manual.  The Hurd server interfaces are currently only documented in the
.defs files, which is a bit short on detail.  I wanted a place where I could
put all the lengthy explanations and rationale and protocols, and so I made
one.

This should probably be part of the big Hurd book some day, or the big Hurd
book will be split into different parts anyway.  Certainly not the time to
decide, a reference manual with all the Hurd server interfaces is definitely
self-contained enough to not need to worry about the grand plan too much when
writing it.

Currently, the following interfaces are documented (not 100% complete, but 90%):

auth, fsys, fs, interrupt

What comes next (in approximate order):

io, sockets, proc, exec, msg, crash, and then all the little others

In the end, you should be able to look at this manual and be able to
reimplement the Hurd specific parts of the C library (or most of it) from
scratch.  In other words, in writing the specification, I look not only at
the interface definition, but also at how the interfaces are actually used,
for example in hurd_lookup and in fork.

Server programmers should not really need this manual to be productive. 
Instead they should be able to stick with the library manuals which are
partly written.  However, I think that every serious server programmer would
quickly come to a point where details only found in the server interfaces
become relevant.

If you start to look into the manual, you will find out a strange thing: The
prototypes are all wrong!  This is on purpose.  I tried to write the manual
in a Mach-independent way.  For now we don't really have the abstraction
layer in code that is needed for that, but I just made up some missing type
names along the way, and just assumed that for what it's worth, the
semantics match those of Mach ports roughly.  So take it with a grain of
salt.  In the future, we will have to change this to match the actual
implementation.  I want to move away from Mach idiosyncrasis, also to explore
where we might be dependent on Mach specific features without being aware of
it, and thus prepare a port to L4 or whatever.

You can find it at:

ftp://alpha.gnu.org/gnu/hurd/contrib/marcus/hurd-server.texi

Plug it into the same directory as hurd.texi in the build tree, so it finds
the version.texi and gpl.texi.

Thanks to Alfred for helping me with the prototype madness!

Thanks,
Marcus


-- 
`Rhubarb is no Egyptian god.' GNU      http://www.gnu.org    marcus@gnu.org
Marcus Brinkmann              The Hurd http://www.gnu.org/software/hurd/
Marcus.Brinkmann@ruhr-uni-bochum.de
http://www.marcus-brinkmann.de/