| blob | 1e997372e43092fb744930f50da5f144cdd2c33d |
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
24 .TH FANOTIFY_MARK 2 2021-03-22 "Linux" "Linux Programmer's Manual"
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>
31 .PP
32 .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags ,
33 .BI " uint64_t " mask ", int " dirfd \
34 ", const char *" pathname );
35 .fi
36 .SH DESCRIPTION
37 For an overview of the fanotify API, see
38 .BR fanotify (7).
39 .PP
40 .BR fanotify_mark ()
41 adds, removes, or modifies an fanotify mark on a filesystem object.
42 The caller must have read permission on the filesystem object that
43 is to be marked.
44 .PP
45 The
46 .I fanotify_fd
47 argument is a file descriptor returned by
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
73 Remove either all marks for filesystems, all marks for mounts, or all
74 marks for directories and files from the fanotify group.
75 If
76 .I flags
77 contains
78 .BR FAN_MARK_MOUNT ,
79 all marks for mounts are removed from the group.
80 If
81 .I flags
82 contains
83 .BR FAN_MARK_FILESYSTEM ,
84 all marks for filesystems are removed from the group.
85 Otherwise, all marks for directories and files are removed.
86 No flag other than and at most one of the flags
87 .B FAN_MARK_MOUNT
88 or
89 .B FAN_MARK_FILESYSTEM
90 can be used in conjunction with
91 .BR FAN_MARK_FLUSH .
92 .I mask
93 is ignored.
94 .PP
95 If none of the values above is specified, or more than one is specified,
96 the call fails with the error
97 .BR EINVAL .
98 .PP
99 In addition,
100 zero or more of the following values may be ORed into
101 .IR flags :
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
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
125 .I pathname
126 will be marked.
127 All directories, subdirectories, and the contained files of the mount point
128 will be monitored.
129 The events which require that filesystem objects are identified by file handles,
130 such as
131 .BR FAN_CREATE ,
132 .BR FAN_ATTRIB ,
133 .BR FAN_MOVE ,
134 and
135 .BR FAN_DELETE_SELF ,
136 cannot be provided as a
137 .IR mask
138 when
139 .I flags
140 contains
141 .BR FAN_MARK_MOUNT .
142 Attempting to do so will result in the error
143 .B EINVAL
144 being returned.
145 .TP
146 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
147 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
148 Mark the filesystem specified by
149 .IR pathname .
150 The filesystem containing
151 .I pathname
152 will be marked.
153 All the contained files and directories of the filesystem from any mount
154 point will be monitored.
155 .TP
156 .B FAN_MARK_IGNORED_MASK
157 The events in
158 .I mask
159 shall be added to or removed from the ignore mask.
160 .TP
161 .B FAN_MARK_IGNORED_SURV_MODIFY
162 The ignore mask shall survive modify events.
163 If this flag is not set,
164 the ignore mask is cleared when a modify event occurs
165 for the ignored file or directory.
166 .PP
167 .I mask
168 defines which events shall be listened for (or which shall be ignored).
169 It is a bit mask composed of the following values:
170 .TP
171 .B FAN_ACCESS
172 Create an event when a file or directory (but see BUGS) is accessed (read).
173 .TP
174 .B FAN_MODIFY
175 Create an event when a file is modified (write).
176 .TP
177 .B FAN_CLOSE_WRITE
178 Create an event when a writable file is closed.
179 .TP
180 .B FAN_CLOSE_NOWRITE
181 Create an event when a read-only file or directory is closed.
182 .TP
183 .B FAN_OPEN
184 Create an event when a file or directory is opened.
185 .TP
186 .BR FAN_OPEN_EXEC " (since Linux 5.0)"
187 .\" commit 9b076f1c0f4869b838a1b7aa0edb5664d47ec8aa
188 Create an event when a file is opened with the intent to be executed.
189 See NOTES for additional details.
190 .TP
191 .BR FAN_ATTRIB " (since Linux 5.1)"
192 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
193 Create an event when the metadata for a file or directory has changed.
194 An fanotify group that identifies filesystem objects by file handles
195 is required.
196 .TP
197 .BR FAN_CREATE " (since Linux 5.1)"
198 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
199 Create an event when a file or directory has been created in a marked
200 parent directory.
201 An fanotify group that identifies filesystem objects by file handles
202 is required.
203 .TP
204 .BR FAN_DELETE " (since Linux 5.1)"
205 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
206 Create an event when a file or directory has been deleted in a marked
207 parent directory.
208 An fanotify group that identifies filesystem objects by file handles
209 is required.
210 .TP
211 .BR FAN_DELETE_SELF " (since Linux 5.1)"
212 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
213 Create an event when a marked file or directory itself is deleted.
214 An fanotify group that identifies filesystem objects by file handles
215 is required.
216 .TP
217 .BR FAN_MOVED_FROM " (since Linux 5.1)"
218 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
219 Create an event when a file or directory has been moved from a marked
220 parent directory.
221 An fanotify group that identifies filesystem objects by file handles
222 is required.
223 .TP
224 .BR FAN_MOVED_TO " (since Linux 5.1)"
225 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
226 Create an event when a file or directory has been moved to a marked parent
227 directory.
228 An fanotify group that identifies filesystem objects by file handles
229 is required.
230 .TP
231 .BR FAN_MOVE_SELF " (since Linux 5.1)"
232 .\" commit 235328d1fa4251c6dcb32351219bb553a58838d2
233 Create an event when a marked file or directory itself has been moved.
234 An fanotify group that identifies filesystem objects by file handles
235 is required.
236 .TP
237 .B FAN_OPEN_PERM
238 Create an event when a permission to open a file or directory is requested.
239 An fanotify file descriptor created with
240 .B FAN_CLASS_PRE_CONTENT
241 or
242 .B FAN_CLASS_CONTENT
243 is required.
244 .TP
245 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
246 .\" commit 66917a3130f218dcef9eeab4fd11a71cd00cd7c9
247 Create an event when a permission to open a file for execution is
248 requested.
249 An fanotify file descriptor created with
250 .B FAN_CLASS_PRE_CONTENT
251 or
252 .B FAN_CLASS_CONTENT
253 is required.
254 See NOTES for additional details.
255 .TP
256 .B FAN_ACCESS_PERM
257 Create an event when a permission to read a file or directory is requested.
258 An fanotify file descriptor created with
259 .B FAN_CLASS_PRE_CONTENT
260 or
261 .B FAN_CLASS_CONTENT
262 is required.
263 .TP
264 .B FAN_ONDIR
265 Create events for directories\(emfor example, when
266 .BR opendir (3),
267 .BR readdir (3)
268 (but see BUGS), and
269 .BR closedir (3)
270 are called.
271 Without this flag, events are created only for files.
272 In the context of directory entry events, such as
273 .BR FAN_CREATE ,
274 .BR FAN_DELETE ,
275 .BR FAN_MOVED_FROM ,
276 and
277 .BR FAN_MOVED_TO ,
278 specifying the flag
279 .BR FAN_ONDIR
280 is required in order to create events when subdirectory entries are
281 modified (i.e.,
282 .BR mkdir (2)/
283 .BR rmdir (2)).
284 .TP
285 .B FAN_EVENT_ON_CHILD
286 Events for the immediate children of marked directories shall be created.
287 The flag has no effect when marking mounts and filesystems.
288 Note that events are not generated for children of the subdirectories
289 of marked directories.
290 More specifically, the directory entry modification events
291 .BR FAN_CREATE ,
292 .BR FAN_DELETE ,
293 .BR FAN_MOVED_FROM ,
294 and
295 .BR FAN_MOVED_TO
296 are not generated for any entry modifications performed inside subdirectories
297 of marked directories.
298 Note that the events
299 .BR FAN_DELETE_SELF
300 and
301 .BR FAN_MOVE_SELF
302 are not generated for children of marked directories.
303 To monitor complete directory trees it is necessary to mark the relevant
304 mount or filesystem.
305 .PP
306 The following composed values are defined:
307 .TP
308 .B FAN_CLOSE
309 A file is closed
310 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
311 .TP
312 .B FAN_MOVE
313 A file or directory has been moved
314 .RB ( FAN_MOVED_FROM | FAN_MOVED_TO ).
315 .PP
316 The filesystem object to be marked is determined by the file descriptor
317 .I dirfd
318 and the pathname specified in
319 .IR pathname :
320 .IP * 3
321 If
322 .I pathname
323 is NULL,
324 .I dirfd
325 defines the filesystem object to be marked.
326 .IP *
327 If
328 .I pathname
329 is NULL, and
330 .I dirfd
331 takes the special value
332 .BR AT_FDCWD ,
333 the current working directory is to be marked.
334 .IP *
335 If
336 .I pathname
337 is absolute, it defines the filesystem object to be marked, and
338 .I dirfd
339 is ignored.
340 .IP *
341 If
342 .I pathname
343 is relative, and
344 .I dirfd
345 does not have the value
346 .BR AT_FDCWD ,
347 then the filesystem object to be marked is determined by interpreting
348 .I pathname
349 relative the directory referred to by
350 .IR dirfd .
351 .IP *
352 If
353 .I pathname
354 is relative, and
355 .I dirfd
356 has the value
357 .BR AT_FDCWD ,
358 then the filesystem object to be marked is determined by interpreting
359 .I pathname
360 relative the current working directory.
361 .SH RETURN VALUE
362 On success,
363 .BR fanotify_mark ()
364 returns 0.
365 On error, \-1 is returned, and
366 .I errno
367 is set to indicate the error.
368 .SH ERRORS
369 .TP
370 .B EBADF
371 An invalid file descriptor was passed in
372 .IR fanotify_fd .
373 .TP
374 .B EBADF
375 .I pathname
376 is relative but
377 .I dirfd
378 is neither
379 .B AT_FDCWD
380 nor a valid file descriptor.
381 .TP
382 .B EINVAL
383 An invalid value was passed in
384 .IR flags
385 or
386 .IR mask ,
387 or
388 .I fanotify_fd
389 was not an fanotify file descriptor.
390 .TP
391 .B EINVAL
392 The fanotify file descriptor was opened with
393 .B FAN_CLASS_NOTIF
394 or the fanotify group identifies filesystem objects by file handles
395 and mask contains a flag for permission events
396 .RB ( FAN_OPEN_PERM
397 or
398 .BR FAN_ACCESS_PERM ).
399 .TP
400 .B ENODEV
401 The filesystem object indicated by
402 .I pathname
403 is not associated with a filesystem that supports
404 .I fsid
405 (e.g.,
406 .BR tmpfs (5)).
407 This error can be returned only with an fanotify group that identifies
408 filesystem objects by file handles.
409 .TP
410 .B ENOENT
411 The filesystem object indicated by
412 .IR dirfd
413 and
414 .IR pathname
415 does not exist.
416 This error also occurs when trying to remove a mark from an object
417 which is not marked.
418 .TP
419 .B ENOMEM
420 The necessary memory could not be allocated.
421 .TP
422 .B ENOSPC
423 The number of marks exceeds the limit of 8192 and the
424 .B FAN_UNLIMITED_MARKS
425 flag was not specified when the fanotify file descriptor was created with
426 .BR fanotify_init (2).
427 .TP
428 .B ENOSYS
429 This kernel does not implement
430 .BR fanotify_mark ().
431 The fanotify API is available only if the kernel was configured with
432 .BR CONFIG_FANOTIFY .
433 .TP
434 .B ENOTDIR
435 .I flags
436 contains
437 .BR FAN_MARK_ONLYDIR ,
438 and
439 .I dirfd
440 and
441 .I pathname
442 do not specify a directory.
443 .TP
444 .B EOPNOTSUPP
445 The object indicated by
446 .I pathname
447 is associated with a filesystem that does not support the encoding of file
448 handles.
449 This error can be returned only with an fanotify group that identifies
450 filesystem objects by file handles.
451 .TP
452 .B EXDEV
453 The filesystem object indicated by
454 .I pathname
455 resides within a filesystem subvolume (e.g.,
456 .BR btrfs (5))
457 which uses a different
458 .I fsid
459 than its root superblock.
460 This error can be returned only with an fanotify group that identifies
461 filesystem objects by file handles.
462 .SH VERSIONS
463 .BR fanotify_mark ()
464 was introduced in version 2.6.36 of the Linux kernel and enabled in version
465 2.6.37.
466 .SH CONFORMING TO
467 This system call is Linux-specific.
468 .SH NOTES
469 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
470 When using either
471 .B FAN_OPEN_EXEC
472 or
473 .B FAN_OPEN_EXEC_PERM
474 within the
475 .IR mask ,
476 events of these types will be returned only when the direct execution of a
477 program occurs.
478 More specifically, this means that events of these types will be generated
479 for files that are opened using
480 .BR execve (2),
481 .BR execveat (2),
482 or
483 .BR uselib (2).
484 Events of these types will not be raised in the situation where an
485 interpreter is passed (or reads) a file for interpretation.
486 .PP
487 Additionally, if a mark has also been placed on the Linux dynamic
488 linker, a user should also expect to receive an event for it when
489 an ELF object has been successfully opened using
490 .BR execve (2)
491 or
492 .BR execveat (2).
493 .PP
494 For example, if the following ELF binary were to be invoked and a
495 .BR FAN_OPEN_EXEC
496 mark has been placed on /:
497 .PP
498 .in +4n
499 .EX
500 $ /bin/echo foo
501 .EE
502 .in
503 .PP
504 The listening application in this case would receive
505 .BR FAN_OPEN_EXEC
506 events for both the ELF binary and interpreter, respectively:
507 .PP
508 .in +4n
509 .EX
510 /bin/echo
511 /lib64/ld\-linux\-x86\-64.so.2
512 .EE
513 .in
514 .SH BUGS
515 The following bugs were present in Linux kernels before version 3.16:
516 .IP * 3
517 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
518 If
519 .I flags
520 contains
521 .BR FAN_MARK_FLUSH ,
522 .IR dirfd ,
523 and
524 .I pathname
525 must specify a valid filesystem object, even though this object is not used.
526 .IP *
527 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
528 .BR readdir (2)
529 does not generate a
530 .B FAN_ACCESS
531 event.
532 .IP *
533 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
534 If
535 .BR fanotify_mark ()
536 is called with
537 .BR FAN_MARK_FLUSH ,
538 .I flags
539 is not checked for invalid values.
540 .SH SEE ALSO
541 .BR fanotify_init (2),
542 .BR fanotify (7)