From 1b24e2ee0ecc69eb2e5baee761484b5a5ad14351 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Mon, 5 May 2014 11:45:37 +0200 Subject: [PATCH] fanotify_init.2, fanotify_mark.2, fanotify.7: srcfix: rewrap long source lines Signed-off-by: Michael Kerrisk --- man2/fanotify_init.2 | 29 ++++++++-------- man2/fanotify_mark.2 | 15 ++++---- man7/fanotify.7 | 83 ++++++++++++++++++++++++-------------------- 3 files changed, 68 insertions(+), 59 deletions(-) diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 index c3c56dd5a..01a8478ad 100644 --- a/man2/fanotify_init.2 +++ b/man2/fanotify_init.2 @@ -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 () diff --git a/man2/fanotify_mark.2 b/man2/fanotify_mark.2 index c311d95f1..5fe92eca2 100644 --- a/man2/fanotify_mark.2 +++ b/man2/fanotify_mark.2 @@ -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. diff --git a/man7/fanotify.7 b/man7/fanotify.7 index e5549d6bc..424ada72e 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -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.