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>
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_REPORT_FID (since Linux 5.1)
104              This value allows the receipt of events which contain additional
105              information about the underlying filesystem object correlated to
106              an event.  An additional record of type  FAN_EVENT_INFO_TYPE_FID
107              encapsulates  the  information  about the object and is included
108              alongside the generic event metadata structure.   The  file  de‐
109              scriptor  that  is used to represent the object correlated to an
110              event is instead substituted with a file handle.  It is intended
111              for applications that may find the use of a file handle to iden‐
112              tify an object more suitable than a file descriptor.   Addition‐
113              ally,  it may be used for applications monitoring a directory or
114              a filesystem that are interested in the directory entry  modifi‐
115              cation events FAN_CREATE, FAN_DELETE, and FAN_MOVE, or in events
116              such as FAN_ATTRIB, FAN_DELETE_SELF, and FAN_MOVE_SELF.  All the
117              events  above require an fanotify group that identifies filesys‐
118              tem objects by file handles.  Note that for the directory  entry
119              modification events the reported file handle identifies the mod‐
120              ified directory and not the created/deleted/moved child  object.
121              The  use  of  FAN_CLASS_CONTENT  or FAN_CLASS_PRE_CONTENT is not
122              permitted with this flag and will result in  the  error  EINVAL.
123              See fanotify(7) for additional details.
124
125       FAN_REPORT_DIR_FID (since Linux 5.9)
126              Events  for fanotify groups initialized with this flag will con‐
127              tain (see exceptions below) additional information about  a  di‐
128              rectory  object correlated to an event.  An additional record of
129              type FAN_EVENT_INFO_TYPE_DFID encapsulates the information about
130              the directory object and is included alongside the generic event
131              metadata structure.  For events that occur  on  a  non-directory
132              object,  the  additional  structure  includes a file handle that
133              identifies the parent directory filesystem  object.   Note  that
134              there  is no guarantee that the directory filesystem object will
135              be found at the location described by the file  handle  informa‐
136              tion  at the time the event is received.  When combined with the
137              flag FAN_REPORT_FID, two records may  be  reported  with  events
138              that  occur  on a non-directory object, one to identify the non-
139              directory object itself and one to identify the parent directory
140              object.   Note  that in some cases, a filesystem object does not
141              have a parent, for example, when an event occurs on an  unlinked
142              but  open file.  In that case, with the FAN_REPORT_FID flag, the
143              event will be reported with only one record to identify the non-
144              directory  object  itself, because there is no directory associ‐
145              ated with the event.  Without the FAN_REPORT_FID flag, no  event
146              will be reported.  See fanotify(7) for additional details.
147
148       FAN_REPORT_NAME (since Linux 5.9)
149              Events  for fanotify groups initialized with this flag will con‐
150              tain additional information about the name of the directory  en‐
151              try  correlated to an event.  This flag must be provided in con‐
152              junction with the flag FAN_REPORT_DIR_FID.  Providing this  flag
153              value  without  FAN_REPORT_DIR_FID will result in the error EIN‐
154              VAL.  This flag may be combined with  the  flag  FAN_REPORT_FID.
155              An  additional  record  of  type  FAN_EVENT_INFO_TYPE_DFID_NAME,
156              which encapsulates the information about the directory entry, is
157              included alongside the generic event metadata structure and sub‐
158              stitutes   the   additional   information   record    of    type
159              FAN_EVENT_INFO_TYPE_DFID.  The additional record includes a file
160              handle that identifies a directory filesystem object followed by
161              a  name that identifies an entry in that directory.  For the di‐
162              rectory entry modification events  FAN_CREATE,  FAN_DELETE,  and
163              FAN_MOVE, the reported name is that of the created/deleted/moved
164              directory entry.  For other events that occur on a directory ob‐
165              ject,  the  reported file handle is that of the directory object
166              itself and the reported name is '.'.  For other events that  oc‐
167              cur  on a non-directory object, the reported file handle is that
168              of the parent directory object and the reported name is the name
169              of a directory entry where the object was located at the time of
170              the event.  The rationale behind this logic is that the reported
171              directory  file  handle can be passed to open_by_handle_at(2) to
172              get an open directory file descriptor and that  file  descriptor
173              along  with  the  reported  name can be used to call fstatat(2).
174              The    same    rule    that    applies    to     record     type
175              FAN_EVENT_INFO_TYPE_DFID    also    applies   to   record   type
176              FAN_EVENT_INFO_TYPE_DFID_NAME: if a non-directory object has  no
177              parent,  either the event will not be reported or it will be re‐
178              ported without the directory entry information.  Note that there
179              is  no guarantee that the filesystem object will be found at the
180              location described by the directory  entry  information  at  the
181              time  the event is received.  See fanotify(7) for additional de‐
182              tails.
183
184       FAN_REPORT_DFID_NAME
185              This is a synonym for (FAN_REPORT_DIR_FID|FAN_REPORT_NAME).
186
187       The event_f_flags argument defines the file status flags that  will  be
188       set on the open file descriptions that are created for fanotify events.
189       For details of these flags, see the description of the flags values  in
190       open(2).  event_f_flags includes a multi-bit field for the access mode.
191       This field can take the following values:
192
193       O_RDONLY
194              This value allows only read access.
195
196       O_WRONLY
197              This value allows only write access.
198
199       O_RDWR This value allows read and write access.
200
201       Additional bits can be set in event_f_flags.  The  most  useful  values
202       are:
203
204       O_LARGEFILE
205              Enable  support  for  files exceeding 2 GB.  Failing to set this
206              flag will result in an EOVERFLOW error when  trying  to  open  a
207              large  file  which is monitored by an fanotify group on a 32-bit
208              system.
209
210       O_CLOEXEC (since Linux 3.18)
211              Enable the close-on-exec flag for the file descriptor.  See  the
212              description  of  the  O_CLOEXEC  flag in open(2) for reasons why
213              this may be useful.
214
215       The following are also allowable: O_APPEND, O_DSYNC, O_NOATIME,  O_NON‐
216       BLOCK,  and  O_SYNC.  Specifying any other flag in event_f_flags yields
217       the error EINVAL (but see BUGS).
218

RETURN VALUE

220       On success, fanotify_init() returns a new file descriptor.   On  error,
221       -1 is returned, and errno is set to indicate the error.
222

ERRORS

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

VERSIONS

243       fanotify_init()  was  introduced  in version 2.6.36 of the Linux kernel
244       and enabled in version 2.6.37.
245

CONFORMING TO

247       This system call is Linux-specific.
248

BUGS

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

SEE ALSO

262       fanotify_mark(2), fanotify(7)
263

COLOPHON

265       This  page  is  part of release 5.10 of the Linux man-pages project.  A
266       description of the project, information about reporting bugs,  and  the
267       latest     version     of     this    page,    can    be    found    at
268       https://www.kernel.org/doc/man-pages/.
269
270
271
272Linux                             2020-11-01                  FANOTIFY_INIT(2)
Impressum