.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Sys::Gamin 3pm"
.TH Sys::Gamin 3pm "2014-02-22" "perl v5.24.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sys::Gamin \- Perl interface to Gamin (File Access Monitor implementation)
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 9
\&  use Sys::Gamin;
\&  my $fm=new Sys::Gamin;
\&  $fm\->monitor(\*(Aq/foo\*(Aq);
\&  $fm\->monitor(\*(Aq/foo/bar.txt\*(Aq);
\&  while (1) {
\&    my $event=$fm\->next_event;  # Blocks
\&    print "Pathname: ", $event\->filename,
\&      " Event: ", $event\->type, "\en";
\&  }
.Ve
.PP
Asynchronous mode:
.PP
.Vb 5
\&  while ($fm\->pending) {
\&    my $event=$fm\->next_event; # Immediate
\&    ...
\&  }
\&  # Do something else
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Provides a somewhat higher-level and friendlier interface to the Gamin File Access
Monitor \s-1API.\s0 This allows one to monitor both local and remote (NFS-mounted) files and
directories for common filesystem events. To do so, you must register \*(L"monitors\*(R" on
specified pathnames and wait for events to arrive pertaining to them.
.PP
Since \s-1FAM\s0 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 \fBwhich\fR or \fBmonitored\fR with no arguments, the originally specified path
is given for convenience.
.SH "MAIN METHODS"
.IX Header "MAIN METHODS"
.SS "\fBnew\fP [ \fIappname\fP ]"
.IX Subsection "new [ appname ]"
Create a new \s-1FAM\s0 connection. An application name may be given.
.SS "\fBpending\fP"
.IX Subsection "pending"
True if there is an event waiting. Returns immediately.
.SS "\fBnext_event\fP"
.IX Subsection "next_event"
Returns next event in queue, as an event object. Blocks if necessary until one is
available.
.SS "\fBmonitor\fP \fIpath\fP [ \fIunique\fP [ \fItype\fP [ \fIdepth\fP \fImask\fP ] ] ]"
.IX Subsection "monitor path [ unique [ type [ depth mask ] ] ]"
Monitor the specified file or directory. Expect a slew of events immediately (\fBexist\fR
and \fBend_exist\fR) which may not interest you.
.PP
\&\fIunique\fR, 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.
.PP
\&\fItype\fR may be \fBfile\fR, \fBdir\fR or \fBcoll\fR; it defaults to \fBfile\fR or \fBdir\fR according
to an \fIexisting\fR filesystem entry. If you specify \fBcoll\fR (collection), pass
additional depth and mask arguments, if you ever figure out what that does (\s-1SGI\s0 does
not say).
.SS "\fBcancel\fP \fIpath\fP"
.IX Subsection "cancel path"
Stop monitoring this path.
.SS "\fBmonitored\fP [ \fIpath\fP ]"
.IX Subsection "monitored [ path ]"
List all currently monitored paths, or check if a specific one is being monitored. Does
not check if a monitor is suspended.
.SS "\fBsuspended\fP \fIpath\fP"
.IX Subsection "suspended path"
True if the specified monitor is suspended.
.SS "\fBsuspend\fP [ \fIpath\fP ]"
.IX Subsection "suspend [ path ]"
Suspend monitoring of a path, or all paths if unspecified.
.SS "\fBresume\fP [ \fIpath\fP ]"
.IX Subsection "resume [ path ]"
Resume monitoring of a path, or all paths if unspecified.
.SS "\fBwhich\fP \fIevent\fP"
.IX Subsection "which event"
Gives the pathname for the monitor generating this event. Often this will be the same
as \f(CW\*(C`$event\->filename\*(C'\fR, but will differ in some cases, e.g. in \fBcreate\fR events
where \fBfilename\fR will yield the basename of the new file while the \fBwhich\fR method
must be invoked to determine the directory of creation, if more than one is being
monitored.
.SH "EVENT METHODS"
.IX Header "EVENT METHODS"
.SS "\fBhostname\fP"
.IX Subsection "hostname"
Host of event. Does not seem to work, actually.
.SS "\fBfilename\fP"
.IX Subsection "filename"
Path of event, according to \s-1FAM.\s0
.SS "\fBtype\fP"
.IX Subsection "type"
Type of event; one of the following strings: \fBchange\fR, \fBdelete\fR, \fBstart_exec\fR,
\&\fBstop_exec\fR, \fBcreate\fR, \fBmove\fR, \fBack\fR, \fBexist\fR, \fBend_exist\fR.
.SH "BUGS"
.IX Header "BUGS"
Most of these can be observed with \fImonitor\fR.
.IP "Hostnames" 4
.IX Item "Hostnames"
Do not seem to be supplied at all.
.IP "Timing" 4
.IX Item "Timing"
Is somewhat erratic. For example, creating a file that had been monitored and deleted
will signal a \fBcreate\fR event on it, after about a second pause.
.IP "Execute Events" 4
.IX Item "Execute Events"
Are not sent, as far as the author can determine.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
For the raw \s-1SGI\s0 interface (rather poorly documented), see \fIfam\fR\|(3x).
.SH "AUTHORS"
.IX Header "AUTHORS"
J. Glick \fBjglick@sig.bsh.com\fR: Original \s-1SGI::FAM\s0 code, in which this module is based.
.PP
Carlos Garnacho \fBcarlosg@gnome.org\fR.
.SH "REVISION"
.IX Header "REVISION"

\&\fIlib/SGI/FAM.pm\fR last modified Thu, 04 Mar 2005 22:05:42 \-0100 release 0.1. Original \s-1SGI::FAM\s0 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.
.IX Xref "$Format: ""\\f(IS$Source$\\f(IE last modified $Date$ release $ProjectRelease$. $Copyright$""$"