"Fossies" - the Fresh Open Source Software Archive

Member "cygwin-snapshot-20210913-1/winsup/doc/fhandler-tut.txt" (7 May 2021, 3889 Bytes) of package /windows/misc/cygwin-20210913-src-x86_64.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 fhandler tutorial
    2 
    3 This document will show how to add a new "fhandler" to cygwin, by
    4 showing an example of /dev/zero.
    5 
    6 Files to note:
    7 
    8 fhandler.h - must define a new derived class here and FH_*
    9 devices.in - to notice "/dev/zero" and mark it
   10 fhandler_zero.cc - new
   11 dtable.cc - to create the fhandler instance
   12 
   13 OK, first we have to define what this new fhandler will do.  In our
   14 example case, we're going to implement the unix "/dev/zero" device,
   15 which has the following characteristics:
   16 
   17 * writes to /dev/zero are silently discarded
   18 * reads from /dev/zero return all zero bytes
   19 * mmap()ing /dev/zero maps a chunk of zero'd out memory.
   20 
   21 Since windows doesn't have a device that acts like this, we'll be
   22 simulating everything.  Thus:
   23 
   24 * writes simply return a success status
   25 * reads memset() the buffer and return success
   26 * we take advantage of the fact that CreateFileMapping can take a
   27   handle of -1, which (1) maps swap memory, and (2) zeros it out for
   28   us (at least, on NT).
   29 
   30 OK, let's start with devices.h.
   31 
   32 We have to create a new entry in the enum fh_devices.  The new
   33 devices must get a major and a minor ID.  As a rule of thumb, just
   34 copy the ones that are used on a linux system.
   35 
   36 Now, let's continue with fhandler.h.
   37 
   38 First, update the fhandler_union near the end of the file with a
   39 line for the new device.  Use existing members, in this case __dev_null
   40 as a template.  This union is sorted alphabetically.
   41 
   42 Earlier in that file, we'll copy fhandler_dev_null and edit it to be
   43 fhandler_dev_zero.  I chose that one because it's small, but we'll add
   44 more members as we go (since we're simulating the whole thing).  In
   45 fact, let's copy the I/O methods from fhandler_windows since we'll
   46 need all those anyway, even though we'll go through the full list
   47 later.
   48 
   49 OK, next we need to edit devices.in.  There is a section where each device
   50 is listed with its cygwin path, its structure and its windows path.
   51 "/dev/zero", FH_ZERO, "\\dev\\zero"
   52 This is needed to recognize when the user is trying to open "/dev/zero".
   53 You have to build devices.cc from devices.in now.
   54 There is a script 'gendevices' in the winsup/cygwin directory which may
   55 be called at some time in the future if you use 'make' to build the DLL.
   56 This should rebuild the devices.cc file.  You have to have shilka
   57 available to do that; this is part of the cygwin cocom package.
   58 
   59 To go along with that change, we'll need to change dtable.cc.  Look for
   60 FH_NULL and add a case for FH_ZERO as well.
   61 
   62 Now we get to fhandler_zero.cc itself.  Create the empty file and copy
   63 the "usual" header/copyright/includes from some other fhandler_*.cc
   64 source file.  Also, edit Makefile.in to build this new file.  Add one
   65 new entry to DLL_OFILES, and a new line for the winsup.h dependencies.
   66 
   67 Since we changed fhandler.h, when you type "make" it will rebuild
   68 everything.  Go ahead and do that when you get a chance to let it run,
   69 since we're not changing the headers any more.  Note that you won't be
   70 able to link the new dll, as we haven't added all the methods for the
   71 new fhandler class yet, but at least you'll get a lot of compilation
   72 out of the way.
   73 
   74 Next we start adding in the fhandler methods themselves.
   75 
   76 Constructor: This takes a name, and all we do is pass that name back
   77 to the base class, along with the FH_ZERO value.  We call set_cb
   78 because all fhandlers call this (it's for exec to copy the fd).
   79 
   80 open: we override the one that takes a name because there are no real
   81 windows devices like /dev/zero, but we ignore the name.  We call
   82 set_flags to save the flags.
   83 
   84 write: writes are discarded; we return success.
   85 
   86 read: reads read NUL bytes, so fill the buffer with NULs and return
   87 success.
   88 
   89 lseek/close: just return success.
   90 
   91 dump: this is just for debugging, so we just print something.
   92 
   93 select_*: we don't support this yet, see the myriad examples in
   94 select.cc for examples.  The base fhandler's methods will do for now.