Tryag File Manager
Home
-
Turbo Force
Current Path :
/
usr
/
share
/
doc
/
gamin-0.1.7
/
Upload File :
New :
File
Dir
//usr/share/doc/gamin-0.1.7/gamin.html
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <meta http-equiv="Content-Type" content="text/html"> <title>Gamin the File Alteration Monitor</title> </head> <body style="color: #000000;background-color: #FFFFFF"> <h1 style="text-align: center">Gamin the File Alteration Monitor</h1> <p>Gamin is a file and directory monitoring system defined to be a subset of the <a href="http://oss.sgi.com/projects/fam/">FAM</a> (File Alteration Monitor) system. This is a service provided by a library which allows to detect when a file or a directory has been modified.</p> <h2><a name="Overview">Overview</a></h2> <p>Gamin is a file and directory monitoring system defined to be a subset of the <a href="http://oss.sgi.com/projects/fam/">FAM</a> (File Alteration Monitor) system.</p> <p>The main goals of the project are:</p> <ol> <li>minimize the security model of FAM, the daemon runs under the user account, it is compatible with SELinux</li> <li>simplify the code base, dropping some of the most exotic feature of FAM</li> <li>provide an API and ABI compatible replacement for FAM</li> <li>try to fix some other issues like resource consumption</li> </ol> <p>Gamin also serves as an interface to test the inotify mechanism to improve the existing dnotify monitoring interface present in the Linux kernel.</p> <p>At this point Gamin is fairly tied to Linux, portability is not a primary goal at this stage but if you have portability patches they are welcome.</p> <p>From an historical point of view, gamin builds from the marmot project authored by James Willcox and Corey Bowers and then heavilly modified to turn it into a minimalist FAM replacement (Francophones will appreciate the filiation from fam to marmot and gamin.)</p> <p>This library is available under the terms of the <a href="http://www.gnu.org/copyleft/lesser.html">GNU LIBRARY GENERAL PUBLIC LICENSE</a>, and a <a href="http://www.opensource.org/licenses/lgpl-license.php">copy</a> of it should be found in the source under the COPYING file.</p> <h2><a name="Using">Using gamin</a></h2> <p>Basically it is exactly like for using the fam interface. From a programmer point of view this is the same API, and one can make use of <a href="http://techpubs.sgi.com/library/tpl/cgi-bin/getdoc.cgi?coll=0650&db=bks&fname=/SGI_Developer/books/IIDsktp_IG/sgi_html/ch08.html">the existing FAM documentation</a>.</p> <h2><a name="Config">Configuration</a></h2> <p>By default gamin should work without needing any configuration, but sometimes using the kernel notification APIs doesn't work or lead to troubles (for example when trying to unmount device). By default gamin revert to using polling for all paths matching <code>/mnt/*</code> or <code>/media/*</code> on Linux. This may be overriden or extended by the one of the three config files <code>/etc/gamin/gaminrc</code>, <code>$HOME/.gaminrc</code>, <code>/etc/gamin/mandatory_gaminrc</code> (note that prior to 0.1.4 only <code>$HOME/.gaminrc</code> was used and fsset was not implemented). Here is an example of such a configuration file:</p> <pre># configuration for gamin # Can be used to override the default behaviour. # notify filepath(s) : indicate to use kernel notification # poll filepath(s) : indicate to use polling instead # fsset fsname method poll_limit : indicate what method of notification for the filesystem # kernel - use the kernel for notification # poll - use polling for notification # none - don't use any notification # # the poll_limit is the number of seconds # that must pass before a resource is polled again. # It is optional, and if it is not present the previous # value will be used or the default. notify /mnt/local* /mnt/pictures* # use kernel notification on these paths poll /temp/* # use poll notification on these paths fsset nfs poll 10 # use polling on nfs mounts and poll once every 10 seconds </pre> <p>The configuration file accepts only 3 types of command:</p> <ul> <li>notify : to express that kernel monitoring should be used for matching paths</li> <li>poll: to express that polling should be used for matching paths</li> <li>fsset: to control what notification method is used on a filesystem type</li> </ul> <p>The three config files are loaded in this order:</p> <ul> <li><code>/etc/gamin/gaminrc</code></li> <li><code>~/.gaminrc</code></li> <li><code>/etc/gamin/mandatory_gaminrc</code></li> </ul> <p>The mandatory config file allows the system administrator to override any potentially dangerous preferences set by the user.</p> <p>When checking a path to guess whether polling or kernel notification should be used, gamin checks first the user provided rules in their declaration order within the configuration file and then check the predefined rules. This way the first declaration for <code>/mnt/local*</code> in the example override the default one for <code>/mnt/*</code> .</p> <p>If gamin is not told to use poll on a particular path, it will then try and decide based on the filesystem the path is located on</p> <p><em>Caveat: separators in the config file should be spaces, not tabs.</em></p> <h2><a name="News">News</a></h2> <h3>0.1.7: Oct 27 2005</h3> <ul> <li>Portability fixes (Diego Pettenò, Sjoerd Simons, Daichi Kawahata)</li> <li>A small memory leak fix (Christopher Aillon)</li> <li>Fixes for gam_server segfaults (Ed Catmur, DV)</li> <li>One last patch for Python detection</li> </ul> <h3>0.1.6: Sep 8 2005</h3> <ul> <li>Large revamp of the inotify back-end (John McCutchan)</li> <li>Code reorganization, changes for polling (John McCutchan)</li> <li>Portability patches for NetBSD (Johnny Lam)</li> <li>Fix compilation without inotify</li> <li>environment variable GAM_TEST_DNOTIFY to force dnotify on inotify kernels (John McCutchan)</li> <li>Inotify race conditions fixes (John McCutchan)</li> <li>Removal of some asserts resulting in crashes</li> <li>Applied some testing patches (TomPh)</li> <li>Fixed a memory leak on inotify back-end</li> <li>Python detection fix</li> </ul> <h3>0.1.5: Aug 9 2005</h3> <ul> <li>Improvement of configuration, system wide configuration files and per filesystem type default (John McCutchan)</li> <li>Rewrite of the inotify back-end, reduce resources usage, tuning in case of busy resources (John McCutchan)</li> <li>Documentation updates</li> <li>Changes to compile inotify back-end on various architectures</li> <li>Debugging output improvements</li> </ul> <h3>0.1.3: Aug 2 2005</h3> <ul> <li> Fix to compile on older gcc versions (Jean-Yves Lefort)</li> <li> Inotify back-end changes and optimizations (John McCutchan)</li> <li> Debug ouput cleanup, pid and process name reports (John McCutchan)</li> <li> Dropped kernel monitor bugfix (John McCutchan)</li> <li> Removed the old glist copy used for debugging</li> <li> Maintain mounted filesystems knowledge, and per fstype preferences (John McCutchan)</li> </ul> <h3>0.1.2: Jul 13 2005</h3> <ul> <li> More patches from John McCutchan for the inotify back-end, inotify is now in Linus's kernel tree, a patch for the new kernel API was needed.</li> <li> Lot of cleanup patches from Neal H. Walfield affecting most of the server code.</li> <li> Fixed an authentication problem.</li> </ul> <h3>0.1.1: Jun 10 2005</h3> <ul> <li> Bug fixes: gamin_data_conn_event (Mark McLoughlin), crash from bug #303932 (Frederic Crozat), Inotify and mounted media #171201 (John McCutchan), monitoring multiple files in busy directories #159748 (mounted media did not show up on Desktop), write may not be atomic (Neal H. Walfield), Monitoring a directory when it is a file. <li> Portability to Hurd/Mach and various code cleanups (Neal H. Walfield) <li> Added support for ~ as user home alias in .gaminrc </ul> <h3>0.1.0: May 12 2005</h3> <ul> <li>Close inherited file descriptors on exec of gam_server</li> <li>Cancelling a monitor send back a FAMAcknowledge based on patch by Christophe Saout</li> <li>Fixed for big files > 2GB</li> <li>Bug when monitoring a non existing directory</li> <li>Make client side thread safe (Nicholas Miell base patch)</li> <li>Unreadable directory fixes (Nickolay Shmyrev)</li> <li>A lot more regression tests, more debugging support and code cleanups.</li> <li>Better flow control handling</li> <li>Updated to latest inotify version: 0.23-6 (John McCutchan, Todor Penev, Andrei Lahun, Daniel Drake)</li> <li>MacOSX/BSDs portability using kqueue (Joe Marcus Clarke, Fred Leason)</li> </ul> <h3>0.0.26: Mar 15 2005</h3> <ul> <li>Fixed an include problem showing up with gcc4</li> <li>A couple of documentation typo fixes</li> <li>fixed the crash on failed tree assert bug #150471 based on patch from Dean Brettle</li> <li>removed an incompatibility with SGI FAM #149822</li> </ul> <h3>0.0.25: Mar 1 2005</h3> <ul> <li>Fix a configure problem reported by Martin Schlemmer</li> <li>Fix the /media/* and /mnt/* mount blocking problems from 0.0.24</li> <li>Fix the monitoring of directory using poll and not kernel</li> </ul> <h3>0.0.24: Feb 18 2005</h3> <ul> <li> more documentation</li> <li> lot of serious bug fixes including Gnome Desktop refresh bug</li> <li> extending the framework for more debug (configure --enable-debug-api)</li> <li> extending the python bindings for watching the same resource multiple times and adding debug framework support</li> <li> growing the regression tests a lot based on python bindings</li> <li> inotify-0.19 patch from John McCutchan</li> <li> renamed python private module to _gamin to follow Python PEP 8</li> </ul> <h3>0.0.23: Feb 8 2005</h3> <ul> <li> memory corruption fix from Mark on the client side.</li> <li> extending the protocol and API to allow skipping Exists and EndExists events to avoid deadlock on reconnect or when they are not used (all gam_servers should be killed after an update to 0.0.23).</li> </ul> <h3>0.0.22: Jan 31 2005</h3> <ul> <li> Added Python regression test, and a python disconnect() operation.</li> <li> Applied patches from John McCutchan to fix inotify 0.18 backend.</li> <li> 3 bugs fixed.</li> </ul> <h3>0.0.21: Jan 26 2005</h3> <ul> <li> Added Python bindings.</li> <li> Applied patch from Philipp Zabel to switch to inotify 0.18 protocol. This won't work with older inotify kernel versions.</li> <li> Doc fix (Mark McLoughlin).</li> <li> Removal of compilation warnings.</li> </ul> <h3>0.0.20: Jan 6 2005</h3> <ul> <li> Frederic Crozat seems to have found the list corruption bug and provided a patch.</li> <li> Frederic Crozat fixed the poll only mode.</li> </ul> <h3>0.0.19: Dec 3 2004</h3> <ul> <li> still chasing the loop bug, made another pass at checking GList, added own copy with memory poisonning of GList implementation.</li> <li> fixed a compile issue when compiling without debug</li> <li> Another internal bugfix.</li> </ul> <h3>0.0.18: Nov 26 2004</h3> <ul> <li> still chasing the loop bug, checked and cleaned up all GList use</li> <li> patch from markmc to minimize load on busy apps</li> </ul> <h3>0.0.16: Oct 20 2004</h3> <ul> <li> chasing #132354, lot of debugging, checking and testing and a bit of refactoring</li> </ul> <h3>0.0.15: Oct 16 2004</h3> <ul> <li> workaround to detect loops and avoid the nasty effects, see RedHat bug #132354</li> </ul> <h3>0.0.14: Oct 3 2004</h3> <ul> <li> Found and fixed the annoying bug where update were not received should fix bugs ##132429, #133665 and #134413</li> <li> new mechanism to debug on-the-fly by sending SIGUSR2 to client or server</li> <li> Added documentation about internals</li> </ul> <h3>0.0.14: Oct 3 2004</h3> <ul> <li>Found and fixed the annoying bug where update were not received should fix bugs ##132429, #133665 and #134413 in Red Hat bugzilla</li> <li>new mechanism to debug on-the-fly by sending SIGUSR2 to client or server</li> <li>Added documentation about internals</li> </ul> <h3>0.0.13: Oct 1 2004</h3> <ul> <li>applied portability fixes</li> <li>hardened the code while chasing a segfault</li> </ul> <h3>0.0.12: Sep 30 2004</h3> <ul> <li>potential fix for a hard to reproduce looping problem.</li> </ul> <h3>0.0.11: Sep 27 2004</h3> <ul> <li>inotify support compiled in by default</li> <li>fix ABI FAM compatibility problems #133162</li> <li>update to the latest version of inotify </li> </ul> <h3>0.0.10: Sep 21 2004</h3> <ul> <li>fixed API/ABI incompatibility between FAM and gamin about FAMErrno and FamErrlist</li> <li>added support for a per-user configuration file $HOME/.gaminrc</li> <li>applied a portability patch from Michael Banck</li> <li>extended the documentation</li> </ul> <h3>0.0.9: Sep 1 2004</h3> <ul> <li>fix konqueror crash Red Hat bug #130967</li> <li>statically excludes /mnt//* /media//* from kernel monitoring to avoid umount problems</li> </ul> <h3>0.0.8: Aug 26 2004</h3> <ul> <li>inotify backend patch (Martin Schlemmer)</li> <li>documentation</li> <li>fixed 0.0.7 crashes</li> <li>fixed the kernel/poll detection code which was buggy</li> </ul> <h3>0.0.7: Aug 24 2004</h3> <ul> <li>increased the test suite</li> <li>activate poll and kernel monitoring (dnotify) simultaneously</li> <li>fix monitoring of resources initially missing</li> <li>fix load problem due to dnotify on very busy resources</li> </ul> <h3>0.0.6: Aug 19 2004</h3> <ul> <li>fix monitoring of file resources</li> <li>moved gam_server to $libexec since it doesn't need to be started from the command line usually</li> <li>test and fixes on x86_64</li> <li>removal all thread dependancies and conditional code</li> </ul> <h2><a name="Downloads">Downloads</a></h2> <p>You can download gamin from the GNOME project pages, either as <a href="http://www.gnome.org/~veillard/gamin/sources/">sources</a>, and <a href="http://www.gnome.org/~veillard/gamin/RPMS/">binaries</a> or <a href="http://www.gnome.org/~veillard/gamin/SRPMS/">source</a> RPMs.</p> <h2><a name="Python">Python bindings</a></h2> <p>Starting with release 0.0.21, gamin comes with Python bindings. Use "<span style="font-family: monospace;">import gamin</span>" to load the module. It exports the main class "<span style="font-family: monospace;">WatchMonitor</span>" which handle one connection to the gam_server. Once an instance of the class has been created you can use the watch_directory and watch_file methods to register objects to monitors, and provide the callback to be called when events are generated. Like the FAM API, the python binding API is passive, i.e. one need to monitor the file descriptor provided with the <span style="font-family: monospace;">get_fd()</span> method to detect events, and call <span style="font-family: monospace;">handle_one_event()</span> (blocking) or <span style="font-family: monospace;">handle_events()</span> (non-blocking) to process incoming events and get the callbacks appropriately. You can also use the <span style="font-family: monospace;">event_pending()</span> method to detect if <span style="font-family: monospace;">handle_one_event()</span> would block or not.<br> Since a short example is worth a thousand words, here is a small session from the python shell:</p> <pre> >>> import gamin >>> >>> def callback(path, event): ... print "Got callback: %s, %s" % (path, event) ... >>> mon = gamin.WatchMonitor() >>> mon.watch_directory(".", callback) <gamin.WatchObject instance at 0xb7f7b56c> >>> mon.event_pending() 1 >>> mon.handle_one_event() Got callback: /u/veillard/temp, 8 1 >>> mon.handle_events() Got callback: bar1, 8 Got callback: foo1, 8 Got callback: /u/veillard/temp, 9 3 >>> mon.stop_watch(".") >>> del mon </pre> <p>The corresponding standalone code follows:</p> <pre>#!/usr/bin/env python import gamin import time def callback(path, event): print "Got callback: %s, %s" % (path, event) mon = gamin.WatchMonitor() mon.watch_directory(".", callback) time.sleep(1) ret = mon.event_pending() if ret > 0: ret = mon.handle_one_event() ret = mon.handle_events() mon.stop_watch(".") del mon </pre> <p>Note the addition of the sleep timeout, it is needed because due to the round trip between the client and the gam_server, events may not be immediately available after the monitor creation to the client.</p> <h2><a name="Developers">Developers</a> informations</h2> <p>The CVS base is in the <a href="http://www.gnome.org/">GNOME</a> project CVS base at cvs.gnome.org, the module name is <a href="http://cvs.gnome.org/viewcvs/gamin/"><strong>gamin</strong></a>. See the <a href="http://developer.gnome.org/tools/cvs.html">Gnome CVS Tools</a> page for more information on using CVS.</p> <p>We expect bug reports to be entered in <a href="http://bugzilla.gnome.org/buglist.cgi?product=gamin&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&bug_status=RESOLVED&bug_status=VERIFIED&form_name=query">GNOME bugzilla</a> or in <a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&product=Red+Hat+Enterprise+Linux&component=fam&component=gamin&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&Search=Search">Red Hat bugzilla</a>.</p> <h2><a name="Contacts">Contacts</a></h2> <p>The best way to contact the developers is to use the mailing-list <a href="http://mail.gnome.org/mailman/listinfo/gamin-list">gamin-list@gnome.org</a>.</p> <p>Before reporting a bug please double-check:</p> <ul> <li>that you are using the <a href="http://www.gnome.org/~veillard/gamin/sources/">latest version</a></li> <li>that the bug hasn't been reported previously in <a href="http://bugzilla.gnome.org/buglist.cgi?product=gamin&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&bug_status=RESOLVED&bug_status=VERIFIED&form_name=query">GNOME</a> or <a href="https://bugzilla.redhat.com/bugzilla/buglist.cgi?product=Fedora+Core&product=Red+Hat+Enterprise+Linux&component=fam&component=gamin&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED&short_desc_type=allwordssubstr&short_desc=&long_desc_type=allwordssubstr&long_desc=&Search=Search">Red Hat</a> bugzillas.</li> </ul> <p>Then the best way is to log the bug in one of the bugzilla or <a href="http://mail.gnome.org/mailman/listinfo/gamin-list">join the list</a> and post there if you think that some of gamin design or code should be changed. If you can provide a <a href="debug.html">testgam</a> scenario reproducing the problem this would really help getting it debugged and fixed, see examples in tests/scenario/ .</p> <h2><a name="FAQ">FAQ</a></h2> <p>This will be created as user feedback is provided.</p> <h2><a name="Debug">Debugging Gamin</a></h2> <ul> <li><a href="#Debugging">Debugging support in gamin</a></li> <li><a href="#Debugging1">Debugging a running program</a></li> <li><a href="#Debugging2">Debugging and testing client</a></li> </ul> <h3><a name="Debugging">Debugging support in gamin</a>:</h3> <p>Both the client and server side, if compiled with debug support accept an environment variable <strong>GAM_DEBUG</strong> which is set will make them report debugging informations to stdout.</p> <p>Usually for debugging you also want to use a dedicated server process so setting the <strong>GAM_CLIENT_ID</strong> environment allows to ensure this. Usually one also want to keep control over the server lifetime and not have it exit automatically after 30 seconds without connection, there is a command line flag <strong>--notimeout</strong> to <strong>gam_server</strong> for this.</p> <p>A typical example of a debugging session using 2 shells would be:</p> <pre>shell1: export GAM_DEBUG= shell1: gam_server --notimeout test</pre> <p>to run the server in debug mode using the ID "test"</p> <pre>shell2: export GAM_DEBUG= shell2: export GAM_CLIENT_ID=test shell2: gamin_client</pre> <p>to run the client in a verbose session. It is perfectly possible to also run the client under a debugger, for the server it works too except the dnotify kernel interface uses a signal SIG33 which is trapped by gdb. To avoid this use the handle gdb instruction:</p> <pre>(gdb) handle SIG33 nostop Signal Stop Print Pass to program Description SIG33 No Yes Yes Real-time event 33 (gdb)</pre> <p>even better add it to your <strong>$HOME/.gdbinit</strong> .</p> <h3><a name="Debugging1">Debugging a running program</a>:</h3> <p>Both the gam_server and client of the gamin library can get switched dynamically to a debug mode by sending them a signal SIGUSR2. In that case the program or library switches to verbose debugging and outputs the traces to a new file /tmp/gamin_debug_XXXXXX . Sending the signal again to the application or the server should switch off debugging.</p> <h3><a name="Debugging2">Debugging and testing client</a>:</h3> <p>A debugging client program called <strong>testgam</strong> is also available in the tests subdirectory. It allow to use the interface and monitor the flow of event received. Here is an example of a session:</p> <pre>paphio:~/gamin/tests -> export GAMIN_DEBUG_SERVER="../server/gam_server" paphio:~/gamin/tests -> ./testgam - > connect test connected to test ></pre> <p>The environment variable can be used to specify the path to the server to run, then <strong>testgam</strong> is launched in interactive mode (argument <strong>-</strong> ) and the program is asked to connect to the server for session test (the server will be started on-demand by the library if needed).</p> <pre>> mkdir temp mkdir temp > mkfile temp/foo mkfile temp/foo > mondir temp mondir temp 0 > 1: /u/veillard/gamin/tests/temp Exists: NULL 1: foo Exists: NULL 1: /u/veillard/gamin/tests/temp EndExist: NULL > mkfile temp/bar mkfile temp/bar > 1: bar Created: NULL > rmfile temp/foo rmfile temp/foo > 1: foo Deleted: NULL ></pre> <p>In this example a new directory is created with a file in it and then monitored, then the directory content is modified. The <strong>testgam</strong> program also poll and report events coming from the server as they arrive.</p> <h2><a name="Security">Security</a></h2> <p>While gamin still use a server to provide the service (ideally if the kernel had a proper interface a library only implementation should be doable and possibly better), it tries to avoid security hazard associated to contacting an external server process:</p> <ul> <li>the server runs under the same privilege level as the client, by running under the uid, no root or superuser access is involved, this is checked by both side using kernel support for the checking</li> <li>when possible (e.g. on Linux) the socket used to communicate is not mapped at the filesystem level to avoid risks related to opening a real file, if the kernel doesn't allow this a per user directory holding the socket is used and appropriate rights are checked.</li> <li>to limit DoS attacks done by continuously modifying a monitored resource, the daemon will switch back monitoring of very busy resources to polling with generation of events only once per second.</li> </ul> <p>Here is the process used to acquire and create the sockets:</p> <h3>If there is abstract socket support:</h3> <p>Use the filename "\0/tmp/fam-$USER-$GAM_CLIENT_ID". They are not mapped on the filesystem, no attack is possible that way. The client and the server checks on the first '\0' byte received from the socket that the other side is running under the same UID.</p> <h3>If there is no abstract socket support:</h3> <p>On the server side:</p> <pre> start: try to create /tmp/fam-$USER using mkdir('/tmp/fam-$USER', 007) if error: make a stat() on it if doesn't exist: return failure to create if user is not getuid() or mode is not 007 or type is not dir: try to unlink() if error: exit with error. if success: goto start: do the socket()/bind() on /tmp/fam-$USER/fam-$GAM_CLIENT_ID</pre> <p>On the client side:</p> <pre> make a stat on /tmp/fam-$USER if doesn't exist: return failure to create should start the server if user is not getuid() or mode is not 007 or type is not dir: try to unlink() if error: exit with error. if success: return failure should start the server make a stat on /tmp/fam-$USER/fam-$GAM_CLIENT_ID if doesn't exist: return failure to create should start the server if user is not getuid() or type is not socket: try to unlink() if error: exit with error. if success: return failure should start the server do the socket()/connect() on /tmp/fam-$USER/fam-$GAM_CLIENT_ID</pre> <p>The client and the server checks on the first '\0' byte received that the other side is of the same UID.</p> <h2><a name="Internals">Internals</a></h2> <p>gamin uses a client server model, this is in a large measure justified by the inappropriate dnotify kernel API way to signal modification events to an application but also to share kernel signal when multiple application monitors the same resource. It also allow to fine tune and filters event flow in the daemon, potentially minimizing resource consumption in applications.</p> <p><img src="client_server.gif" alt="One server and two client connected"></p> <p>Internally the gam_server maintain various data structures:</p> <ul> <li>A tree of monitored nodes, using both GamNode structure containing specific informations (like the path, the subscriptions list for that node, monitoring data and whether it's a directory), the tree itself is based on a GNode N-ary tree.</li> <li>Per connection data (GamConnData) one per connected socket. The data includes state, connection informations (file descriptor, Glib I/O Channel, pid of the application), and potential unprocessed yet data request from the socket.</li> <li>Listener information, keeps the list of subscriptions for the connected application, this could probably be merged in the connection data.</li> <li>For each path monitored by an application, a specific GamSubscription structure is maintained. The subscriptions are referenced both from the monitored nodes tree and from the listeners.</li> </ul> <p><img src="server_structs.gif" alt="the data structures present in the server"></p> <p></p> <h2><a name="Differences">Differences from FAM</a></h2> <h3>Differences</h3> <p>gamin should be binary and source code compatible with FAM 2.6.8. However there are some differences and at least one significant extension.</p> <p>The differences are in term of implementation:</p> <ul> <li>No system wide server, instead it relies on per user server, if needed started on demand by the fam/gamin library.</li> <li>The functions FAMSuspendMonitor(), FAMResumeMonitor() and FAMMonitorCollection() are not implemented. They all raise problem of accumulating unbounded state on the server side and better handled at the client level if needed.</li> <li>FAMErrno is provided, but the values may not match their FAM counterparts, similary FamErrlist[] error messages are different.</li> <li>No NFS support based on specific RPC and server, instead gamin monitors only the state as reported locally by the kernel, not that locally done changes on NFS or AFS filesystems are reported on Linux which is the main criteria when having user home directories on such filesystems.</li> </ul> <h3>Extension(s)</h3> <p>We tried to limit changes in gamin but a number of features were deemed more important than sticking to the exact same set than FAM:</p> <ul> <li>Support for inotify on Linux if compiled in the kernel, this override most of the deficiencies related to dnotify.</li> <li>A lot of debugging support was added both for client and server see the <a href="debug.html">specific page</a> on the matter.</li> <li>The possibility to block Exist/EndExists callbacks when monitoring directories based on a new API, see below</li> </ul> <p>FAM when monitoring a directory, immediately send a set of events listing the files found in that directory, this ends up with an EndExists events. However when monitoring hierarchy it's usually far more efficient and simple to do the scanning on the client side and ignore those directory listing events from the FAM server (the only drawback is a potential mismatch of the directory content between the FAM server and the client). In such a case, all those events are not only superfluous but they are also dangerous since they can lead to a congested pipe to the client which is just scanning directories and not listening to FAM. To that intent we added in gamin 0.0.23 a new API disabling the Exists/EndExists sequences when watching directories for a given FAMConnection:</p> <pre>int FAMNoExists(FAMConnection *fc)</pre> <p>and with the Python bindings:</p> <pre>WatchMonitor.no_exists()</pre> <p>This feature is also used when the client reconnect to the server after a connection loss or if the server died.</p> <p>Calling it changes the protocol as described below, directory monitoring from that call will only get mutation events and not the initial lists:</p> <p><img src="callbacks.gif" alt="The NoExists behaviour change on callbacks"></p> </body> </html>