NAME

       Sys::Gamin - Perl interface to Gamin (File Access Monitor implementation)

SYNOPSIS

         use Sys::Gamin;
         my $fm=new Sys::Gamin;
         $fm->monitor('/foo');
         $fm->monitor('/foo/bar.txt');
         while (1) {
           my $event=$fm->next_event;  # Blocks
           print "Pathname: ", $event->filename,
             " Event: ", $event->type, "\n";
         }

       Asynchronous mode:

         while ($fm->pending) {
           my $event=$fm->next_event; # Immediate
           ...
         }
         # Do something else

DESCRIPTION

       Provides a somewhat higher-level and friendlier interface to the Gamin File Access Monitor
       API. This allows one to monitor both local and remote (NFS-mounted) files and directories
       for common filesystem events. To do so, you must register "monitors" on specified
       pathnames and wait for events to arrive pertaining to them.

       Since FAM only deals with absolute pathnames, all paths are canonicalized internally and
       monitors are held on canonical paths. Whenever a path is returned from this module,
       howvever, via which or monitored with no arguments, the originally specified path is given
       for convenience.

MAIN METHODS

   new [ appname ]
       Create a new FAM connection. An application name may be given.

   pending
       True if there is an event waiting. Returns immediately.

   next_event
       Returns next event in queue, as an event object. Blocks if necessary until one is
       available.

   monitor path [ unique [ type [ depth mask ] ] ]
       Monitor the specified file or directory. Expect a slew of events immediately (exist and
       end_exist) which may not interest you.

       unique, if specified and true, will produce a warning if the monitored path is not unique
       among those already being monitored. This can be helpful for debugging, but normally this
       is harmless.

       type may be file, dir or coll; it defaults to file or dir according to an existing
       filesystem entry. If you specify coll (collection), pass additional depth and mask
       arguments, if you ever figure out what that does (SGI does not say).

   cancel path
       Stop monitoring this path.

   monitored [ path ]
       List all currently monitored paths, or check if a specific one is being monitored. Does
       not check if a monitor is suspended.

   suspended path
       True if the specified monitor is suspended.

   suspend [ path ]
       Suspend monitoring of a path, or all paths if unspecified.

   resume [ path ]
       Resume monitoring of a path, or all paths if unspecified.

   which event
       Gives the pathname for the monitor generating this event. Often this will be the same as
       "$event->filename", but will differ in some cases, e.g. in create events where filename
       will yield the basename of the new file while the which method must be invoked to
       determine the directory of creation, if more than one is being monitored.

EVENT METHODS

   hostname
       Host of event. Does not seem to work, actually.

   filename
       Path of event, according to FAM.

   type
       Type of event; one of the following strings: change, delete, start_exec, stop_exec,
       create, move, ack, exist, end_exist.

BUGS

       Most of these can be observed with monitor.

       Hostnames
           Do not seem to be supplied at all.

       Timing
           Is somewhat erratic. For example, creating a file that had been monitored and deleted
           will signal a create event on it, after about a second pause.

       Execute Events
           Are not sent, as far as the author can determine.

SEE ALSO

       For the raw SGI interface (rather poorly documented), see fam(3x).

AUTHORS

       J. Glick jglick@sig.bsh.com: Original SGI::FAM code, in which this module is based.

       Carlos Garnacho carlosg@gnome.org.

REVISION

       lib/SGI/FAM.pm last modified Thu, 04 Mar 2005 22:05:42 -0100 release 0.1. Original
       SGI::FAM module: Copyright (c) 1997 Strategic Interactive Group. All rights reserved. This
       program is free software; you can redistribute it and/or modify it under the same terms as
       Perl itself.