]>
Commit | Line | Data |
---|---|---|
e9f14fa0 | 1 | \" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> |
3e6ebb33 | 2 | .\" |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
1d767b55 | 4 | .TH FANOTIFY_INIT 2 2021-03-22 "Linux" "Linux Programmer's Manual" |
3e6ebb33 HS |
5 | .SH NAME |
6 | fanotify_init \- create and initialize fanotify group | |
65a43077 AC |
7 | .SH LIBRARY |
8 | Standard C library | |
8fc3b2cf | 9 | .RI ( libc ", " \-lc ) |
3e6ebb33 | 10 | .SH SYNOPSIS |
c7db92b9 | 11 | .nf |
d2ac3dcf | 12 | .BR "#include <fcntl.h>" " /* Definition of " O_* " constants */" |
3e6ebb33 | 13 | .B #include <sys/fanotify.h> |
080522cb | 14 | .PP |
3e6ebb33 | 15 | .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); |
c7db92b9 | 16 | .fi |
3e6ebb33 HS |
17 | .SH DESCRIPTION |
18 | For an overview of the fanotify API, see | |
19 | .BR fanotify (7). | |
20 | .PP | |
21 | .BR fanotify_init () | |
22 | initializes a new fanotify group and returns a file descriptor for the event | |
23 | queue associated with the group. | |
24 | .PP | |
25 | The file descriptor is used in calls to | |
26 | .BR fanotify_mark (2) | |
3ded684c | 27 | to specify the files, directories, mounts, or filesystems for which fanotify |
0a4db6dc | 28 | events shall be created. |
3e6ebb33 HS |
29 | These events are received by reading from the file descriptor. |
30 | Some events are only informative, indicating that a file has been accessed. | |
72b14a93 MK |
31 | Other events can be used to determine whether |
32 | another application is permitted to access a file or directory. | |
3e6ebb33 HS |
33 | Permission to access filesystem objects is granted by writing to the file |
34 | descriptor. | |
35 | .PP | |
36 | Multiple programs may be using the fanotify interface at the same time to | |
37 | monitor the same files. | |
38 | .PP | |
39bab785 AG |
39 | The number of fanotify groups per user is limited. |
40 | See | |
41 | .BR fanotify (7) | |
42 | for details about this limit. | |
3e6ebb33 | 43 | .PP |
3e6ebb33 HS |
44 | The |
45 | .I flags | |
46 | argument contains a multi-bit field defining the notification class of the | |
1b24e2ee MK |
47 | listening application and further single bit fields specifying the behavior |
48 | of the file descriptor. | |
3e6ebb33 | 49 | .PP |
1b24e2ee MK |
50 | If multiple listeners for permission events exist, |
51 | the notification class is used to establish the sequence | |
52 | in which the listeners receive the events. | |
3e6ebb33 | 53 | .PP |
d58f4190 MK |
54 | Only one of the following notification classes may be specified in |
55 | .IR flags : | |
3e6ebb33 HS |
56 | .TP |
57 | .B FAN_CLASS_PRE_CONTENT | |
58 | This value allows the receipt of events notifying that a file has been | |
59 | accessed and events for permission decisions if a file may be accessed. | |
60 | It is intended for event listeners that need to access files before they | |
61 | contain their final data. | |
1b24e2ee MK |
62 | This notification class might be used by hierarchical storage managers, |
63 | for example. | |
69e6b644 MB |
64 | Use of this flag requires the |
65 | .B CAP_SYS_ADMIN | |
66 | capability. | |
3e6ebb33 HS |
67 | .TP |
68 | .B FAN_CLASS_CONTENT | |
69 | This value allows the receipt of events notifying that a file has been | |
70 | accessed and events for permission decisions if a file may be accessed. | |
1b24e2ee MK |
71 | It is intended for event listeners that need to access files when they |
72 | already contain their final content. | |
3e6ebb33 HS |
73 | This notification class might be used by malware detection programs, for |
74 | example. | |
69e6b644 MB |
75 | Use of this flag requires the |
76 | .B CAP_SYS_ADMIN | |
77 | capability. | |
3e6ebb33 HS |
78 | .TP |
79 | .B FAN_CLASS_NOTIF | |
80 | This is the default value. | |
81 | It does not need to be specified. | |
82 | This value only allows the receipt of events notifying that a file has been | |
83 | accessed. | |
84 | Permission decisions before the file is accessed are not possible. | |
85 | .PP | |
86 | Listeners with different notification classes will receive events in the | |
cd505a8a | 87 | order |
3e6ebb33 HS |
88 | .BR FAN_CLASS_PRE_CONTENT , |
89 | .BR FAN_CLASS_CONTENT , | |
90 | .BR FAN_CLASS_NOTIF . | |
8d605e55 MK |
91 | The order of notification for listeners in the same notification class |
92 | is undefined. | |
3e6ebb33 | 93 | .PP |
8d605e55 | 94 | The following bits can additionally be set in |
3e6ebb33 HS |
95 | .IR flags : |
96 | .TP | |
97 | .B FAN_CLOEXEC | |
8d605e55 | 98 | Set the close-on-exec flag |
3e6ebb33 HS |
99 | .RB ( FD_CLOEXEC ) |
100 | on the new file descriptor. | |
101 | See the description of the | |
102 | .B O_CLOEXEC | |
103 | flag in | |
104 | .BR open (2). | |
105 | .TP | |
106 | .B FAN_NONBLOCK | |
8d605e55 | 107 | Enable the nonblocking flag |
3e6ebb33 HS |
108 | .RB ( O_NONBLOCK ) |
109 | for the file descriptor. | |
110 | Reading from the file descriptor will not block. | |
f199b308 | 111 | Instead, if no data is available, |
3e6ebb33 | 112 | .BR read (2) |
a23d8efa | 113 | fails with the error |
f199b308 | 114 | .BR EAGAIN . |
3e6ebb33 HS |
115 | .TP |
116 | .B FAN_UNLIMITED_QUEUE | |
39bab785 AG |
117 | Remove the limit on the number of events in the event queue. |
118 | See | |
119 | .BR fanotify (7) | |
120 | for details about this limit. | |
8d605e55 | 121 | Use of this flag requires the |
3e6ebb33 HS |
122 | .B CAP_SYS_ADMIN |
123 | capability. | |
124 | .TP | |
125 | .B FAN_UNLIMITED_MARKS | |
39bab785 AG |
126 | Remove the limit on the number of fanotify marks per user. |
127 | See | |
128 | .BR fanotify (7) | |
129 | for details about this limit. | |
8d605e55 | 130 | Use of this flag requires the |
3e6ebb33 HS |
131 | .B CAP_SYS_ADMIN |
132 | capability. | |
ebfb6fee | 133 | .TP |
134 | .BR FAN_REPORT_TID " (since Linux 4.20)" | |
135 | .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29 | |
ce61c76f MK |
136 | Report thread ID (TID) instead of process ID (PID) |
137 | in the | |
138 | .I pid | |
139 | field of the | |
140 | .I "struct fanotify_event_metadata" | |
141 | supplied to | |
142 | .BR read (2) | |
143 | (see | |
144 | .BR fanotify (7)). | |
69e6b644 MB |
145 | Use of this flag requires the |
146 | .B CAP_SYS_ADMIN | |
147 | capability. | |
e5a800c1 | 148 | .TP |
f040d286 JK |
149 | .BR FAN_ENABLE_AUDIT " (since Linux 4.15)" |
150 | .\" commit de8cd83e91bc3ee212b3e6ec6e4283af9e4ab269 | |
151 | Enable generation of audit log records about access mediation performed by | |
d187835f MK |
152 | permission events. |
153 | The permission event response has to be marked with the | |
f040d286 | 154 | .B FAN_AUDIT |
d187835f | 155 | flag for an audit log record to be generated. |
69e6b644 MB |
156 | Use of this flag requires the |
157 | .B CAP_AUDIT_WRITE | |
158 | capability. | |
f040d286 | 159 | .TP |
e5a800c1 AG |
160 | .BR FAN_REPORT_FID " (since Linux 5.1)" |
161 | .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360 | |
162 | This value allows the receipt of events which contain additional information | |
163 | about the underlying filesystem object correlated to an event. | |
b216da61 | 164 | An additional record of type |
1ae6b2c7 | 165 | .B FAN_EVENT_INFO_TYPE_FID |
b216da61 AG |
166 | encapsulates the information about the object and is included alongside the |
167 | generic event metadata structure. | |
e5a800c1 AG |
168 | The file descriptor that is used to represent the object correlated to an |
169 | event is instead substituted with a file handle. | |
170 | It is intended for applications that may find the use of a file handle to | |
171 | identify an object more suitable than a file descriptor. | |
b216da61 AG |
172 | Additionally, it may be used for applications monitoring a directory or a |
173 | filesystem that are interested in the directory entry modification events | |
e5a800c1 | 174 | .BR FAN_CREATE , |
b216da61 AG |
175 | .BR FAN_DELETE , |
176 | and | |
e5a800c1 | 177 | .BR FAN_MOVE , |
b216da61 AG |
178 | or in events such as |
179 | .BR FAN_ATTRIB , | |
180 | .BR FAN_DELETE_SELF , | |
e5a800c1 | 181 | and |
b216da61 AG |
182 | .BR FAN_MOVE_SELF . |
183 | All the events above require an fanotify group that identifies filesystem | |
184 | objects by file handles. | |
185 | Note that for the directory entry modification events the reported file handle | |
186 | identifies the modified directory and not the created/deleted/moved child | |
187 | object. | |
e5a800c1 | 188 | The use of |
1ae6b2c7 | 189 | .B FAN_CLASS_CONTENT |
e5a800c1 | 190 | or |
1ae6b2c7 | 191 | .B FAN_CLASS_PRE_CONTENT |
e5a800c1 AG |
192 | is not permitted with this flag and will result in the error |
193 | .BR EINVAL . | |
194 | See | |
195 | .BR fanotify (7) | |
e9f14fa0 AG |
196 | for additional details. |
197 | .TP | |
198 | .BR FAN_REPORT_DIR_FID " (since Linux 5.9)" | |
1bfa8d6e | 199 | .\" commit 83b7a59896dd24015a34b7f00027f0ff3747972f |
e9f14fa0 AG |
200 | Events for fanotify groups initialized with this flag will contain |
201 | (see exceptions below) additional information about a directory object | |
202 | correlated to an event. | |
203 | An additional record of type | |
1ae6b2c7 | 204 | .B FAN_EVENT_INFO_TYPE_DFID |
e9f14fa0 AG |
205 | encapsulates the information about the directory object and is included |
206 | alongside the generic event metadata structure. | |
207 | For events that occur on a non-directory object, the additional structure | |
208 | includes a file handle that identifies the parent directory filesystem object. | |
209 | Note that there is no guarantee that the directory filesystem object will be | |
210 | found at the location described by the file handle information at the time | |
211 | the event is received. | |
212 | When combined with the flag | |
213 | .BR FAN_REPORT_FID , | |
214 | two records may be reported with events that occur on a non-directory object, | |
215 | one to identify the non-directory object itself and one to identify the parent | |
216 | directory object. | |
217 | Note that in some cases, a filesystem object does not have a parent, | |
218 | for example, when an event occurs on an unlinked but open file. | |
219 | In that case, with the | |
1ae6b2c7 | 220 | .B FAN_REPORT_FID |
e9f14fa0 AG |
221 | flag, the event will be reported with only one record to identify the |
222 | non-directory object itself, because there is no directory associated with | |
1a1e4638 MK |
223 | the event. |
224 | Without the | |
1ae6b2c7 | 225 | .B FAN_REPORT_FID |
e9f14fa0 AG |
226 | flag, no event will be reported. |
227 | See | |
228 | .BR fanotify (7) | |
229 | for additional details. | |
ea4f5778 AG |
230 | .TP |
231 | .BR FAN_REPORT_NAME " (since Linux 5.9)" | |
1bfa8d6e | 232 | .\" commit 929943b38daf817f2e6d303ea04401651fc3bc05 |
ea4f5778 AG |
233 | Events for fanotify groups initialized with this flag will contain additional |
234 | information about the name of the directory entry correlated to an event. | |
235 | This flag must be provided in conjunction with the flag | |
236 | .BR FAN_REPORT_DIR_FID . | |
237 | Providing this flag value without | |
1ae6b2c7 | 238 | .B FAN_REPORT_DIR_FID |
ea4f5778 AG |
239 | will result in the error |
240 | .BR EINVAL . | |
241 | This flag may be combined with the flag | |
242 | .BR FAN_REPORT_FID . | |
243 | An additional record of type | |
244 | .BR FAN_EVENT_INFO_TYPE_DFID_NAME , | |
0bda7ded | 245 | which encapsulates the information about the directory entry, is included |
ea4f5778 AG |
246 | alongside the generic event metadata structure and substitutes the additional |
247 | information record of type | |
248 | .BR FAN_EVENT_INFO_TYPE_DFID . | |
249 | The additional record includes a file handle that identifies a directory | |
250 | filesystem object followed by a name that identifies an entry in that | |
251 | directory. | |
252 | For the directory entry modification events | |
253 | .BR FAN_CREATE , | |
254 | .BR FAN_DELETE , | |
255 | and | |
256 | .BR FAN_MOVE , | |
257 | the reported name is that of the created/deleted/moved directory entry. | |
258 | For other events that occur on a directory object, the reported file handle | |
259 | is that of the directory object itself and the reported name is '.'. | |
260 | For other events that occur on a non-directory object, the reported file handle | |
261 | is that of the parent directory object and the reported name is the name of a | |
262 | directory entry where the object was located at the time of the event. | |
263 | The rationale behind this logic is that the reported directory file handle can | |
264 | be passed to | |
265 | .BR open_by_handle_at (2) | |
266 | to get an open directory file descriptor and that file descriptor along with | |
267 | the reported name can be used to call | |
268 | .BR fstatat (2). | |
269 | The same rule that applies to record type | |
1ae6b2c7 | 270 | .B FAN_EVENT_INFO_TYPE_DFID |
ea4f5778 | 271 | also applies to record type |
0bda7ded | 272 | .BR FAN_EVENT_INFO_TYPE_DFID_NAME : |
ea4f5778 AG |
273 | if a non-directory object has no parent, either the event will not be reported |
274 | or it will be reported without the directory entry information. | |
275 | Note that there is no guarantee that the filesystem object will be found at the | |
276 | location described by the directory entry information at the time the event is | |
277 | received. | |
278 | See | |
279 | .BR fanotify (7) | |
280 | for additional details. | |
281 | .TP | |
282 | .B FAN_REPORT_DFID_NAME | |
283 | This is a synonym for | |
284 | .RB ( FAN_REPORT_DIR_FID | FAN_REPORT_NAME ). | |
3e6ebb33 | 285 | .PP |
8d605e55 | 286 | The |
3e6ebb33 | 287 | .I event_f_flags |
8d605e55 MK |
288 | argument |
289 | defines the file status flags that will be set on the open file descriptions | |
290 | that are created for fanotify events. | |
291 | For details of these flags, see the description of the | |
3e6ebb33 | 292 | .I flags |
8d605e55 MK |
293 | values in |
294 | .BR open (2). | |
1caffed4 | 295 | .I event_f_flags |
be5c465e | 296 | includes a multi-bit field for the access mode. |
1caffed4 | 297 | This field can take the following values: |
3e6ebb33 HS |
298 | .TP |
299 | .B O_RDONLY | |
300 | This value allows only read access. | |
301 | .TP | |
302 | .B O_WRONLY | |
303 | This value allows only write access. | |
304 | .TP | |
305 | .B O_RDWR | |
306 | This value allows read and write access. | |
1caffed4 HS |
307 | .PP |
308 | Additional bits can be set in | |
309 | .IR event_f_flags . | |
310 | The most useful values are: | |
3e6ebb33 HS |
311 | .TP |
312 | .B O_LARGEFILE | |
c4b7e5ac | 313 | Enable support for files exceeding 2\ GB. |
3e6ebb33 HS |
314 | Failing to set this flag will result in an |
315 | .B EOVERFLOW | |
1b24e2ee MK |
316 | error when trying to open a large file which is monitored by |
317 | an fanotify group on a 32-bit system. | |
1caffed4 | 318 | .TP |
d38a09fc MK |
319 | .BR O_CLOEXEC " (since Linux 3.18)" |
320 | .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 | |
1caffed4 | 321 | Enable the close-on-exec flag for the file descriptor. |
be5c465e MK |
322 | See the description of the |
323 | .B O_CLOEXEC | |
324 | flag in | |
325 | .BR open (2) | |
326 | for reasons why this may be useful. | |
1caffed4 HS |
327 | .PP |
328 | The following are also allowable: | |
329 | .BR O_APPEND , | |
330 | .BR O_DSYNC , | |
331 | .BR O_NOATIME , | |
332 | .BR O_NONBLOCK , | |
333 | and | |
334 | .BR O_SYNC . | |
be5c465e MK |
335 | Specifying any other flag in |
336 | .I event_f_flags | |
337 | yields the error | |
1caffed4 HS |
338 | .B EINVAL |
339 | (but see BUGS). | |
3e6ebb33 HS |
340 | .SH RETURN VALUE |
341 | On success, | |
342 | .BR fanotify_init () | |
343 | returns a new file descriptor. | |
ddfa9db7 | 344 | On error, \-1 is returned, and |
3e6ebb33 HS |
345 | .I errno |
346 | is set to indicate the error. | |
347 | .SH ERRORS | |
348 | .TP | |
349 | .B EINVAL | |
350 | An invalid value was passed in | |
1caffed4 HS |
351 | .I flags |
352 | or | |
353 | .IR event_f_flags . | |
3e6ebb33 | 354 | .B FAN_ALL_INIT_FLAGS |
0a4db6dc MB |
355 | (deprecated since Linux kernel version 4.20) |
356 | .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4 | |
1caffed4 HS |
357 | defines all allowable bits for |
358 | .IR flags . | |
3e6ebb33 HS |
359 | .TP |
360 | .B EMFILE | |
39bab785 AG |
361 | The number of fanotify groups for this user exceeds the limit. |
362 | See | |
363 | .BR fanotify (7) | |
364 | for details about this limit. | |
3e6ebb33 | 365 | .TP |
356a2957 | 366 | .B EMFILE |
71d597e9 MK |
367 | The per-process limit on the number of open file descriptors has been reached. |
368 | .TP | |
3e6ebb33 HS |
369 | .B ENOMEM |
370 | The allocation of memory for the notification group failed. | |
371 | .TP | |
a8972eed HS |
372 | .B ENOSYS |
373 | This kernel does not implement | |
374 | .BR fanotify_init (). | |
8d605e55 MK |
375 | The fanotify API is available only if the kernel was configured with |
376 | .BR CONFIG_FANOTIFY . | |
a8972eed | 377 | .TP |
3e6ebb33 | 378 | .B EPERM |
69e6b644 | 379 | The operation is not permitted because the caller lacks a required capability. |
3e6ebb33 HS |
380 | .SH VERSIONS |
381 | .BR fanotify_init () | |
382 | was introduced in version 2.6.36 of the Linux kernel and enabled in version | |
383 | 2.6.37. | |
69e6b644 MB |
384 | .PP |
385 | Prior to Linux 5.13, | |
386 | .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7 | |
387 | calling | |
388 | .BR fanotify_init () | |
389 | required the | |
390 | .B CAP_SYS_ADMIN | |
391 | capability. | |
392 | Since Linux 5.13, | |
393 | .\" commit 7cea2a3c505e87a9d6afc78be4a7f7be636a73a7 | |
394 | users may call | |
395 | .BR fanotify_init () | |
396 | without the | |
397 | .B CAP_SYS_ADMIN | |
398 | capability to create and intialize an fanotify group with limited functionality. | |
399 | .TP | |
400 | The limitations imposed on an event listener created by a user without the | |
401 | .B CAP_SYS_ADMIN | |
402 | capability are as follows: | |
403 | .RS | |
404 | .IP * 3 | |
405 | The user cannot request for an unlimited event queue by using | |
406 | .BR FAN_UNLIMITED_QUEUE . | |
407 | .IP * 3 | |
408 | The user cannot request for an unlimited number of marks by using | |
409 | .BR FAN_UNLIMITED_MARKS . | |
410 | .IP * 3 | |
411 | The user cannot request to use either notification classes | |
9594c505 | 412 | .B FAN_CLASS_CONTENT |
69e6b644 MB |
413 | or |
414 | .BR FAN_CLASS_PRE_CONTENT . | |
415 | This means that user cannot request permission events. | |
416 | .IP * 3 | |
417 | The user is required to create a group that identifies filesystem objects by | |
418 | file handles, for example, by providing the | |
9594c505 | 419 | .B FAN_REPORT_FID |
69e6b644 MB |
420 | flag. |
421 | .IP * 3 | |
422 | The user is limited to only mark inodes. | |
423 | The ability to mark a mount or filesystem via | |
9594c505 | 424 | .BR fanotify_mark () |
69e6b644 | 425 | through the use of |
9594c505 | 426 | .B FAN_MARK_MOUNT |
69e6b644 | 427 | or |
9594c505 | 428 | .B FAN_MARK_FILESYSTEM |
69e6b644 MB |
429 | is not permitted. |
430 | .IP * 3 | |
431 | The event object in the event queue is limited in terms of the information | |
432 | that is made available to the unprivileged user. | |
433 | A user will also not receive the pid that generated the event, unless the | |
434 | listening process itself generated the event. | |
435 | .RE | |
d282bb24 | 436 | .SH CONFORMING TO |
3e6ebb33 | 437 | This system call is Linux-specific. |
6448be7e | 438 | .SH BUGS |
692b4bcc | 439 | The following bug was present in Linux kernels before version 3.18: |
0d69c093 | 440 | .IP * 3 |
692b4bcc | 441 | .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 |
51d266b7 | 442 | The |
0d69c093 | 443 | .B O_CLOEXEC |
51d266b7 MK |
444 | is ignored when passed in |
445 | .IR event_f_flags . | |
0d69c093 | 446 | .PP |
f479e19c | 447 | The following bug was present in Linux kernels before version 3.14: |
6448be7e | 448 | .IP * 3 |
f479e19c | 449 | .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 |
20abed53 | 450 | The |
6448be7e | 451 | .I event_f_flags |
491bc783 | 452 | argument is not checked for invalid flags. |
20abed53 MK |
453 | Flags that are intended only for internal use, |
454 | such as | |
6448be7e | 455 | .BR FMODE_EXEC , |
20abed53 MK |
456 | can be set, and will consequently be set for the file descriptors |
457 | returned when reading from the fanotify file descriptor. | |
d282bb24 | 458 | .SH SEE ALSO |
3e6ebb33 HS |
459 | .BR fanotify_mark (2), |
460 | .BR fanotify (7) |