1 files changed, 83 insertions, 0 deletions
diff --git a/winsup/doc/fhandler-tut.txt b/winsup/doc/fhandler-tut.txt
new file mode 100644
index 000000000..52e08c768
--- /dev/null
+++ b/winsup/doc/fhandler-tut.txt
@@ -0,0 +1,83 @@
+fhandler tutorial
+
+This document will show how to add a new "fhandler" to cygwin, by
+showing an example of /dev/zero.
+
+Files to note:
+
+fhandler.h - must define a new derived class here and FH_*
+path.cc - to notice "/dev/zero" and mark it
+fhandler_zero.cc - new
+hinfo.cc - to create the fhandler instance
+
+OK, first we have to define what this new fhandler will do.  In our
+example case, we're going to implement the unix "/dev/zero" device,
+which has the following characteristics:
+
+* writes to /dev/zero are silently discarded
+* reads from /dev/zero return all zero bytes
+* mmap()ing /dev/zero maps a chunk of zero'd out memory.
+
+Since windows doesn't have a device that acts like this, we'll be
+simulating everything.  Thus:
+
+* writes simply return a success status
+* reads memset() the buffer and return success
+* we take advantage of the fact that CreateFileMapping can take a
+  handle of -1, which (1) maps swap memory, and (2) zeros it out for
+  us (at least, on NT).
+
+OK, let's start with fhandler.h.
+
+First, update the comment about which files are where.  We're adding
+fhandler_dev_zero as FH_DEV_ZERO.  We're adding this as a "fast"
+device (it will never block) so we have to adjust FH_NDEV also.
+
+Later in that file, we'll copy fhandler_dev_null and edit it to be
+fhandler_dev_zero.  I chose that one because it's small, but we'll add
+more members as we go (since we're simulating the whole thing).  In
+fact, let's copy the I/O methods from fhandler_windows since we'll
+need all those anyway, even though we'll go through the full list
+later.
+
+OK, next we need to edit path.cc to recognize when the user is trying
+to open "/dev/zero".  Look in get_device_number; there's a long list
+of cases, just add one (I added one after "null").  Also remember to
+add an entry to the windows_device_names list in the right spot.
+
+To go along with that change, we'll need to change hinfo.cc.  Look for
+FH_NULL and add a case for FH_ZERO as well.
+
+Now we get to fhandler_zero.cc itself.  Create the empty file and copy
+the "usual" header/copyright/includes from some other fhandler_*.cc
+source file.  Also, edit Makefile.in to build this new file.  Add one
+new entry to DLL_OFILES, and a new line for the winsup.h dependencies.
+
+Since we changed fhandler.h, when you type "make" it will rebuild
+everything.  Go ahead and do that when you get a chance to let it run,
+since we're not changing the headers any more.  Note that you won't be
+able to link the new dll, as we haven't added all the methods for the
+new fhandler class yet, but at least you'll get a lot of compilation
+out of the way.
+
+Next we start adding in the fhandler methods themselves.
+
+Constructor: This takes a name, and all we do is pass that name back
+to the base class, along with the FH_ZERO value.  We call set_cb
+because all fhandlers call this (it's for exec to copy the fd).
+
+open: we override the one that takes a name because there are no real
+windows devices like /dev/zero, but we ignore the name.  We call
+set_flags to save the flags.
+
+write: writes are discarded; we return success.
+
+read: reads read NUL bytes, so fill the buffer with NULs and return
+success.
+
+lseek/close: just return success.
+
+dump: this is just for debugging, so we just print something.
+
+select_*: we don't support this yet, see the myriad examples in
+select.cc for examples.  The base fhandler's methods will do for now.