1
2FANOTIFY_INIT(2)           Linux Programmer's Manual          FANOTIFY_INIT(2)
3
4
5

NAME

7       fanotify_init - create and initialize fanotify group
8

SYNOPSIS

10       #include <fcntl.h>            /* Definition of O_* constants */
11       #include <sys/fanotify.h>
12
13       int fanotify_init(unsigned int flags, unsigned int event_f_flags);
14

DESCRIPTION

16       For an overview of the fanotify API, see fanotify(7).
17
18       fanotify_init() initializes a new fanotify group and returns a file de‐
19       scriptor for the event queue associated with the group.
20
21       The file descriptor is used in calls to fanotify_mark(2) to specify the
22       files,  directories,  mounts,  or filesystems for which fanotify events
23       shall be created.  These events are received by reading from  the  file
24       descriptor.   Some  events are only informative, indicating that a file
25       has been accessed.  Other events can be used to determine  whether  an‐
26       other  application is permitted to access a file or directory.  Permis‐
27       sion to access filesystem objects is granted by writing to the file de‐
28       scriptor.
29
30       Multiple  programs may be using the fanotify interface at the same time
31       to monitor the same files.
32
33       In the current implementation, the number of fanotify groups  per  user
34       is limited to 128.  This limit cannot be overridden.
35
36       Calling  fanotify_init()  requires  the CAP_SYS_ADMIN capability.  This
37       constraint might be relaxed in future versions of the API.   Therefore,
38       certain additional capability checks have been implemented as indicated
39       below.
40
41       The flags argument contains a multi-bit field defining the notification
42       class of the listening application and further single bit fields speci‐
43       fying the behavior of the file descriptor.
44
45       If multiple listeners for permission  events  exist,  the  notification
46       class  is used to establish the sequence in which the listeners receive
47       the events.
48
49       Only one of the following notification  classes  may  be  specified  in
50       flags:
51
52       FAN_CLASS_PRE_CONTENT
53              This  value  allows  the receipt of events notifying that a file
54              has been accessed and events for permission decisions if a  file
55              may  be  accessed.  It is intended for event listeners that need
56              to access files before they contain their final data.  This  no‐
57              tification class might be used by hierarchical storage managers,
58              for example.
59
60       FAN_CLASS_CONTENT
61              This value allows the receipt of events notifying  that  a  file
62              has  been accessed and events for permission decisions if a file
63              may be accessed.  It is intended for event listeners  that  need
64              to  access  files when they already contain their final content.
65              This notification class might be used by malware detection  pro‐
66              grams, for example.
67
68       FAN_CLASS_NOTIF
69              This  is  the  default value.  It does not need to be specified.
70              This value only allows the receipt of events  notifying  that  a
71              file has been accessed.  Permission decisions before the file is
72              accessed are not possible.
73
74       Listeners with different notification classes will  receive  events  in
75       the  order  FAN_CLASS_PRE_CONTENT,  FAN_CLASS_CONTENT, FAN_CLASS_NOTIF.
76       The order of notification for listeners in the same notification  class
77       is undefined.
78
79       The following bits can additionally be set in flags:
80
81       FAN_CLOEXEC
82              Set the close-on-exec flag (FD_CLOEXEC) on the new file descrip‐
83              tor.  See the description of the O_CLOEXEC flag in open(2).
84
85       FAN_NONBLOCK
86              Enable the nonblocking flag (O_NONBLOCK) for the  file  descrip‐
87              tor.  Reading from the file descriptor will not block.  Instead,
88              if no data is available, read(2) fails with the error EAGAIN.
89
90       FAN_UNLIMITED_QUEUE
91              Remove the limit of 16384 events for the event  queue.   Use  of
92              this flag requires the CAP_SYS_ADMIN capability.
93
94       FAN_UNLIMITED_MARKS
95              Remove  the  limit of 8192 marks.  Use of this flag requires the
96              CAP_SYS_ADMIN capability.
97
98       FAN_REPORT_TID (since Linux 4.20)
99              Report thread ID (TID) instead of process ID (PID)  in  the  pid
100              field  of the struct fanotify_event_metadata supplied to read(2)
101              (see fanotify(7)).
102
103       FAN_ENABLE_AUDIT (since Linux 4.15)
104              Enable generation of audit log records  about  access  mediation
105              performed  by  permission events.  The permission event response
106              has to be marked with the FAN_AUDIT flag for an audit log record
107              to be generated.
108
109       FAN_REPORT_FID (since Linux 5.1)
110              This value allows the receipt of events which contain additional
111              information about the underlying filesystem object correlated to
112              an  event.  An additional record of type FAN_EVENT_INFO_TYPE_FID
113              encapsulates the information about the object  and  is  included
114              alongside  the  generic  event metadata structure.  The file de‐
115              scriptor that is used to represent the object correlated  to  an
116              event is instead substituted with a file handle.  It is intended
117              for applications that may find the use of a file handle to iden‐
118              tify  an object more suitable than a file descriptor.  Addition‐
119              ally, it may be used for applications monitoring a directory  or
120              a  filesystem that are interested in the directory entry modifi‐
121              cation events FAN_CREATE, FAN_DELETE, and FAN_MOVE, or in events
122              such as FAN_ATTRIB, FAN_DELETE_SELF, and FAN_MOVE_SELF.  All the
123              events above require an fanotify group that identifies  filesys‐
124              tem  objects by file handles.  Note that for the directory entry
125              modification events the reported file handle identifies the mod‐
126              ified  directory and not the created/deleted/moved child object.
127              The use of FAN_CLASS_CONTENT  or  FAN_CLASS_PRE_CONTENT  is  not
128              permitted  with  this  flag and will result in the error EINVAL.
129              See fanotify(7) for additional details.
130
131       FAN_REPORT_DIR_FID (since Linux 5.9)
132              Events for fanotify groups initialized with this flag will  con‐
133              tain  (see  exceptions below) additional information about a di‐
134              rectory object correlated to an event.  An additional record  of
135              type FAN_EVENT_INFO_TYPE_DFID encapsulates the information about
136              the directory object and is included alongside the generic event
137              metadata  structure.   For  events that occur on a non-directory
138              object, the additional structure includes  a  file  handle  that
139              identifies  the  parent  directory filesystem object.  Note that
140              there is no guarantee that the directory filesystem object  will
141              be  found  at the location described by the file handle informa‐
142              tion at the time the event is received.  When combined with  the
143              flag  FAN_REPORT_FID,  two  records  may be reported with events
144              that occur on a non-directory object, one to identify  the  non-
145              directory object itself and one to identify the parent directory
146              object.  Note that in some cases, a filesystem object  does  not
147              have  a parent, for example, when an event occurs on an unlinked
148              but open file.  In that case, with the FAN_REPORT_FID flag,  the
149              event will be reported with only one record to identify the non-
150              directory object itself, because there is no  directory  associ‐
151              ated  with the event.  Without the FAN_REPORT_FID flag, no event
152              will be reported.  See fanotify(7) for additional details.
153
154       FAN_REPORT_NAME (since Linux 5.9)
155              Events for fanotify groups initialized with this flag will  con‐
156              tain  additional information about the name of the directory en‐
157              try correlated to an event.  This flag must be provided in  con‐
158              junction  with the flag FAN_REPORT_DIR_FID.  Providing this flag
159              value without FAN_REPORT_DIR_FID will result in the  error  EIN‐
160              VAL.   This  flag  may be combined with the flag FAN_REPORT_FID.
161              An  additional  record  of  type  FAN_EVENT_INFO_TYPE_DFID_NAME,
162              which encapsulates the information about the directory entry, is
163              included alongside the generic event metadata structure and sub‐
164              stitutes    the    additional   information   record   of   type
165              FAN_EVENT_INFO_TYPE_DFID.  The additional record includes a file
166              handle that identifies a directory filesystem object followed by
167              a name that identifies an entry in that directory.  For the  di‐
168              rectory  entry  modification  events FAN_CREATE, FAN_DELETE, and
169              FAN_MOVE, the reported name is that of the created/deleted/moved
170              directory entry.  For other events that occur on a directory ob‐
171              ject, the reported file handle is that of the  directory  object
172              itself  and the reported name is '.'.  For other events that oc‐
173              cur on a non-directory object, the reported file handle is  that
174              of the parent directory object and the reported name is the name
175              of a directory entry where the object was located at the time of
176              the event.  The rationale behind this logic is that the reported
177              directory file handle can be passed to  open_by_handle_at(2)  to
178              get  an  open directory file descriptor and that file descriptor
179              along with the reported name can be  used  to  call  fstatat(2).
180              The     same     rule    that    applies    to    record    type
181              FAN_EVENT_INFO_TYPE_DFID   also   applies   to    record    type
182              FAN_EVENT_INFO_TYPE_DFID_NAME:  if a non-directory object has no
183              parent, either the event will not be reported or it will be  re‐
184              ported without the directory entry information.  Note that there
185              is no guarantee that the filesystem object will be found at  the
186              location  described  by  the  directory entry information at the
187              time the event is received.  See fanotify(7) for additional  de‐
188              tails.
189
190       FAN_REPORT_DFID_NAME
191              This is a synonym for (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).
192
193       The  event_f_flags  argument defines the file status flags that will be
194       set on the open file descriptions that are created for fanotify events.
195       For  details of these flags, see the description of the flags values in
196       open(2).  event_f_flags includes a multi-bit field for the access mode.
197       This field can take the following values:
198
199       O_RDONLY
200              This value allows only read access.
201
202       O_WRONLY
203              This value allows only write access.
204
205       O_RDWR This value allows read and write access.
206
207       Additional  bits  can  be set in event_f_flags.  The most useful values
208       are:
209
210       O_LARGEFILE
211              Enable support for files exceeding 2 GB.  Failing  to  set  this
212              flag  will  result  in  an EOVERFLOW error when trying to open a
213              large file which is monitored by an fanotify group on  a  32-bit
214              system.
215
216       O_CLOEXEC (since Linux 3.18)
217              Enable  the close-on-exec flag for the file descriptor.  See the
218              description of the O_CLOEXEC flag in  open(2)  for  reasons  why
219              this may be useful.
220
221       The  following are also allowable: O_APPEND, O_DSYNC, O_NOATIME, O_NON‐
222       BLOCK, and O_SYNC.  Specifying any other flag in  event_f_flags  yields
223       the error EINVAL (but see BUGS).
224

RETURN VALUE

226       On  success,  fanotify_init() returns a new file descriptor.  On error,
227       -1 is returned, and errno is set to indicate the error.
228

ERRORS

230       EINVAL An  invalid  value  was  passed  in  flags   or   event_f_flags.
231              FAN_ALL_INIT_FLAGS  (deprecated since Linux kernel version 4.20)
232              defines all allowable bits for flags.
233
234       EMFILE The number of fanotify groups for this user exceeds 128.
235
236       EMFILE The per-process limit on the number of open file descriptors has
237              been reached.
238
239       ENOMEM The allocation of memory for the notification group failed.
240
241       ENOSYS This  kernel  does  not implement fanotify_init().  The fanotify
242              API is available only if the kernel  was  configured  with  CON‐
243              FIG_FANOTIFY.
244
245       EPERM  The  operation  is  not  permitted  because the caller lacks the
246              CAP_SYS_ADMIN capability.
247

VERSIONS

249       fanotify_init() was introduced in version 2.6.36 of  the  Linux  kernel
250       and enabled in version 2.6.37.
251

CONFORMING TO

253       This system call is Linux-specific.
254

BUGS

256       The following bug was present in Linux kernels before version 3.18:
257
258       *  The O_CLOEXEC is ignored when passed in event_f_flags.
259
260       The following bug was present in Linux kernels before version 3.14:
261
262       *  The  event_f_flags argument is not checked for invalid flags.  Flags
263          that are intended only for internal use, such as FMODE_EXEC, can  be
264          set,  and will consequently be set for the file descriptors returned
265          when reading from the fanotify file descriptor.
266

SEE ALSO

268       fanotify_mark(2), fanotify(7)
269

COLOPHON

271       This page is part of release 5.13 of the Linux  man-pages  project.   A
272       description  of  the project, information about reporting bugs, and the
273       latest    version    of    this    page,    can     be     found     at
274       https://www.kernel.org/doc/man-pages/.
275
276
277
278Linux                             2021-03-22                  FANOTIFY_INIT(2)
Impressum