]>
Commit | Line | Data |
---|---|---|
c200b422 HS |
1 | .\" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> |
2 | .\" | |
3 | .\" %%%LICENSE_START(VERBATIM) | |
4 | .\" Permission is granted to make and distribute verbatim copies of this | |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of | |
9 | .\" this manual under the conditions for verbatim copying, provided that | |
10 | .\" the entire resulting derived work is distributed under the terms of | |
11 | .\" a permission notice identical to this one. | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume. | |
15 | .\" no responsibility for errors or omissions, or for damages resulting. | |
16 | .\" from the use of the information contained herein. The author(s) may. | |
17 | .\" not have taken the same level of care in the production of this. | |
18 | .\" manual, which is licensed free of charge, as they might when working. | |
19 | .\" professionally. | |
20 | .\" | |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
23 | .\" %%%LICENSE_END | |
63121bd4 | 24 | .TH FANOTIFY_MARK 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
c200b422 HS |
25 | .SH NAME |
26 | fanotify_mark \- add, remove, or modify an fanotify mark on a filesystem | |
27 | object | |
28 | .SH SYNOPSIS | |
29 | .nf | |
30 | .B #include <sys/fanotify.h> | |
68e4db0a | 31 | .PP |
c200b422 | 32 | .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , |
5ff1ff14 MK |
33 | .BI " uint64_t " mask ", int " dirfd \ |
34 | ", const char *" pathname ); | |
c200b422 HS |
35 | .fi |
36 | .SH DESCRIPTION | |
37 | For an overview of the fanotify API, see | |
38 | .BR fanotify (7). | |
39 | .PP | |
bf7bc8b8 | 40 | .BR fanotify_mark () |
b6551738 | 41 | adds, removes, or modifies an fanotify mark on a filesystem object. |
1b24e2ee MK |
42 | The caller must have read permission on the filesystem object that |
43 | is to be marked. | |
c200b422 HS |
44 | .PP |
45 | The | |
46 | .I fanotify_fd | |
963a1568 | 47 | argument is a file descriptor returned by |
c200b422 HS |
48 | .BR fanotify_init (2). |
49 | .PP | |
50 | .I flags | |
51 | is a bit mask describing the modification to perform. | |
52 | It must include exactly one of the following values: | |
53 | .TP | |
54 | .B FAN_MARK_ADD | |
55 | The events in | |
56 | .I mask | |
57 | will be added to the mark mask (or to the ignore mask). | |
58 | .I mask | |
59 | must be nonempty or the error | |
60 | .B EINVAL | |
61 | will occur. | |
62 | .TP | |
63 | .B FAN_MARK_REMOVE | |
64 | The events in argument | |
65 | .I mask | |
66 | will be removed from the mark mask (or from the ignore mask). | |
67 | .I mask | |
68 | must be nonempty or the error | |
69 | .B EINVAL | |
70 | will occur. | |
71 | .TP | |
72 | .B FAN_MARK_FLUSH | |
953d1e07 | 73 | Remove either all marks for filesystems, all marks for mounts, or all |
b2f8214d | 74 | marks for directories and files from the fanotify group. |
c200b422 | 75 | If |
8c659c48 | 76 | .I flags |
c200b422 HS |
77 | contains |
78 | .BR FAN_MARK_MOUNT , | |
79 | all marks for mounts are removed from the group. | |
b2f8214d AG |
80 | If |
81 | .I flags | |
82 | contains | |
83 | .BR FAN_MARK_FILESYSTEM , | |
84 | all marks for filesystems are removed from the group. | |
c200b422 | 85 | Otherwise, all marks for directories and files are removed. |
953d1e07 | 86 | No flag other than and at most one of the flags |
c200b422 | 87 | .B FAN_MARK_MOUNT |
b2f8214d AG |
88 | or |
89 | .B FAN_MARK_FILESYSTEM | |
c200b422 HS |
90 | can be used in conjunction with |
91 | .BR FAN_MARK_FLUSH . | |
92 | .I mask | |
93 | is ignored. | |
94 | .PP | |
1b24e2ee MK |
95 | If none of the values above is specified, or more than one is specified, |
96 | the call fails with the error | |
c200b422 HS |
97 | .BR EINVAL . |
98 | .PP | |
99 | In addition, | |
d4a12c12 MK |
100 | zero or more of the following values may be ORed into |
101 | .IR flags : | |
c200b422 HS |
102 | .TP |
103 | .B FAN_MARK_DONT_FOLLOW | |
104 | If | |
105 | .I pathname | |
106 | is a symbolic link, mark the link itself, rather than the file to which it | |
107 | refers. | |
108 | (By default, | |
109 | .BR fanotify_mark () | |
110 | dereferences | |
111 | .I pathname | |
112 | if it is a symbolic link.) | |
113 | .TP | |
114 | .B FAN_MARK_ONLYDIR | |
115 | If the filesystem object to be marked is not a directory, the error | |
116 | .B ENOTDIR | |
117 | shall be raised. | |
118 | .TP | |
119 | .B FAN_MARK_MOUNT | |
c82b4ae4 MK |
120 | Mark the mount point specified by |
121 | .IR pathname . | |
122 | If | |
123 | .I pathname | |
124 | is not itself a mount point, the mount point containing | |
c200b422 | 125 | .I pathname |
c200b422 HS |
126 | will be marked. |
127 | All directories, subdirectories, and the contained files of the mount point | |
128 | will be monitored. | |
0a4db6dc MB |
129 | This value cannot be used if the |
130 | .I fanotify_fd | |
131 | file descriptor has been initialized with the flag | |
132 | .BR FAN_REPORT_FID | |
133 | or if any of the new directory modification events are provided as a | |
134 | .IR mask . | |
135 | Attempting to do so will result in the error | |
136 | .B EINVAL | |
137 | being returned. | |
c200b422 | 138 | .TP |
b2f8214d AG |
139 | .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)" |
140 | .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2 | |
141 | Mark the filesystem specified by | |
142 | .IR pathname . | |
143 | The filesystem containing | |
144 | .I pathname | |
145 | will be marked. | |
146 | All the contained files and directories of the filesystem from any mount | |
147 | point will be monitored. | |
148 | .TP | |
c200b422 HS |
149 | .B FAN_MARK_IGNORED_MASK |
150 | The events in | |
151 | .I mask | |
152 | shall be added to or removed from the ignore mask. | |
153 | .TP | |
154 | .B FAN_MARK_IGNORED_SURV_MODIFY | |
155 | The ignore mask shall survive modify events. | |
1b24e2ee MK |
156 | If this flag is not set, |
157 | the ignore mask is cleared when a modify event occurs | |
c200b422 HS |
158 | for the ignored file or directory. |
159 | .PP | |
160 | .I mask | |
d4a12c12 | 161 | defines which events shall be listened for (or which shall be ignored). |
c200b422 HS |
162 | It is a bit mask composed of the following values: |
163 | .TP | |
164 | .B FAN_ACCESS | |
165 | Create an event when a file or directory (but see BUGS) is accessed (read). | |
166 | .TP | |
167 | .B FAN_MODIFY | |
168 | Create an event when a file is modified (write). | |
169 | .TP | |
170 | .B FAN_CLOSE_WRITE | |
171 | Create an event when a writable file is closed. | |
172 | .TP | |
173 | .B FAN_CLOSE_NOWRITE | |
174 | Create an event when a read-only file or directory is closed. | |
175 | .TP | |
176 | .B FAN_OPEN | |
177 | Create an event when a file or directory is opened. | |
178 | .TP | |
bbd7edea | 179 | .BR FAN_OPEN_EXEC " (since Linux 5.0)" |
10fa1da2 | 180 | .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa |
fc37d2f1 | 181 | Create an event when a file is opened with the intent to be executed. |
fd1eb8a7 | 182 | See NOTES for additional details. |
fc37d2f1 | 183 | .TP |
10fa1da2 JW |
184 | .BR FAN_ATTRIB " (since Linux 5.1)" |
185 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
186 | Create an event when the metadata for a file or directory has changed. |
187 | .TP | |
10fa1da2 JW |
188 | .BR FAN_CREATE " (since Linux 5.1)" |
189 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
190 | Create an event when a file or directory has been created in a marked |
191 | parent directory. | |
192 | .TP | |
10fa1da2 JW |
193 | .BR FAN_DELETE " (since Linux 5.1)" |
194 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
195 | Create an event when a file or directory has been deleted in a marked |
196 | parent directory. | |
197 | .TP | |
10fa1da2 JW |
198 | .BR FAN_DELETE_SELF " (since Linux 5.1)" |
199 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
200 | Create an event when a marked file or directory itself is deleted. |
201 | .TP | |
10fa1da2 JW |
202 | .BR FAN_MOVED_FROM " (since Linux 5.1)" |
203 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
204 | Create an event when a file or directory has been moved from a marked |
205 | parent directory. | |
206 | .TP | |
10fa1da2 JW |
207 | .BR FAN_MOVED_TO " (since Linux 5.1)" |
208 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
0a4db6dc MB |
209 | Create an event when a file or directory has been moved to a marked parent |
210 | directory. | |
211 | .TP | |
b5e1b804 JW |
212 | .BR FAN_MOVE_SELF " (since Linux 5.1)" |
213 | .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2 | |
214 | Create an event when a marked file or directory itself has been moved. | |
215 | .TP | |
5d730f86 HS |
216 | .B FAN_Q_OVERFLOW |
217 | Create an event when an overflow of the event queue occurs. | |
218 | The size of the event queue is limited to 16384 entries if | |
219 | .B FAN_UNLIMITED_QUEUE | |
220 | is not set in | |
221 | .BR fanotify_init (2). | |
222 | .TP | |
c200b422 HS |
223 | .B FAN_OPEN_PERM |
224 | Create an event when a permission to open a file or directory is requested. | |
225 | An fanotify file descriptor created with | |
226 | .B FAN_CLASS_PRE_CONTENT | |
227 | or | |
228 | .B FAN_CLASS_CONTENT | |
229 | is required. | |
230 | .TP | |
fd1eb8a7 | 231 | .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)" |
10fa1da2 | 232 | .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9 |
fc37d2f1 MB |
233 | Create an event when a permission to open a file for execution is |
234 | requested. | |
235 | An fanotify file descriptor created with | |
236 | .B FAN_CLASS_PRE_CONTENT | |
237 | or | |
238 | .B FAN_CLASS_CONTENT | |
239 | is required. | |
fd1eb8a7 | 240 | See NOTES for additional details. |
fc37d2f1 | 241 | .TP |
c200b422 HS |
242 | .B FAN_ACCESS_PERM |
243 | Create an event when a permission to read a file or directory is requested. | |
244 | An fanotify file descriptor created with | |
245 | .B FAN_CLASS_PRE_CONTENT | |
246 | or | |
247 | .B FAN_CLASS_CONTENT | |
248 | is required. | |
249 | .TP | |
250 | .B FAN_ONDIR | |
817c8240 | 251 | Create events for directories\(emfor example, when |
834e5597 MK |
252 | .BR opendir (3), |
253 | .BR readdir (3) | |
c200b422 | 254 | (but see BUGS), and |
834e5597 | 255 | .BR closedir (3) |
c200b422 | 256 | are called. |
57f87a2c | 257 | Without this flag, only events for files are created. |
0a4db6dc MB |
258 | The |
259 | .BR FAN_ONDIR | |
260 | flag is reported in an event mask only if the | |
261 | .I fanotify_fd | |
262 | file descriptor has been initialized with the flag | |
263 | .BR FAN_REPORT_FID . | |
264 | In the context of directory entry events, such as | |
265 | .BR FAN_CREATE , | |
266 | .BR FAN_DELETE , | |
817c8240 | 267 | .BR FAN_MOVED_FROM , |
0a4db6dc MB |
268 | and |
269 | .BR FAN_MOVED_TO | |
270 | for example, specifying the flag | |
271 | .BR FAN_ONDIR | |
272 | is required in order to create events when subdirectory entries are | |
817c8240 MK |
273 | modified (i.e., |
274 | .BR mkdir (2)/ | |
275 | .BR rmdir (2)). | |
276 | Subdirectory entry modification events will never be merged with | |
277 | nonsubdirectory entry modification events. | |
0a4db6dc MB |
278 | This flag is never reported individually within an event and is always |
279 | supplied in conjunction with another event type. | |
c200b422 HS |
280 | .TP |
281 | .B FAN_EVENT_ON_CHILD | |
282 | Events for the immediate children of marked directories shall be created. | |
b2f8214d | 283 | The flag has no effect when marking mounts and filesystems. |
c200b422 HS |
284 | Note that events are not generated for children of the subdirectories |
285 | of marked directories. | |
286 | To monitor complete directory trees it is necessary to mark the relevant | |
287 | mount. | |
288 | .PP | |
0a4db6dc | 289 | The following composed values are defined: |
c200b422 HS |
290 | .TP |
291 | .B FAN_CLOSE | |
292 | A file is closed | |
293 | .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ). | |
0a4db6dc MB |
294 | .TP |
295 | .B FAN_MOVE | |
296 | A file or directory has been moved | |
297 | .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ). | |
c200b422 HS |
298 | .PP |
299 | The filesystem object to be marked is determined by the file descriptor | |
300 | .I dirfd | |
301 | and the pathname specified in | |
302 | .IR pathname : | |
303 | .IP * 3 | |
304 | If | |
305 | .I pathname | |
306 | is NULL, | |
307 | .I dirfd | |
308 | defines the filesystem object to be marked. | |
309 | .IP * | |
310 | If | |
311 | .I pathname | |
312 | is NULL, and | |
313 | .I dirfd | |
314 | takes the special value | |
315 | .BR AT_FDCWD , | |
316 | the current working directory is to be marked. | |
317 | .IP * | |
318 | If | |
319 | .I pathname | |
320 | is absolute, it defines the filesystem object to be marked, and | |
321 | .I dirfd | |
322 | is ignored. | |
323 | .IP * | |
324 | If | |
325 | .I pathname | |
326 | is relative, and | |
327 | .I dirfd | |
328 | does not have the value | |
329 | .BR AT_FDCWD , | |
330 | then the filesystem object to be marked is determined by interpreting | |
331 | .I pathname | |
332 | relative the directory referred to by | |
333 | .IR dirfd . | |
334 | .IP * | |
335 | If | |
336 | .I pathname | |
337 | is relative, and | |
338 | .I dirfd | |
339 | has the value | |
9fdb563e | 340 | .BR AT_FDCWD , |
c200b422 HS |
341 | then the filesystem object to be marked is determined by interpreting |
342 | .I pathname | |
343 | relative the current working directory. | |
344 | .SH RETURN VALUE | |
345 | On success, | |
346 | .BR fanotify_mark () | |
347 | returns 0. | |
b3470de1 | 348 | On error, \-1 is returned, and |
c200b422 HS |
349 | .I errno |
350 | is set to indicate the error. | |
351 | .SH ERRORS | |
352 | .TP | |
353 | .B EBADF | |
354 | An invalid file descriptor was passed in | |
355 | .IR fanotify_fd . | |
356 | .TP | |
357 | .B EINVAL | |
358 | An invalid value was passed in | |
359 | .IR flags | |
360 | or | |
361 | .IR mask , | |
362 | or | |
363 | .I fanotify_fd | |
364 | was not an fanotify file descriptor. | |
365 | .TP | |
366 | .B EINVAL | |
367 | The fanotify file descriptor was opened with | |
368 | .B FAN_CLASS_NOTIF | |
0a4db6dc MB |
369 | or |
370 | .B FAN_REPORT_FID | |
c200b422 HS |
371 | and mask contains a flag for permission events |
372 | .RB ( FAN_OPEN_PERM | |
373 | or | |
374 | .BR FAN_ACCESS_PERM ). | |
375 | .TP | |
49a2a105 MK |
376 | .B ENODEV |
377 | The filesystem object indicated by | |
378 | .I pathname | |
379 | is not associated with a filesystem that supports | |
380 | .I fsid | |
381 | (e.g., | |
382 | .BR tmpfs (5)). | |
383 | This error can be returned only when an fanotify file descriptor returned | |
384 | by | |
385 | .BR fanotify_init (2) | |
386 | has been created with | |
387 | .BR FAN_REPORT_FID . | |
388 | .TP | |
c200b422 HS |
389 | .B ENOENT |
390 | The filesystem object indicated by | |
391 | .IR dirfd | |
392 | and | |
393 | .IR pathname | |
394 | does not exist. | |
1b24e2ee MK |
395 | This error also occurs when trying to remove a mark from an object |
396 | which is not marked. | |
c200b422 HS |
397 | .TP |
398 | .B ENOMEM | |
399 | The necessary memory could not be allocated. | |
400 | .TP | |
401 | .B ENOSPC | |
d4a12c12 | 402 | The number of marks exceeds the limit of 8192 and the |
c200b422 | 403 | .B FAN_UNLIMITED_MARKS |
d4a12c12 | 404 | flag was not specified when the fanotify file descriptor was created with |
c200b422 HS |
405 | .BR fanotify_init (2). |
406 | .TP | |
89ba4cc2 MK |
407 | .B ENOSYS |
408 | This kernel does not implement | |
ffb30e75 | 409 | .BR fanotify_mark (). |
d4a12c12 MK |
410 | The fanotify API is available only if the kernel was configured with |
411 | .BR CONFIG_FANOTIFY . | |
89ba4cc2 | 412 | .TP |
c200b422 HS |
413 | .B ENOTDIR |
414 | .I flags | |
415 | contains | |
416 | .BR FAN_MARK_ONLYDIR , | |
417 | and | |
418 | .I dirfd | |
419 | and | |
420 | .I pathname | |
421 | do not specify a directory. | |
0a4db6dc | 422 | .TP |
49a2a105 MK |
423 | .B EOPNOTSUPP |
424 | The object indicated by | |
0a4db6dc | 425 | .I pathname |
49a2a105 MK |
426 | is associated with a filesystem that does not support the encoding of file |
427 | handles. | |
817c8240 | 428 | This error can be returned only when an fanotify file descriptor returned |
0a4db6dc MB |
429 | by |
430 | .BR fanotify_init (2) | |
431 | has been created with | |
432 | .BR FAN_REPORT_FID . | |
433 | .TP | |
49a2a105 | 434 | .B EXDEV |
eae836e0 | 435 | The filesystem object indicated by |
0a4db6dc | 436 | .I pathname |
49a2a105 MK |
437 | resides within a filesystem subvolume (e.g., |
438 | .BR btrfs (5)) | |
439 | which uses a different | |
0a4db6dc | 440 | .I fsid |
49a2a105 | 441 | than its root superblock. |
817c8240 | 442 | This error can be returned only when an fanotify file descriptor returned |
0a4db6dc MB |
443 | by |
444 | .BR fanotify_init (2) | |
445 | has been created with | |
446 | .BR FAN_REPORT_FID . | |
c200b422 HS |
447 | .SH VERSIONS |
448 | .BR fanotify_mark () | |
449 | was introduced in version 2.6.36 of the Linux kernel and enabled in version | |
450 | 2.6.37. | |
451 | .SH CONFORMING TO | |
452 | This system call is Linux-specific. | |
fc37d2f1 | 453 | .SH NOTES |
fd1eb8a7 | 454 | .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM |
fc37d2f1 MB |
455 | When using either |
456 | .B FAN_OPEN_EXEC | |
457 | or | |
458 | .B FAN_OPEN_EXEC_PERM | |
459 | within the | |
460 | .IR mask , | |
fd1eb8a7 | 461 | events of these types will be returned only when the direct execution of a |
fc37d2f1 | 462 | program occurs. |
fd1eb8a7 MK |
463 | More specifically, this means that events of these types will be generated |
464 | for files that are opened using | |
465 | .BR execve (2), | |
466 | .BR execveat (2), | |
fc37d2f1 | 467 | or |
fd1eb8a7 | 468 | .BR uselib (2). |
fc37d2f1 | 469 | Events of these types will not be raised in the situation where an |
9b89b9dd | 470 | interpreter is passed (or reads) a file for interpretation. |
fc37d2f1 MB |
471 | .PP |
472 | Additionally, if a mark has also been placed on the Linux dynamic | |
fd1eb8a7 MK |
473 | linker, a user should also expect to receive an event for it when |
474 | an ELF object has been successfully opened using | |
475 | .BR execve (2) | |
fc37d2f1 | 476 | or |
fd1eb8a7 | 477 | .BR execveat (2). |
fc37d2f1 MB |
478 | .PP |
479 | For example, if the following ELF binary were to be invoked and a | |
480 | .BR FAN_OPEN_EXEC | |
481 | mark has been placed on /: | |
482 | .PP | |
fd1eb8a7 | 483 | .in +4n |
fc37d2f1 | 484 | .EX |
fd1eb8a7 | 485 | $ /bin/echo foo |
fc37d2f1 | 486 | .EE |
fd1eb8a7 | 487 | .in |
fc37d2f1 | 488 | .PP |
fd1eb8a7 | 489 | The listening application in this case would receive |
fc37d2f1 | 490 | .BR FAN_OPEN_EXEC |
fd1eb8a7 | 491 | events for both the ELF binary and interpreter, respectively: |
fc37d2f1 | 492 | .PP |
fd1eb8a7 | 493 | .in +4n |
fc37d2f1 | 494 | .EX |
fd1eb8a7 MK |
495 | /bin/echo |
496 | /lib64/ld-linux-x86-64.so.2 | |
fc37d2f1 | 497 | .EE |
fd1eb8a7 | 498 | .in |
c200b422 | 499 | .SH BUGS |
e5209a5a | 500 | The following bugs were present in Linux kernels before version 3.16: |
c200b422 | 501 | .IP * 3 |
e5209a5a | 502 | .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563 |
c200b422 HS |
503 | If |
504 | .I flags | |
505 | contains | |
506 | .BR FAN_MARK_FLUSH , | |
2335e402 | 507 | .I dirfd |
c200b422 HS |
508 | and |
509 | .I pathname | |
4ac7d313 | 510 | must specify a valid filesystem object, even though this object is not used. |
c200b422 | 511 | .IP * |
e5209a5a | 512 | .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b |
c200b422 | 513 | .BR readdir (2) |
97ef170a | 514 | does not generate a |
c200b422 HS |
515 | .B FAN_ACCESS |
516 | event. | |
517 | .IP * | |
e5209a5a | 518 | .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406 |
c200b422 | 519 | If |
bf7bc8b8 | 520 | .BR fanotify_mark () |
c200b422 | 521 | is called with |
f2f50fed | 522 | .BR FAN_MARK_FLUSH , |
c200b422 HS |
523 | .I flags |
524 | is not checked for invalid values. | |
525 | .SH SEE ALSO | |
526 | .BR fanotify_init (2), | |
527 | .BR fanotify (7) |