newlib/winsup/doc/fhandler-tut.txt

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
dtable.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 dtable.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.