diff options
Diffstat (limited to 'winsup/doc/fhandler-tut.txt')
| -rw-r--r-- | winsup/doc/fhandler-tut.txt | 94 |
1 files changed, 0 insertions, 94 deletions
diff --git a/winsup/doc/fhandler-tut.txt b/winsup/doc/fhandler-tut.txt deleted file mode 100644 index 00a3b4b94..000000000 --- a/winsup/doc/fhandler-tut.txt +++ /dev/null @@ -1,94 +0,0 @@ -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_* -devices.in - 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 devices.h. - -We have to create a new entry in the enum fh_devices. The new -devices must get a major and a minor ID. As a rule of thumb, just -copy the ones that are used on a linux system. - -Now, let's continue with fhandler.h. - -First, update the fhandler_union near the end of the file with a -line for the new device. Use existing members, in this case __dev_null -as a template. This union is sorted alphabetically. - -Earlier 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 devices.in. There is a section where each device -is listed with its cygwin path, its structure and its windows path. -"/dev/zero", FH_ZERO, "\\dev\\zero" -This is needed to recognize when the user is trying to open "/dev/zero". -You have to build devices.cc from devices.in now. -There is a script 'gendevices' in the winsup/cygwin directory which may -be called at some time in the future if you use 'make' to build the DLL. -This should rebuild the devices.cc file. You have to have shilka -available to do that; this is part of the cygwin cocom package. - -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. |