Sys::Gamin(3pm)

✨ NAME ✨

ok so Sys::Gamin is a Perl interface to Gamin — which is a File Access Monitor implementation. that's the whole vibe. 💖

(also hi bestie, this is a <pink>3pm</pink> page, i.e. user-contributed Perl documentation, so you know it's the good stuff 🫶)

---

🦋 SYNOPSIS 🦋

ok so first, the classic blocking setup:

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";
}

and then asynchronous mode, for when you're too busy to block 💅:

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

---

🌸 DESCRIPTION 🌸

so basically this module gives you a somewhat higher-level and friendlier interface to the Gamin File Access Monitor API. cute, right? it lets you monitor both local and remote (NFS-mounted) files and directories for common filesystem events. to do that you gotta register "monitors" on specified pathnames and then sit there and wait for events about them. iconic behavior honestly.

now here's a detail that matters: since FAM only deals with absolute pathnames, all paths get canonicalized internally and the monitors are held on those canonical paths. BUT — whenever a path is returned from this module (via which, or monitored with no arguments), you get the originally specified path back, for convenience. thoughtful king 👑

---

👑 MAIN METHODS 👑

new [ appname ]

creates a new FAM connection. you can hand it an application name if you want. 💫

pending

returns true if there's an event waiting. returns immediately — no waiting around, no drama. ✨

next_event

returns the next event in the queue, as an event object. it blocks if necessary until one shows up. it will simply sit there. patiently. 💀

monitor path [ unique [ type [ depth mask ] ] ]

monitors the specified file or directory. heads up bestie: expect a slew of events immediately (exist and end_exist) which may not interest you at all. it's giving "notifications you didn't ask for". 🙈

• unique — if specified and true, it'll throw a warning if the monitored path isn't unique among the ones you're already monitoring. helpful for debugging, but normally this is harmless. no biggie.
• type — may be file, dir or coll. it defaults to file or dir depending on what actually exists in the filesystem. if you specify coll (collection), you pass additional depth and mask arguments — if you ever figure out what that does (SGI does not say). 😭

cancel path

stops monitoring this path. bye bestie 👋

monitored [ path ]

lists all currently monitored paths, or checks whether a specific one is being monitored. does not check if a monitor is suspended, so don't get it twisted. 💅

suspended path

true if the specified monitor is suspended. that's it, that's the method.

suspend [ path ]

suspends monitoring of a path — or all paths if you don't specify one.

resume [ path ]

resumes monitoring of a path — or all paths if you don't specify one. we're so back 🫶

which event

gives you the pathname for the monitor generating this event. often this will be the same as $event->filename, but it differs in some cases — for example in create events, where filename gives you the basename of the new file, and you must call the which method to figure out the directory of creation, if more than one directory is being monitored. so like, don't skip it. iykyk. 🌈

---

🎀 EVENT METHODS 🎀

hostname

host of the event. does not seem to work, actually. 💀

filename

path of the event, according to FAM.

type

type of the event. it's one of these strings, periodt:

• change
• delete
• start_exec
• stop_exec
• create
• move
• ack
• exist
• end_exist

---

💀 BUGS 💀

most of these can be observed with monitor. not me exposing the module's whole business 🙈

Hostnames

Do not seem to be supplied at all. at all. zero. nada. 😭

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. she's on her own schedule bestie.

Execute Events

are not sent, as far as the author can determine. so like. don't count on them. 💀

---

⭐ SEE ALSO ⭐

for the raw SGI interface (which is, and i quote, rather poorly documented), go check out fam(3x).

---

🫶 AUTHORS 🫶

• J. Glick jglick@sig.bsh.com — original SGI::FAM code, which this module is based on. the blueprint, the blueprint. 👑
• Carlos Garnacho carlosg@gnome.org — slay.

---

🌈 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. legal queen. 💅

---

ok that's the whole page bestie!! perl v5.34.0, dated 2022-02-06 — and that's the Sys::Gamin(3pm) footer, mwah 💖 go monitor something, love u, bye 🎀✨