| blob | 3c6e9565ae9267230116e59901c88de0da48d6fc |
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 2019-03-06 "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 .TP
130 .BR FAN_MARK_FILESYSTEM " (since Linux 4.20)"
131 .\" commit d54f4fba889b205e9cd8239182ca5d27d0ac3bc2
132 Mark the filesystem specified by
133 .IR pathname .
134 The filesystem containing
135 .I pathname
136 will be marked.
137 All the contained files and directories of the filesystem from any mount
138 point will be monitored.
139 .TP
140 .B FAN_MARK_IGNORED_MASK
141 The events in
142 .I mask
143 shall be added to or removed from the ignore mask.
144 .TP
145 .B FAN_MARK_IGNORED_SURV_MODIFY
146 The ignore mask shall survive modify events.
147 If this flag is not set,
148 the ignore mask is cleared when a modify event occurs
149 for the ignored file or directory.
150 .PP
151 .I mask
152 defines which events shall be listened for (or which shall be ignored).
153 It is a bit mask composed of the following values:
154 .TP
155 .B FAN_ACCESS
156 Create an event when a file or directory (but see BUGS) is accessed (read).
157 .TP
158 .B FAN_MODIFY
159 Create an event when a file is modified (write).
160 .TP
161 .B FAN_CLOSE_WRITE
162 Create an event when a writable file is closed.
163 .TP
164 .B FAN_CLOSE_NOWRITE
165 Create an event when a read-only file or directory is closed.
166 .TP
167 .B FAN_OPEN
168 Create an event when a file or directory is opened.
169 .TP
170 .B FAN_OPEN_EXEC " (since Linux 5.0)"
171 Create an event when a file is opened with the intent to be executed.
172 See NOTES for additional details.
173 .TP
174 .B FAN_Q_OVERFLOW
175 Create an event when an overflow of the event queue occurs.
176 The size of the event queue is limited to 16384 entries if
177 .B FAN_UNLIMITED_QUEUE
178 is not set in
179 .BR fanotify_init (2).
180 .TP
181 .B FAN_OPEN_PERM
182 Create an event when a permission to open a file or directory is requested.
183 An fanotify file descriptor created with
184 .B FAN_CLASS_PRE_CONTENT
185 or
186 .B FAN_CLASS_CONTENT
187 is required.
188 .TP
189 .BR FAN_OPEN_EXEC_PERM " (since Linux 5.0)"
190 Create an event when a permission to open a file for execution is
191 requested.
192 An fanotify file descriptor created with
193 .B FAN_CLASS_PRE_CONTENT
194 or
195 .B FAN_CLASS_CONTENT
196 is required.
197 See NOTES for additional details.
198 .TP
199 .B FAN_ACCESS_PERM
200 Create an event when a permission to read a file or directory is requested.
201 An fanotify file descriptor created with
202 .B FAN_CLASS_PRE_CONTENT
203 or
204 .B FAN_CLASS_CONTENT
205 is required.
206 .TP
207 .B FAN_ONDIR
208 Create events for directories\(emfor example, when
209 .BR opendir (3),
210 .BR readdir (3)
211 (but see BUGS), and
212 .BR closedir (3)
213 are called.
214 Without this flag, only events for files are created.
215 .TP
216 .B FAN_EVENT_ON_CHILD
217 Events for the immediate children of marked directories shall be created.
218 The flag has no effect when marking mounts and filesystems.
219 Note that events are not generated for children of the subdirectories
220 of marked directories.
221 To monitor complete directory trees it is necessary to mark the relevant
222 mount.
223 .PP
224 The following composed value is defined:
225 .TP
226 .B FAN_CLOSE
227 A file is closed
228 .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ).
229 .PP
230 The filesystem object to be marked is determined by the file descriptor
231 .I dirfd
232 and the pathname specified in
233 .IR pathname :
234 .IP * 3
235 If
236 .I pathname
237 is NULL,
238 .I dirfd
239 defines the filesystem object to be marked.
240 .IP *
241 If
242 .I pathname
243 is NULL, and
244 .I dirfd
245 takes the special value
246 .BR AT_FDCWD ,
247 the current working directory is to be marked.
248 .IP *
249 If
250 .I pathname
251 is absolute, it defines the filesystem object to be marked, and
252 .I dirfd
253 is ignored.
254 .IP *
255 If
256 .I pathname
257 is relative, and
258 .I dirfd
259 does not have the value
260 .BR AT_FDCWD ,
261 then the filesystem object to be marked is determined by interpreting
262 .I pathname
263 relative the directory referred to by
264 .IR dirfd .
265 .IP *
266 If
267 .I pathname
268 is relative, and
269 .I dirfd
270 has the value
271 .BR AT_FDCWD ,
272 then the filesystem object to be marked is determined by interpreting
273 .I pathname
274 relative the current working directory.
275 .SH RETURN VALUE
276 On success,
277 .BR fanotify_mark ()
278 returns 0.
279 On error, \-1 is returned, and
280 .I errno
281 is set to indicate the error.
282 .SH ERRORS
283 .TP
284 .B EBADF
285 An invalid file descriptor was passed in
286 .IR fanotify_fd .
287 .TP
288 .B EINVAL
289 An invalid value was passed in
290 .IR flags
291 or
292 .IR mask ,
293 or
294 .I fanotify_fd
295 was not an fanotify file descriptor.
296 .TP
297 .B EINVAL
298 The fanotify file descriptor was opened with
299 .B FAN_CLASS_NOTIF
300 and mask contains a flag for permission events
301 .RB ( FAN_OPEN_PERM
302 or
303 .BR FAN_ACCESS_PERM ).
304 .TP
305 .B ENOENT
306 The filesystem object indicated by
307 .IR dirfd
308 and
309 .IR pathname
310 does not exist.
311 This error also occurs when trying to remove a mark from an object
312 which is not marked.
313 .TP
314 .B ENOMEM
315 The necessary memory could not be allocated.
316 .TP
317 .B ENOSPC
318 The number of marks exceeds the limit of 8192 and the
319 .B FAN_UNLIMITED_MARKS
320 flag was not specified when the fanotify file descriptor was created with
321 .BR fanotify_init (2).
322 .TP
323 .B ENOSYS
324 This kernel does not implement
325 .BR fanotify_mark ().
326 The fanotify API is available only if the kernel was configured with
327 .BR CONFIG_FANOTIFY .
328 .TP
329 .B ENOTDIR
330 .I flags
331 contains
332 .BR FAN_MARK_ONLYDIR ,
333 and
334 .I dirfd
335 and
336 .I pathname
337 do not specify a directory.
338 .SH VERSIONS
339 .BR fanotify_mark ()
340 was introduced in version 2.6.36 of the Linux kernel and enabled in version
341 2.6.37.
342 .SH CONFORMING TO
343 This system call is Linux-specific.
344 .SH NOTES
345 .SS FAN_OPEN_EXEC and FAN_OPEN_EXEC_PERM
346 When using either
347 .B FAN_OPEN_EXEC
348 or
349 .B FAN_OPEN_EXEC_PERM
350 within the
351 .IR mask ,
352 events of these types will be returned only when the direct execution of a
353 program occurs.
354 More specifically, this means that events of these types will be generated
355 for files that are opened using
356 .BR execve (2),
357 .BR execveat (2),
358 or
359 .BR uselib (2).
360 Events of these types will not be raised in the situation where an
361 interpreter is passed (or reads) a script file for interpretation.
362 .PP
363 Additionally, if a mark has also been placed on the Linux dynamic
364 linker, a user should also expect to receive an event for it when
365 an ELF object has been successfully opened using
366 .BR execve (2)
367 or
368 .BR execveat (2).
369 .PP
370 For example, if the following ELF binary were to be invoked and a
371 .BR FAN_OPEN_EXEC
372 mark has been placed on /:
373 .PP
374 .in +4n
375 .EX
376 $ /bin/echo foo
377 .EE
378 .in
379 .PP
380 The listening application in this case would receive
381 .BR FAN_OPEN_EXEC
382 events for both the ELF binary and interpreter, respectively:
383 .PP
384 .in +4n
385 .EX
386 /bin/echo
387 /lib64/ld-linux-x86-64.so.2
388 .EE
389 .in
390 .SH BUGS
391 The following bugs were present in Linux kernels before version 3.16:
392 .IP * 3
393 .\" Fixed by commit 0a8dd2db579f7a0ac7033d6b857c3d5dbaa77563
394 If
395 .I flags
396 contains
397 .BR FAN_MARK_FLUSH ,
398 .I dirfd
399 and
400 .I pathname
401 must specify a valid filesystem object, even though this object is not used.
402 .IP *
403 .\" Fixed by commit d4c7cf6cffb1bc711a833b5e304ba5bcfe76398b
404 .BR readdir (2)
405 does not generate a
406 .B FAN_ACCESS
407 event.
408 .IP *
409 .\" Fixed by commit cc299a98eb13a9853675a9cbb90b30b4011e1406
410 If
411 .BR fanotify_mark ()
412 is called with
413 .BR FAN_MARK_FLUSH ,
414 .I flags
415 is not checked for invalid values.
416 .SH SEE ALSO
417 .BR fanotify_init (2),
418 .BR fanotify (7)