diff options
Diffstat (limited to 'man7/fanotify.7')
| -rw-r--r-- | man7/fanotify.7 | 116 |
1 files changed, 58 insertions, 58 deletions
diff --git a/man7/fanotify.7 b/man7/fanotify.7 index 07e445546..02df55e9a 100644 --- a/man7/fanotify.7 +++ b/man7/fanotify.7 @@ -13,26 +13,26 @@ In the original fanotify API, only a limited set of events was supported. In particular, there was no support for create, delete, and move events. The support for those events was added in Linux 5.1. (See -.BR inotify (7) +.MR inotify 7 for details of an API that did notify those events pre Linux 5.1.) .P Additional capabilities compared to the -.BR inotify (7) +.MR 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. .P The following system calls are used with this API: -.BR fanotify_init (2), -.BR fanotify_mark (2), -.BR read (2), -.BR write (2), +.MR fanotify_init 2 , +.MR fanotify_mark 2 , +.MR read 2 , +.MR write 2 , and -.BR close (2). +.MR close 2 . .SS fanotify_init(), fanotify_mark(), and notification groups The -.BR fanotify_init (2) +.MR fanotify_init 2 system call creates and initializes an fanotify notification group and returns a file descriptor referring to it. .P @@ -52,7 +52,7 @@ directory to be marked for receiving events, while at the same time ignoring events for specific objects under a mount or directory. .P The -.BR fanotify_mark (2) +.MR 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. @@ -80,11 +80,11 @@ filesystems or mounts are unmounted, the corresponding entries are deleted. As events occur on the filesystem objects monitored by a notification group, the fanotify system generates events that are collected in a queue. These events can then be read (using -.BR read (2) +.MR read 2 or similar) from the fanotify file descriptor returned by -.BR fanotify_init (2). +.MR fanotify_init 2 . .P Two types of events are generated: .I notification @@ -107,19 +107,19 @@ writing to the fanotify file descriptor or the fanotify file descriptor is closed. .SS Reading fanotify events Calling -.BR read (2) +.MR read 2 for the file descriptor returned by -.BR fanotify_init (2) +.MR fanotify_init 2 blocks (if the flag .B FAN_NONBLOCK is not specified in the call to -.BR fanotify_init (2)) +.MR fanotify_init 2 ) until either a file event occurs or the call is interrupted by a signal (see -.BR signal (7)). +.MR signal 7 ). .P After a successful -.BR read (2), +.MR read 2 , the read buffer contains one or more of the following structures: .P .in +4n @@ -144,7 +144,7 @@ structure. The .I flags passed to -.BR fanotify_init (2) +.MR fanotify_init 2 have influence over the type of information records that may be returned for an event. For example, @@ -268,10 +268,10 @@ struct fanotify_event_info_header { 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). +.MR read 2 . .P The return value of -.BR read (2) +.MR read 2 is the number of bytes placed in the buffer, or \-1 in case of an error (but see BUGS). .P @@ -324,7 +324,7 @@ of the monitored file or directory. The reading application is responsible for closing this file descriptor. .IP When calling -.BR fanotify_init (2), +.MR fanotify_init 2 , the caller may specify (via the .I event_f_flags argument) various file status flags that are to be set @@ -340,13 +340,13 @@ directory using this file descriptor, no additional events will be created. If flag .B FAN_REPORT_TID was set in -.BR fanotify_init (2), +.MR 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. .P A program listening to fanotify events can compare this PID to the PID returned by -.BR getpid (2), +.MR getpid 2 , to determine whether the event is caused by the listener itself, or is due to a file access by another process. .P @@ -373,7 +373,7 @@ A file or a directory was opened. .B FAN_OPEN_EXEC A file was opened with the intent to be executed. See NOTES in -.BR fanotify_mark (2) +.MR fanotify_mark 2 for additional details. .TP .B FAN_ATTRIB @@ -423,13 +423,13 @@ The event queue exceeded the limit on number of events. This limit can be overridden by specifying the .B FAN_UNLIMITED_QUEUE flag when calling -.BR fanotify_init (2). +.MR fanotify_init 2 . .TP .B FAN_ACCESS_PERM An application wants to read a file or directory, for example using -.BR read (2) +.MR read 2 or -.BR readdir (2). +.MR readdir 2 . The reader must write a response (as described below) that determines whether the permission to access the filesystem object shall be granted. @@ -444,7 +444,7 @@ An application wants to open a file for execution. The reader must write a response that determines whether the permission to open the filesystem object for execution shall be granted. See NOTES in -.BR fanotify_mark (2) +.MR fanotify_mark 2 for additional details. .P To check for any close event, the following bit mask may be used: @@ -481,7 +481,7 @@ The events described in the have occurred on a directory object. Reporting events on directories requires setting this flag in the mark mask. See -.BR fanotify_mark (2) +.MR fanotify_mark 2 for additional details. The .B FAN_ONDIR @@ -507,7 +507,7 @@ or .BR FAN_EVENT_INFO_TYPE_PIDFD . The value set for this field is dependent on the flags that have been supplied to -.BR fanotify_init (2). +.MR fanotify_init 2 . Refer to the field details of each information record object type below to understand the different cases in which the .I info_type @@ -574,17 +574,17 @@ It is a structure of type and contains the same value as .I f_fsid when calling -.BR statfs (2). +.MR statfs 2 . .TP .I handle This field contains a variable-length structure of type .IR "struct file_handle" . It is an opaque handle that corresponds to a specified object on a filesystem as returned by -.BR name_to_handle_at (2). +.MR name_to_handle_at 2 . It can be used to uniquely identify a file on a filesystem and can be passed as an argument to -.BR open_by_handle_at (2). +.MR open_by_handle_at 2 . If the value of .I info_type field is @@ -645,7 +645,7 @@ This is a process file descriptor that refers to the process responsible for generating the event. The returned process file descriptor is no different from one which could be obtained manually if -.BR pidfd_open (2) +.MR pidfd_open 2 were to be called on .IR fanotify_event_metadata.pid . In the instance that an error is encountered during pidfd creation, @@ -667,7 +667,7 @@ All other possible pidfd creation failures are represented by Once the event listener has dealt with an event and the pidfd is no longer required, the pidfd should be closed via -.BR close (2). +.MR close 2 . .P The fields of the .I fanotify_event_info_error @@ -690,7 +690,7 @@ since the last error was read. .P The following macros are provided to iterate over a buffer containing fanotify event metadata returned by a -.BR read (2) +.MR read 2 from an fanotify file descriptor: .TP .B FAN_EVENT_OK(meta, len) @@ -731,13 +731,13 @@ This is the minimum size (and currently the only size) of any event metadata. .SS Monitoring an fanotify file descriptor for events When an fanotify event occurs, the fanotify file descriptor indicates as readable when passed to -.BR epoll (7), -.BR poll (2), +.MR epoll 7 , +.MR poll 2 , or -.BR select (2). +.MR select 2 . .SS Dealing with permission events For permission events, the application must -.BR write (2) +.MR write 2 a structure of the following form to the fanotify file descriptor: .P @@ -812,7 +812,7 @@ When all file descriptors referring to the fanotify notification group are closed, the fanotify group is released and its resources are freed for reuse by the kernel. Upon -.BR close (2), +.MR close 2 , outstanding permission events will be set to allowed. .SS /proc interfaces The file @@ -822,7 +822,7 @@ contains information about fanotify marks for file descriptor of process .IR pid . See -.BR proc (5) +.MR proc 5 for details. .P Since Linux 5.13, @@ -832,7 +832,7 @@ kernel resources consumed by fanotify: .TP .I /proc/sys/fs/fanotify/max_queued_events The value in this file is used when an application calls -.BR fanotify_init (2) +.MR fanotify_init 2 to set an upper limit on the number of events that can be queued to the corresponding fanotify group. Events in excess of this limit are dropped, but an @@ -857,7 +857,7 @@ Prior to Linux kernel 5.13, the hardcoded limit was 8192 marks per group (not per user). .SH ERRORS In addition to the usual errors for -.BR read (2), +.MR read 2 , the following errors can occur when reading from the fanotify file descriptor: .TP @@ -869,18 +869,18 @@ The per-process limit on the number of open files has been reached. See the description of .B RLIMIT_NOFILE in -.BR getrlimit (2). +.MR getrlimit 2 . .TP .B ENFILE The system-wide limit on the total number of open files has been reached. See .I /proc/sys/fs/file\-max in -.BR proc (5). +.MR proc 5 . .TP .B ETXTBSY This error is returned by -.BR read (2) +.MR read 2 if .B O_RDWR or @@ -888,11 +888,11 @@ or was specified in the .I event_f_flags argument when calling -.BR fanotify_init (2) +.MR fanotify_init 2 and an event occurred for a monitored file that is currently being executed. .P In addition to the usual errors for -.BR write (2), +.MR write 2 , the following errors can occur when writing to the fanotify file descriptor: .TP .B EINVAL @@ -928,10 +928,10 @@ it does not catch remote events that occur on network filesystems. .P The fanotify API does not report file accesses and modifications that may occur because of -.BR mmap (2), -.BR msync (2), +.MR mmap 2 , +.MR msync 2 , and -.BR munmap (2). +.MR munmap 2 . .P Events for directories are created only if the directory itself is opened, read, and closed. @@ -957,12 +957,12 @@ The event queue can overflow. In this case, events are lost. .SH BUGS Before Linux 3.19, -.BR fallocate (2) +.MR fallocate 2 did not generate fanotify events. Since Linux 3.19, .\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 calls to -.BR fallocate (2) +.MR fallocate 2 generate .B FAN_MODIFY events. @@ -974,7 +974,7 @@ On Linux, a filesystem object may be accessible through multiple paths, for example, a part of a filesystem may be remounted using the .I \-\-bind option of -.BR mount (8). +.MR mount 8 . A listener that marked a mount will be notified only of events that were triggered for a filesystem object using the same mount. Any other event will pass unnoticed. @@ -989,7 +989,7 @@ This poses a security risk, when the capability is set for programs executed by unprivileged users. .IP \[bu] If a call to -.BR read (2) +.MR read 2 processes multiple events from the fanotify queue and an error occurs, the return value will be the total length of the events successfully copied to the user-space buffer before the error occurred. @@ -1451,6 +1451,6 @@ main(int argc, char *argv[]) .EE .SH SEE ALSO .ad l -.BR fanotify_init (2), -.BR fanotify_mark (2), -.BR inotify (7) +.MR fanotify_init 2 , +.MR fanotify_mark 2 , +.MR inotify 7 |