Function naughtyfy::low_api::fanotify_init

source · 
pub fn fanotify_init(flags: u32, event_f_flags: u32) -> Result<i32, Error>
Expand description

Initializes a new fanotify group and returns a file descriptor for the event queue associated with the group.

The file descriptor is used in calls to fanotify_mark(2) to specify the files, directories, mounts or filesystems for which fanotify events shall be created.
These events are received by reading from the file descriptor.
Some events are only informative, indicating that a file has been accessed. Other events can be used to determine whether another application is permitted to access a file or directory. Permission to access filesystem objects is granted by writing to the file descriptor. Multiple programs may be using the fanotify interface at the same time to monitor the same files.
In the current implementation, the number of fanotify groups per user is limited to 128. This limit cannot be overridden. Calling fanotify_init() requires the CAP_SYS_ADMIN capability.
This constraint might be relaxed in future versions of the API.
Therefore, certain additional capability checks have been implemented as indicated below.
The flags argument contains a multi-bit field defining the notification class of the listening application and further single bit fields specifying the behavior of the file descriptor.
If multiple listeners for permission events exist, the notification class is used to establish the sequence in which the listeners receive the events.

Only one of the following notification classes may be specified in flags:

  • FAN_CLASS_PRE_CONTENT
  • FAN_CLASS_CONTENT
  • FAN_CLASS_NOTIF

Listeners with different notification classes will receive events in the order FAN_CLASS_PRE_CONTENT, FAN_CLASS_CONTENT, FAN_CLASS_NOTIF. The order of notification for listeners in the same notification class is undefined.
The following bits can additionally be set in flags:

  • FAN_CLOEXEC
  • FAN_NONBLOCK
  • FAN_UNLIMITED_QUEUE
  • FAN_UNLIMITED_MARKS
  • FAN_REPORT_TID (since Linux 4.20)
  • FAN_REPORT_FID (since Linux 5.1)

The event_f_flags argument defines the file status flags that will be set on the open file descriptions that are created for fanotify events.
For details of these flags, see the description of the flags values in open(2). event_f_flags includes a multi-bit field for the access mode.
This field can take the following values:

  • O_RDONLY
  • O_WRONLY
  • O_RDWR

Additional bits can be set in event_f_flags. The most useful values are:

  • O_LARGEFILE
  • O_CLOEXEC (since Linux 3.18)

The following are also allowable: O_APPEND, O_DSYNC, O_NOATIME,O_NONBLOCK, and O_SYNC. Specifying any other flag in event_f_flags yields the error EINVAL.