| .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> |
| .\" |
| .\" %%%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 2016-03-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| fanotify_init \- create and initialize fanotify group |
| .SH SYNOPSIS |
| .B #include <fcntl.h> |
| .br |
| .B #include <sys/fanotify.h> |
| .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 determine whether |
| another application is permitted to 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 notification classes 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 |
| order |
| .BR FAN_CLASS_PRE_CONTENT , |
| .BR FAN_CLASS_CONTENT , |
| .BR FAN_CLASS_NOTIF . |
| The order of notification for listeners in the same notification class |
| is undefined. |
| .PP |
| The following bits can additionally be set in |
| .IR flags : |
| .TP |
| .B FAN_CLOEXEC |
| Set 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 |
| Enable the nonblocking flag |
| .RB ( O_NONBLOCK ) |
| for the file descriptor. |
| Reading from the file descriptor will not block. |
| Instead, if no data is available, |
| .BR read (2) |
| will fail with the error |
| .BR EAGAIN . |
| .TP |
| .B FAN_UNLIMITED_QUEUE |
| Remove the limit of 16384 events for the event queue. |
| Use of this flag requires the |
| .B CAP_SYS_ADMIN |
| capability. |
| .TP |
| .B FAN_UNLIMITED_MARKS |
| Remove the limit of 8192 marks. |
| Use of this flag requires the |
| .B CAP_SYS_ADMIN |
| capability. |
| .PP |
| The |
| .I event_f_flags |
| argument |
| defines the file status flags that will be set on the open file descriptions |
| that are created for fanotify events. |
| For details of these flags, see the description of the |
| .I flags |
| values in |
| .BR open (2). |
| .I event_f_flags |
| includes a multi-bit field for the access mode. |
| This field can take the following values: |
| .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. |
| .PP |
| Additional bits can be set in |
| .IR event_f_flags . |
| The most useful values are: |
| .TP |
| .B O_LARGEFILE |
| Enable 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. |
| .TP |
| .BR O_CLOEXEC " (since Linux 3.18)" |
| .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 |
| Enable the close-on-exec flag for the file descriptor. |
| See the description of the |
| .B O_CLOEXEC |
| flag in |
| .BR open (2) |
| for reasons why this may be useful. |
| .PP |
| The following are also allowable: |
| .BR O_APPEND , |
| .BR O_DSYNC , |
| .BR O_NOATIME , |
| .BR O_NONBLOCK , |
| and |
| .BR O_SYNC . |
| Specifying any other flag in |
| .I event_f_flags |
| yields the error |
| .B EINVAL |
| (but see BUGS). |
| .SH RETURN VALUE |
| On success, |
| .BR fanotify_init () |
| returns a new file descriptor. |
| On error, \-1 is returned, and |
| .I errno |
| is set to indicate the error. |
| .SH ERRORS |
| .TP |
| .B EINVAL |
| An invalid value was passed in |
| .I flags |
| or |
| .IR event_f_flags . |
| .B FAN_ALL_INIT_FLAGS |
| defines all allowable bits for |
| .IR flags . |
| .TP |
| .B EMFILE |
| The number of fanotify groups for this user exceeds 128. |
| .TP |
| .B |
| The per-process limit on the number of open file descriptors has been reached. |
| .TP |
| .B ENOMEM |
| The allocation of memory for the notification group failed. |
| .TP |
| .B ENOSYS |
| This kernel does not implement |
| .BR fanotify_init (). |
| The fanotify API is available only if the kernel was configured with |
| .BR CONFIG_FANOTIFY . |
| .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 BUGS |
| As of Linux 3.17, |
| the following bug exists: |
| .IP * 3 |
| .\" FIXME . Patch proposed: https://lkml.org/lkml/2014/9/24/967 |
| The |
| .B O_CLOEXEC |
| is ignored when passed in |
| .IR event_f_flags . |
| .PP |
| The following bug was present in Linux kernels before version 3.14: |
| .IP * 3 |
| .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 |
| The |
| .I event_f_flags |
| argument is not checked for invalid flags. |
| Flags that are intended only for internal use, |
| such as |
| .BR FMODE_EXEC , |
| can be set, and will consequently be set for the file descriptors |
| returned when reading from the fanotify file descriptor. |
| .SH SEE ALSO |
| .BR fanotify_mark (2), |
| .BR fanotify (7) |