NAME

Linux::Perl::inotify

SYNOPSIS

    my $inf = Linux::Perl::inotify->new();

    my $wd = $inf->add( path => $path, events => ['CREATE', 'ONLYDIR'] );

    my @events = $inf->read();

    $inf->remove($wd);

DESCRIPTION

This is an interface to Linux’s “inotify” feature.

METHODS

CLASS->EVENT_NUMBER()

A hash reference of event names to numeric values. The member keys are:

• ACCESS, MODIFY, ATTRIB

• OPEN, CLOSE, CLOSE_WRITE, CLOSE_NOWRITE

• MOVE, MOVED_FROM, MOVED_TO, MOVE_SELF

• CREATE, DELETE, DELETE_SELF

• UNMOUNT, Q_OVERFLOW, IGNORED, ISDIR

See man 7 inotify for details of what these mean. This is useful to parse the return from read() (below).

CLASS->new( %OPTS )

Instantiates a new inotify instance.

%OPTS is:

• flags - Optional, an array reference of either or both of NONBLOCK and/or CLOEXEC.

$wd = OBJ->add( %OPTS )

Adds to an inotify instance and returns a watch descriptor. See man 2 inotify_add_watch for more information.

%OPTS is:

• path - The filesystem path to monitor.

• events - An array reference of events to monitor for. Recognized events are:

  • ACCESS, MODIFY, ATTRIB

  • OPEN, CLOSE, CLOSE_WRITE, CLOSE_NOWRITE

  • MOVE, MOVED_FROM, MOVED_TO, MOVE_SELF

  • CREATE, DELETE, DELETE_SELF

  • UNMOUNT, Q_OVERFLOW, IGNORED, ISDIR

  • ALL_EVENTS

  • ONLYDIR, DONT_FOLLOW, EXCL_UNLINK, MASK_CREATE, MASK_ADD, ONESHOT

  Note that your kernel may not recognize all of these.

@events = OBJ->read()

Reads events from the inotify instance. Each event is returned as a hash reference with members wd, mask, cookie, and name. See man 7 inotify for details about what these mean. (Use the members of EVENT_NUMBER() above to parse mask.)

Note that if the underlying inotify object is not set NONBLOCK then this call will block until there is an inotify event to read.

In scalar context this returns the number of events that happened.

An empty return here indicates a read failure; $! will contain the usual information about the failure.

OBJ->remove( $WD )

Analogous to man 2 inotify_rm_watch.