fanotify (fanotify v0.1.1)
View SourceA low-level Erlang interface to the Linux fanotify
API.
% Create a notification group.
Group = fanotify:group().
% Observe create and delete events on files inside /tmp/dir1
% and keep the file handle for later use.
nil = fanotify:mark(Group, "/tmp/dir1", [add, onlydir], [create, delete, ondir, event_on_child]).
Dir1Handle = fanotify:file_handle("/tmp/dir1").
% Also observe create and delete events on files inside /tmp/dir2.
nil = fanotify:mark(Group, "/tmp/dir2", [add, onlydir], [create, delete, ondir, event_on_child]).
Dir2Handle = fanotify:file_handle("/tmp/dir2").
% Receive filesystem events.
[{event, EventType, [{dfid_name, Handle, File}]}] = fanotify:read(Group).
case Handle of
Dir1Handle ->
io:format("Received ~w event on /tmp/dir1/~s~n", [EventType, File]);
Dir2Handle ->
io:format("Received ~w event on /tmp/dir2/~s~n", [EventType, File])
end.
% Close the notification group when done.
nil = fanotify:close(Group).
https://man7.org/linux/man-pages/man7/fanotify.7.html
This library focuses on receiving notifications for filesystem objects and does not support intercepting events.
Summary
Types
Action to perform on the notification group.
Notification event.
Type of events that should be affected by the specified action.
Filesystem object handle.
A fanotify group.
Additional event information.
Functions
Close the notification group, stopping the monitoring of events.
Get the file handle for the filesystem object at the given path.
Add, remove, or modify a fanotify mark on a filesystem object.
Create a fanotify group.
Read the queued notification events on the notification group.
Types
-type action() :: add | remove | dont_follow | onlydir | ignored_mask | evictable | ignore.
Action to perform on the notification group.
-type event() :: {event, [event_type()], [info()]}.
Notification event.
-type event_type() ::
access | modify | attrib | close_write | close_nowrite | open | moved_from | moved_to |
create | delete | delete_self | move_self | open_exec | fs_error | open_perm | access_perm |
open_exec_perm | event_on_child | rename | ondir.
Type of events that should be affected by the specified action.
-opaque file_handle()
Filesystem object handle.
Identifies the filesystem object that received the notification.
-opaque group()
A fanotify group.
Internally, this is represented as a file descriptor for the event queue associated with the group.
-type info() :: {dfid_name, file_handle(), binary()} | {new_dfid_name, file_handle(), binary()} | {old_dfid_name, file_handle(), binary()} | {unknown, non_neg_integer(), binary()}.
Additional event information.
Functions
Close the notification group, stopping the monitoring of events.
-spec file_handle(string() | unicode:unicode_binary()) -> file_handle() | {error, integer() | nil}.
Get the file handle for the filesystem object at the given path.
A filesystem handle remains stable across calls, so you can use this to identify which filesystem object received a notification when monitoring multiple objects.
-spec mark(group(), string() | unicode:unicode_binary(), [action()], [event_type()]) -> nil | {error, integer()}.
Add, remove, or modify a fanotify mark on a filesystem object.
The caller must have read permissions on the filesystem object that is to be marked.
Create a fanotify group.
Currently the notification class supported is FAN_CLASS_NOTIF | FAN_REPORT_DFID_NAME
, as the others require the CAP_SYS_ADMIN
capability.
Read the queued notification events on the notification group.
Returns a list of queued event()
s containing {event,[event_type()],[info()]}
.
info()
is a tuple containing {Type, FileHandle, SubPath}
, where Type
is one of dfid_name
, new_dfid_name
, or old_dfid_name
, FileHandle
is the file handle of the monitored filesystem object, and SubPath
is the subpath of the file that changes (when the monitored object is a directory and [ondir, event_on_child]
were specified in the mark/4
call), or "."
when the watched object itself changed.
Generally an event()
only contains one info()
with type dfid_name
, except for the rename
event which contains an old_dfid_name
and a new_dfid_name
, respectively representing the old and the new name of the object that changed.