(See
.BR inotify (7)
for details of an API that did notify those events pre Linux 5.1.)
-.PP
+.P
Additional capabilities compared to the
.BR inotify (7)
API include the ability to monitor all of the objects
in a mounted filesystem,
the ability to make access permission decisions, and the
possibility to read or modify files before access by other applications.
-.PP
+.P
The following system calls are used with this API:
.BR fanotify_init (2),
.BR fanotify_mark (2),
.BR fanotify_init (2)
system call creates and initializes an fanotify notification group
and returns a file descriptor referring to it.
-.PP
+.P
An fanotify notification group is a kernel-internal object that holds
a list of files, directories, filesystems, and mounts for which
events shall be created.
-.PP
+.P
For each entry in an fanotify notification group, two bit masks exist: the
.I mark
mask and the
Having these two types of masks permits a filesystem, mount, or
directory to be marked for receiving events, while at the same time
ignoring events for specific objects under a mount or directory.
-.PP
+.P
The
.BR fanotify_mark (2)
system call adds a file, directory, filesystem, or mount to a
notification group and specifies which events
shall be reported (or ignored), or removes or modifies such an entry.
-.PP
+.P
A possible usage of the ignore mask is for a file cache.
Events of interest for a file cache are modification of a file and closing
of the same.
Hence, the modify event can be added to the ignore mask.
Upon receiving the close event, the modify event can be removed from the
ignore mask and the file cache entry can be updated.
-.PP
+.P
The entries in the fanotify notification groups refer to files and
directories via their inode number and to mounts via their mount ID.
If files or directories are renamed or moved within the same mount,
from the fanotify file descriptor
returned by
.BR fanotify_init (2).
-.PP
+.P
Two types of events are generated:
.I notification
events and
whether permission for a file access shall be granted.
For these events, the recipient must write a response which decides whether
access is granted or not.
-.PP
+.P
An event is removed from the event queue of the fanotify group
when it has been read.
Permission events that have been read are kept in an internal list of the
until either a file event occurs or the call is interrupted by a signal
(see
.BR signal (7)).
-.PP
+.P
After a successful
.BR read (2),
the read buffer contains one or more of the following structures:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_metadata {
};
.EE
.in
-.PP
+.P
Information records are
supplemental pieces of information that
may be provided alongside the generic
field of this structure in order to
determine the type of information record that
had been received for a given event.
-.PP
+.P
In cases where an fanotify group
identifies filesystem objects by file handles,
event listeners should also expect to
information record objects alongside the generic
.I fanotify_event_metadata
structure within the read buffer:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_fid {
};
.EE
.in
-.PP
+.P
In cases where an fanotify group is initialized with
.BR FAN_REPORT_PIDFD ,
event listeners should expect to receive the below
information record object alongside the generic
.I fanotify_event_metadata
structure within the read buffer:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_pidfd {
};
.EE
.in
-.PP
+.P
In case of a
.B FAN_FS_ERROR
event,
.I fanotify_event_metadata
structure within the read buffer.
This structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_error {
};
.EE
.in
-.PP
+.P
All information records contain a nested structure of type
.IR fanotify_event_info_header .
This structure holds meta-information about the information record
.I fanotify_event_metadata
structure.
This structure is defined as follows:
-.PP
+.P
.in +4n
.EX
struct fanotify_event_info_header {
};
.EE
.in
-.PP
+.P
For performance reasons, it is recommended to use a large
buffer size (for example, 4096 bytes),
so that multiple events can be retrieved by a single
.BR read (2).
-.PP
+.P
The return value of
.BR read (2)
is the number of bytes placed in the buffer,
or \-1 in case of an error (but see BUGS).
-.PP
+.P
The fields of the
.I fanotify_event_metadata
structure are as follows:
.BR fanotify_init (2),
this is the TID of the thread that caused the event.
Otherwise, this the PID of the process that caused the event.
-.PP
+.P
A program listening to fanotify events can compare this PID
to the PID returned by
.BR getpid (2),
to determine whether the event is caused by the listener itself,
or is due to a file access by another process.
-.PP
+.P
The bit mask in
.I mask
indicates which events have occurred for a single filesystem object.
consecutive events for the same filesystem object and originating from the
same process may be merged into a single event, with the exception that two
permission events are never merged into one queue entry.
-.PP
+.P
The bits that may appear in
.I mask
are as follows:
See NOTES in
.BR fanotify_mark (2)
for additional details.
-.PP
+.P
To check for any close event, the following bit mask may be used:
.TP
.B FAN_CLOSE
FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
.EE
.in
-.PP
+.P
To check for any move event, the following bit mask may be used:
.TP
.B FAN_MOVE
FAN_MOVED_FROM | FAN_MOVED_TO
.EE
.in
-.PP
+.P
The following bits may appear in
.I mask
only in conjunction with other event type bits:
.B FAN_ONDIR
flag is reported in an event mask only if the fanotify group identifies
filesystem objects by file handles.
-.PP
+.P
Information records that are supplied alongside the generic
.I fanotify_event_metadata
structure will always contain a nested structure of type
.RI ( event_len
\-
.IR metadata_len ).
-.PP
+.P
The fields of the
.I fanotify_event_info_fid
structure are as follows:
and the file handle is followed by a null terminated string that identifies the
name of a directory entry in that directory, or '.' to identify the directory
object itself.
-.PP
+.P
The fields of the
.I fanotify_event_info_pidfd
structure are as follows:
and the pidfd is no longer required,
the pidfd should be closed via
.BR close (2).
-.PP
+.P
The fields of the
.I fanotify_event_info_error
structure are as follows:
.I error_count
This is a counter of the number of errors suppressed
since the last error was read.
-.PP
+.P
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
.I meta\->event_len
from
.IR len ).
-.PP
+.P
In addition, there is:
.TP
.B FAN_EVENT_METADATA_LEN
.BR write (2)
a structure of the following form to the
fanotify file descriptor:
-.PP
+.P
.in +4n
.EX
struct fanotify_response {
};
.EE
.in
-.PP
+.P
The fields of this structure are as follows:
.TP
.I fd
to allow the file operation or
.B FAN_DENY
to deny the file operation.
-.PP
+.P
If access is denied, the requesting application call will receive an
.B EPERM
error.
.B FAN_FS_ERROR
event record,
but details about the errors are lost.
-.PP
+.P
Errors reported by
.B FAN_FS_ERROR
are generic
.I errno
values,
but not all kinds of error types are reported by all filesystems.
-.PP
+.P
Errors not directly related to a file (i.e. super block corruption)
are reported with an invalid
.IR handle .
See
.BR proc (5)
for details.
-.PP
+.P
Since Linux 5.13,
.\" commit 5b8fea65d197f408bb00b251c70d842826d6b70b
the following interfaces can be used to control the amount of
argument when calling
.BR fanotify_init (2)
and an event occurred for a monitored file that is currently being executed.
-.PP
+.P
In addition to the usual errors for
.BR write (2),
the following errors can occur when writing to the fanotify file descriptor:
filesystem API.
As a result,
it does not catch remote events that occur on network filesystems.
-.PP
+.P
The fanotify API does not report file accesses and modifications that
may occur because of
.BR mmap (2),
.BR msync (2),
and
.BR munmap (2).
-.PP
+.P
Events for directories are created only if the directory itself is opened,
read, and closed.
Adding, removing, or changing children of a marked directory does not create
events for the monitored directory itself.
-.PP
+.P
Fanotify monitoring of directories is not recursive:
to monitor subdirectories under a directory,
additional marks must be created.
in a race-free manner.
Monitoring filesystems offers the capability to monitor changes made from
any mount of a filesystem instance in a race-free manner.
-.PP
+.P
The event queue can overflow.
In this case, events are lost.
.SH BUGS
generate
.B FAN_MODIFY
events.
-.PP
+.P
As of Linux 3.17,
the following bugs exist:
.IP \[bu] 3
When a permission event occurs, a
.B FAN_ALLOW
response is given.
-.PP
+.P
The following shell session shows an example of
running this program.
This session involved editing the file
.B FAN_CLOSE_WRITE
event occurred.
Execution of the program ends when the user presses the ENTER key.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_example /home\fP
a file or a directory\[em]was created.
Once all events have been read from the buffer and processed accordingly,
the program simply terminates.
-.PP
+.P
The following shell sessions show two different invocations of
this program, with different actions performed on a watched object.
-.PP
+.P
The first session shows a mark being placed on
.IR /home/user .
This is followed by the creation of a regular file,
directory object and with the created file name.
Program execution ends once all events captured within the buffer have
been processed.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_fid /home/user\fP
$ \fBtouch /home/user/testfile.txt\fP # In another terminal
.EE
.in
-.PP
+.P
The second session shows a mark being placed on
.IR /home/user .
This is followed by the creation of a directory,
event being generated and is reported with the
.B FAN_ONDIR
flag set and with the created directory name.
-.PP
+.P
.in +4n
.EX
# \fB./fanotify_fid /home/user\fP
projects / thirdparty / man-pages.git / blobdiff