fanotify (fanotify v0.1.1)

View Source

A 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

action/0

-type action() :: add | remove | dont_follow | onlydir | ignored_mask | evictable | ignore.

Action to perform on the notification group.

event/0

-type event() :: {event, [event_type()], [info()]}.

Notification event.

event_type/0

-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.

file_handle/0

-opaque file_handle()

Filesystem object handle.

Identifies the filesystem object that received the notification.

group/0

-opaque group()

A fanotify group.

Internally, this is represented as a file descriptor for the event queue associated with the group.

info/0

-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(_)

-spec close(group()) -> nil | {error, integer()}.

Close the notification group, stopping the monitoring of events.

file_handle(Path)

-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.

mark(_, Path, Action, EventTypes)

-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.

new()

-spec new() -> group() | {error, integer()}.

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(_)

-spec read(group()) -> [event()] | {error, integer()}.

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.