"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
the uninterpreted source code file.
1 fhandler tutorial
3 This document will show how to add a new "fhandler" to cygwin, by
4 showing an example of /dev/zero.
6 Files to note:
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
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:
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.
21 Since windows doesn't have a device that acts like this, we'll be
22 simulating everything. Thus:
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).
30 OK, let's start with devices.h.
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.
36 Now, let's continue with fhandler.h.
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.
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
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.
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.
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.
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.
74 Next we start adding in the fhandler methods themselves.
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).
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.
84 write: writes are discarded; we return success.
86 read: reads read NUL bytes, so fill the buffer with NULs and return
89 lseek/close: just return success.
91 dump: this is just for debugging, so we just print something.
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.