From: Heinrich Schuchardt Date: Fri, 25 Apr 2014 05:56:02 +0000 (+0200) Subject: fanotify_init.2: New page documenting fanotify_init(2) X-Git-Tag: man-pages-3.66~188 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=3e6ebb33e54bb0c68ee1fe3abc940bd12a161ed7;p=thirdparty%2Fman-pages.git fanotify_init.2: New page documenting fanotify_init(2) Signed-off-by: Heinrich Schuchardt Signed-off-by: Michael Kerrisk --- diff --git a/man2/fanotify_init.2 b/man2/fanotify_init.2 new file mode 100644 index 0000000000..3214d9eafa --- /dev/null +++ b/man2/fanotify_init.2 @@ -0,0 +1,207 @@ +.\" Copyright (C) 2013, Heinrich Schuchardt +.\" +.\" %%%LICENSE_START(VERBATIM) +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume. +.\" no responsibility for errors or omissions, or for damages resulting. +.\" from the use of the information contained herein. The author(s) may. +.\" not have taken the same level of care in the production of this. +.\" manual, which is licensed free of charge, as they might when working. +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" %%%LICENSE_END +.TH FANOTIFY_INIT 2 2014-04-24 "Linux" "Linux Programmer's Manual" +.SH NAME +fanotify_init \- create and initialize fanotify group +.SH SYNOPSIS +.B #include +.br +.B #include +.sp +.BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); +.SH DESCRIPTION +For an overview of the fanotify API, see +.BR fanotify (7). +.PP +.BR fanotify_init () +initializes a new fanotify group and returns a file descriptor for the event +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. +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 control if another application may access a file +or directory. +Permission to access filesystem objects is granted by writing to the file +descriptor. +.PP +Multiple programs may be using the fanotify interface at the same time to +monitor the same files. +.PP +In the current implementation, the number of fanotify groups per user is +limited to 128. +This limit cannot be overridden. +.PP +Calling +.BR fanotify_init () +requires the +.B 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. +.PP +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. +.PP +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 values may be specified in +.IR flags . +.TP +.B FAN_CLASS_PRE_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 before they +contain their final data. +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. +This notification class might be used by malware detection programs, for +example. +.TP +.B FAN_CLASS_NOTIF +This is the default value. +It does not need to be specified. +This value only allows the receipt of events notifying that a file has been +accessed. +Permission decisions before the file is accessed are not possible. +.PP +Listeners with different notification classes will receive events in the +sequence +.BR FAN_CLASS_PRE_CONTENT , +.BR FAN_CLASS_CONTENT , +.BR FAN_CLASS_NOTIF . +The order of notification for listeners of the same value is undefined. +.PP +The following bit mask values can be set additionally in +.IR flags : +.TP +.B FAN_CLOEXEC +This flag sets the close-on-exec flag +.RB ( FD_CLOEXEC ) +on the new file descriptor. +See the description of the +.B O_CLOEXEC +flag in +.BR open (2). +.TP +.B FAN_NONBLOCK +This flag enables the nonblocking flag +.RB ( O_NONBLOCK ) +for the file descriptor. +Reading from the file descriptor will not block. +Instead, if no data is available in a call to +.BR read (2) +the error +.B EAGAIN +will occur. +.TP +.B FAN_UNLIMITED_QUEUE +This flag removes the limit of 16384 events on the size of the event queue. +It requires the +.B CAP_SYS_ADMIN +capability. +.TP +.B FAN_UNLIMITED_MARKS +This flag removes the limit of 8192 marks. +It requires the +.B CAP_SYS_ADMIN +capability. +.PP +The argument +.I event_f_flags +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 +.BR open (2) +system call. +Useful values are: +.TP +.B O_RDONLY +This value allows only read access. +.TP +.B O_WRONLY +This value allows only write access. +.TP +.B O_RDWR +This value allows read and write access. +.TP +.B O_CLOEXEC +This flag enables the close-on-exec flag for the file descriptor. +.TP +.B O_LARGEFILE +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. +.SH RETURN VALUE +On success, +.BR fanotify_init () +returns a new file descriptor. +In case of an error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +An invalid value was passed in +.IR flags . +.B FAN_ALL_INIT_FLAGS +defines all allowable bits. +.TP +.B EMFILE +The number of fanotify groups of the user exceeds 128. +.TP +.B ENOMEM +The allocation of memory for the notification group failed. +.TP +.B EPERM +The operation is not permitted because the caller lacks the +.B CAP_SYS_ADMIN +capability. +.SH VERSIONS +.BR fanotify_init () +was introduced in version 2.6.36 of the Linux kernel and enabled in version +2.6.37. +.SH "CONFORMING TO" +This system call is Linux-specific. +.SH "SEE ALSO" +.BR fanotify_mark (2), +.BR fanotify (7)