| \" 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 2021-03-22 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| fanotify_init \- create and initialize fanotify group |
| .SH SYNOPSIS |
| .nf |
| .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" |
| .B #include <sys/fanotify.h> |
| .PP |
| .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); |
| .fi |
| .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, mounts, or filesystems 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) |
| fails 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. |
| .TP |
| .BR FAN_REPORT_TID " (since Linux 4.20)" |
| .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29 |
| Report thread ID (TID) instead of process ID (PID) |
| in the |
| .I pid |
| field of the |
| .I "struct fanotify_event_metadata" |
| supplied to |
| .BR read (2) |
| (see |
| .BR fanotify (7)). |
| .TP |
| .BR FAN_ENABLE_AUDIT " (since Linux 4.15)" |
| .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269 |
| Enable generation of audit log records about access mediation performed by |
| permission events. |
| The permission event response has to be marked with the |
| .B FAN_AUDIT |
| flag for an audit log record to be generated. |
| .TP |
| .BR FAN_REPORT_FID " (since Linux 5.1)" |
| .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360 |
| This value allows the receipt of events which contain additional information |
| about the underlying filesystem object correlated to an event. |
| An additional record of type |
| .BR FAN_EVENT_INFO_TYPE_FID |
| encapsulates the information about the object and is included alongside the |
| generic event metadata structure. |
| The file descriptor that is used to represent the object correlated to an |
| event is instead substituted with a file handle. |
| It is intended for applications that may find the use of a file handle to |
| identify an object more suitable than a file descriptor. |
| Additionally, it may be used for applications monitoring a directory or a |
| filesystem that are interested in the directory entry modification events |
| .BR FAN_CREATE , |
| .BR FAN_DELETE , |
| and |
| .BR FAN_MOVE , |
| or in events such as |
| .BR FAN_ATTRIB , |
| .BR FAN_DELETE_SELF , |
| and |
| .BR FAN_MOVE_SELF . |
| All the events above require an fanotify group that identifies filesystem |
| objects by file handles. |
| Note that for the directory entry modification events the reported file handle |
| identifies the modified directory and not the created/deleted/moved child |
| object. |
| The use of |
| .BR FAN_CLASS_CONTENT |
| or |
| .BR FAN_CLASS_PRE_CONTENT |
| is not permitted with this flag and will result in the error |
| .BR EINVAL . |
| See |
| .BR fanotify (7) |
| for additional details. |
| .TP |
| .BR FAN_REPORT_DIR_FID " (since Linux 5.9)" |
| Events for fanotify groups initialized with this flag will contain |
| (see exceptions below) additional information about a directory object |
| correlated to an event. |
| An additional record of type |
| .BR FAN_EVENT_INFO_TYPE_DFID |
| encapsulates the information about the directory object and is included |
| alongside the generic event metadata structure. |
| For events that occur on a non-directory object, the additional structure |
| includes a file handle that identifies the parent directory filesystem object. |
| Note that there is no guarantee that the directory filesystem object will be |
| found at the location described by the file handle information at the time |
| the event is received. |
| When combined with the flag |
| .BR FAN_REPORT_FID , |
| two records may be reported with events that occur on a non-directory object, |
| one to identify the non-directory object itself and one to identify the parent |
| directory object. |
| Note that in some cases, a filesystem object does not have a parent, |
| for example, when an event occurs on an unlinked but open file. |
| In that case, with the |
| .BR FAN_REPORT_FID |
| flag, the event will be reported with only one record to identify the |
| non-directory object itself, because there is no directory associated with |
| the event. |
| Without the |
| .BR FAN_REPORT_FID |
| flag, no event will be reported. |
| See |
| .BR fanotify (7) |
| for additional details. |
| .TP |
| .BR FAN_REPORT_NAME " (since Linux 5.9)" |
| Events for fanotify groups initialized with this flag will contain additional |
| information about the name of the directory entry correlated to an event. |
| This flag must be provided in conjunction with the flag |
| .BR FAN_REPORT_DIR_FID . |
| Providing this flag value without |
| .BR FAN_REPORT_DIR_FID |
| will result in the error |
| .BR EINVAL . |
| This flag may be combined with the flag |
| .BR FAN_REPORT_FID . |
| An additional record of type |
| .BR FAN_EVENT_INFO_TYPE_DFID_NAME , |
| which encapsulates the information about the directory entry, is included |
| alongside the generic event metadata structure and substitutes the additional |
| information record of type |
| .BR FAN_EVENT_INFO_TYPE_DFID . |
| The additional record includes a file handle that identifies a directory |
| filesystem object followed by a name that identifies an entry in that |
| directory. |
| For the directory entry modification events |
| .BR FAN_CREATE , |
| .BR FAN_DELETE , |
| and |
| .BR FAN_MOVE , |
| the reported name is that of the created/deleted/moved directory entry. |
| For other events that occur on a directory object, the reported file handle |
| is that of the directory object itself and the reported name is '.'. |
| For other events that occur on a non-directory object, the reported file handle |
| is that of the parent directory object and the reported name is the name of a |
| directory entry where the object was located at the time of the event. |
| The rationale behind this logic is that the reported directory file handle can |
| be passed to |
| .BR open_by_handle_at (2) |
| to get an open directory file descriptor and that file descriptor along with |
| the reported name can be used to call |
| .BR fstatat (2). |
| The same rule that applies to record type |
| .BR FAN_EVENT_INFO_TYPE_DFID |
| also applies to record type |
| .BR FAN_EVENT_INFO_TYPE_DFID_NAME : |
| if a non-directory object has no parent, either the event will not be reported |
| or it will be reported without the directory entry information. |
| Note that there is no guarantee that the filesystem object will be found at the |
| location described by the directory entry information at the time the event is |
| received. |
| See |
| .BR fanotify (7) |
| for additional details. |
| .TP |
| .B FAN_REPORT_DFID_NAME |
| This is a synonym for |
| .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). |
| .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 |
| (deprecated since Linux kernel version 4.20) |
| .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4 |
| defines all allowable bits for |
| .IR flags . |
| .TP |
| .B EMFILE |
| The number of fanotify groups for this user exceeds 128. |
| .TP |
| .B EMFILE |
| 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 |
| The following bug was present in Linux kernels before version 3.18: |
| .IP * 3 |
| .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 |
| 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) |