LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

fanotify_init.2, fanotify_mark.2, fanotify.7: srcfix: rewrap long source lines 

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2014-05-05 11:45:37 +02:00
parent 77bba7b589
commit 1b24e2ee0e
3 changed files with 68 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
man2/fanotify_init.2
View File

@ -40,8 +40,8 @@ queue associated with the group.
.PP
The file descriptor is used in calls to
.BR fanotify_mark (2)
to specify the files, directories, and mounts for which fanotify events shall
be created.
to specify the files, directories, and mounts 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
@ -68,11 +68,12 @@ indicated below.
The
.I 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.
listening application and further single bit fields specifying the behavior
of the file descriptor.
.PP
If multiple listeners for permission events exist, the notification class is
used to establish the sequence in which the listeners receive the events.
If multiple listeners for permission events exist,
the notification class is used to establish the sequence
in which the listeners receive the events.
.PP
Only one of the following notification classes may be specified in
.IR flags :
@ -82,14 +83,14 @@ This value allows the receipt of events notifying that a file has been
accessed and events for permission decisions if a file may be accessed.
It is intended for event listeners that need to access files before they
contain their final data.
This notification class might be used by hierarchical storage managers, for
example.
This notification class might be used by hierarchical storage managers,
for example.
.TP
.B FAN_CLASS_CONTENT
This value allows the receipt of events notifying that a file has been
accessed and events for permission decisions if a file may be accessed.
It is intended for event listeners that need to access files when they already
contain their final content.
It is intended for event listeners that need to access files when they
already contain their final content.
This notification class might be used by malware detection programs, for
example.
.TP
@ -143,8 +144,8 @@ capability.
.PP
The argument
.I event_f_flags
defines the file flags with which file descriptors for fanotify events shall
be created.
defines the file flags with which file descriptors for fanotify events
shall be created.
For explanations of possible values, see the argument
.I flags
of the
@ -168,8 +169,8 @@ This flag enables the close-on-exec flag for the file descriptor.
This flag enables support for files exceeding 2 GB.
Failing to set this flag will result in an
.B EOVERFLOW
error when trying to open a large file which is monitored by an fanotify group
on a 32-bit system.
error when trying to open a large file which is monitored by
an fanotify group on a 32-bit system.
.SH RETURN VALUE
On success,
.BR fanotify_init ()

15
man2/fanotify_mark.2
View File

@ -39,8 +39,8 @@ For an overview of the fanotify API, see
.PP
.BR fanotify_mark (2)
adds, removes, or modifies an fanotify mark on a filesystem object.
The caller must have read permission on the filesystem object that is to be
marked.
The caller must have read permission on the filesystem object that
is to be marked.
.PP
The
.I fanotify_fd
@ -84,8 +84,8 @@ can be used in conjunction with
.I mask
is ignored.
.PP
If none of the values above is specified, or more than one is specified, the
call fails with the error
If none of the values above is specified, or more than one is specified,
the call fails with the error
.BR EINVAL .
.PP
In addition,
@ -126,7 +126,8 @@ shall be added to or removed from the ignore mask.
.TP
.B FAN_MARK_IGNORED_SURV_MODIFY
The ignore mask shall survive modify events.
If this flag is not set, the ignore mask is cleared when a modify event occurs
If this flag is not set,
the ignore mask is cleared when a modify event occurs
for the ignored file or directory.
.PP
.I mask
@ -268,8 +269,8 @@ The filesystem object indicated by
and
.IR pathname
does not exist.
This error also occurs when trying to remove a mark from an object which is not
marked.
This error also occurs when trying to remove a mark from an object
which is not marked.
.TP
.B ENOMEM
The necessary memory could not be allocated.

83
man7/fanotify.7
View File

@ -25,7 +25,8 @@
.SH NAME
fanotify \- monitoring filesystem events
.SH DESCRIPTION
The fanotify API provides notification and interception of filesystem events.
The fanotify API provides notification and interception of
filesystem events.
Use cases include virus scanning and hierarchical storage management.
Currently, only a limited set of events is supported.
In particular, there is no support for create, delete, and move events.
@ -77,19 +78,20 @@ Events of interest for a file cache are modification of a file and closing
of the same.
Hence, the cached directory or mount point is to be marked to receive these
events.
After receiving the first event informing that a file has been modified, the
corresponding cache entry will be invalidated.
No further modification events for this file are of interest until the file is
closed.
After receiving the first event informing that a file has been modified,
the corresponding cache entry will be invalidated.
No further modification events for this file are of interest until the file
is closed.
Hence, the modify event can be added to the ignore mask.
Upon receiving the closed event, the modify event can be removed from the
ignore mask and the file cache entry can be updated.
.PP
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, the respective entries survive.
If files or directories are deleted or mounts are unmounted, the corresponding
entries are deleted.
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,
the respective entries survive.
If files or directories are deleted or mounts are unmounted,
the corresponding entries are deleted.
.SS The event queue
As events occur on the filesystem objects monitored by a notification group,
the fanotify system generates events that are collected in a queue.
@ -104,10 +106,10 @@ Two types of events are generated:
notification events and permission events.
Notification events are merely informative
and require no action to be taken by
the receiving application except for closing the file descriptor passed in the
event.
Permission events are requests to the receiving application to decide whether
permission for a file access shall be granted.
the receiving application except for closing the file descriptor passed
in the event.
Permission events are requests to the receiving application to decide
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.
@ -152,13 +154,14 @@ struct fanotify_event_metadata {
The fields of this structure as follows:
.TP
.I event_len
This is the length of the data for the current event and the offset to the next
event in the buffer.
This is the length of the data for the current event and the offset
to the next event in the buffer.
In the current implementation, the value of
.I event_len
is always
.BR FAN_EVENT_METADATA_LEN .
In principle, the API design would allow to return variable-length structures.
In principle,
the API design would allow to return variable-length structures.
Therefore, and for performance reasons, it is recommended to use a larger
buffer size when reading, for example 4096 bytes.
.TP
@ -176,8 +179,8 @@ This field is not used.
.TP
.I metadata_len
This is the length of the structure.
The field was introduced to facilitate the implementation of optional headers
per event type.
The field was introduced to facilitate the implementation of
optional headers per event type.
No such optional headers exist in the current implementation.
.TP
.I mask
@ -187,8 +190,8 @@ This is a bit mask describing the event.
This is an open file descriptor for the object being accessed, or
.B FAN_NOFD
if a queue overflow occurred.
The file descriptor can be used to access the contents of the monitored file or
directory.
The file descriptor can be used to access the contents
of the monitored file or directory.
The
.B FMODE_NONOTIFY
file status flag is set on the corresponding open file description.
@ -199,11 +202,11 @@ The reading application is responsible for closing the file descriptor.
.TP
.I pid
This is the ID of the process that caused the event.
A program listening to fanotify events can compare this PID to the PID returned
by
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 program.
to determine whether the event is caused by the listener itself,
or is due to a file access by another program.
.PP
The bit mask in
.I mask
@ -268,8 +271,8 @@ This is a synonym for;
FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE
.PP
The following macros are provided to iterate over a buffer containing fanotify
event metadata returned by a
The following macros are provided to iterate over a buffer containing
fanotify event metadata returned by a
.BR read (2)
from an fanotify file descriptor.
.TP
@ -350,7 +353,8 @@ for details.
.SH ERRORS
In addition to the usual errors for
.BR read (2),
the following errors can occur when reading from the fanotify file descriptor:
the following errors can occur when reading from the
fanotify file descriptor:
.TP
.B EINVAL
The buffer is too short to hold the event.
@ -387,8 +391,8 @@ In addition to the usual errors for
the following errors can occur when writing to the fanotify file descriptor:
.TP
.B EINVAL
Fanotify access permissions are not enabled in the kernel configuration or the
value of
Fanotify access permissions are not enabled in the kernel configuration
or the value of
.I response
in the response structure is not valid.
.TP
@ -414,7 +418,8 @@ configuration option is enabled.
.SS Limitations and caveats
Fanotify reports only events that a user-space program triggers through the
filesystem API.
As a result, it does not catch remote events that occur on network filesystems.
As a result,
it does not catch remote events that occur on network filesystems.
.PP
The fanotify API does not report file accesses and modifications that
may occur because of
@ -428,11 +433,12 @@ read, and closed.
Adding, removing, or changing children of a marked directory does not create
events for the monitored directory itself.
.PP
Fanotify monitoring of directories is not recursive: to monitor subdirectories
under a directory, additional marks must be created.
Fanotify monitoring of directories is not recursive:
to monitor subdirectories under a directory,
additional marks must be created.
(But note that the fanotify API provides no way of detecting when a
subdirectory has been created under a marked directory, which makes recursive
monitoring difficult.)
subdirectory has been created under a marked directory,
which makes recursive monitoring difficult.)
Monitoring mounts offers the capability to monitor a whole directory tree.
.PP
The event queue can overflow.
@ -442,9 +448,10 @@ As of Linux 3.15,
the following bug exists:
.IP * 3
.\" FIXME: A patch was proposed.
When an event is generated, no check is made to see whether the user ID of the
receiving process has authorization to read or write the file before passing a
file descriptor for that file.
When an event is generated,
no check is made to see whether the user ID of the
receiving process has authorization to read or write the file
before passing a file descriptor for that file.
This poses a security risk, when the
.B CAP_SYS_ADMIN
capability is set for programs executed by unprivileged users.