]>
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 | |
24 | .TH FANOTIFY_MARK 2 2014-04-24 "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 | .sp | |
32 | .BI "int fanotify_mark(int " fanotify_fd ", unsigned int " flags , | |
33 | .BI " uint64_t " mask ", int " dirfd , | |
34 | .BI " 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 (2) | |
b6551738 | 41 | adds, removes, or modifies an fanotify mark on a filesystem object. |
c200b422 HS |
42 | The caller must have read permission on the filesystem object that is to be |
43 | marked. | |
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 | |
73 | Remove either all mount or non-mount marks from the fanotify group. | |
74 | If | |
75 | .I flag | |
76 | contains | |
77 | .BR FAN_MARK_MOUNT , | |
78 | all marks for mounts are removed from the group. | |
79 | Otherwise, all marks for directories and files are removed. | |
80 | No other flag but | |
81 | .B FAN_MARK_MOUNT | |
82 | can be used in conjunction with | |
83 | .BR FAN_MARK_FLUSH . | |
84 | .I mask | |
85 | is ignored. | |
86 | .PP | |
87 | If none of the values above is specified, or more than one is specified, the | |
88 | call fails with the error | |
89 | .BR EINVAL . | |
90 | .PP | |
91 | In addition, | |
92 | .I flags | |
93 | may contain zero or more of the following: | |
94 | .TP | |
95 | .B FAN_MARK_DONT_FOLLOW | |
96 | If | |
97 | .I pathname | |
98 | is a symbolic link, mark the link itself, rather than the file to which it | |
99 | refers. | |
100 | (By default, | |
101 | .BR fanotify_mark () | |
102 | dereferences | |
103 | .I pathname | |
104 | if it is a symbolic link.) | |
105 | .TP | |
106 | .B FAN_MARK_ONLYDIR | |
107 | If the filesystem object to be marked is not a directory, the error | |
108 | .B ENOTDIR | |
109 | shall be raised. | |
110 | .TP | |
111 | .B FAN_MARK_MOUNT | |
112 | The | |
113 | .I pathname | |
114 | indicates a mount point to be marked. | |
115 | If the path is not itself a mount point, the mount point containing the path | |
116 | will be marked. | |
117 | All directories, subdirectories, and the contained files of the mount point | |
118 | will be monitored. | |
119 | .TP | |
120 | .B FAN_MARK_IGNORED_MASK | |
121 | The events in | |
122 | .I mask | |
123 | shall be added to or removed from the ignore mask. | |
124 | .TP | |
125 | .B FAN_MARK_IGNORED_SURV_MODIFY | |
126 | The ignore mask shall survive modify events. | |
127 | If this flag is not set, the ignore mask is cleared when a modify event occurs | |
128 | for the ignored file or directory. | |
129 | .PP | |
130 | .I mask | |
131 | defines which events shall be listened to (or which shall be ignored). | |
132 | It is a bit mask composed of the following values: | |
133 | .TP | |
134 | .B FAN_ACCESS | |
135 | Create an event when a file or directory (but see BUGS) is accessed (read). | |
136 | .TP | |
137 | .B FAN_MODIFY | |
138 | Create an event when a file is modified (write). | |
139 | .TP | |
140 | .B FAN_CLOSE_WRITE | |
141 | Create an event when a writable file is closed. | |
142 | .TP | |
143 | .B FAN_CLOSE_NOWRITE | |
144 | Create an event when a read-only file or directory is closed. | |
145 | .TP | |
146 | .B FAN_OPEN | |
147 | Create an event when a file or directory is opened. | |
148 | .TP | |
149 | .B FAN_OPEN_PERM | |
150 | Create an event when a permission to open a file or directory is requested. | |
151 | An fanotify file descriptor created with | |
152 | .B FAN_CLASS_PRE_CONTENT | |
153 | or | |
154 | .B FAN_CLASS_CONTENT | |
155 | is required. | |
156 | .TP | |
157 | .B FAN_ACCESS_PERM | |
158 | Create an event when a permission to read a file or directory is requested. | |
159 | An fanotify file descriptor created with | |
160 | .B FAN_CLASS_PRE_CONTENT | |
161 | or | |
162 | .B FAN_CLASS_CONTENT | |
163 | is required. | |
164 | .TP | |
165 | .B FAN_ONDIR | |
166 | Events for directories shall be created, for example when | |
167 | .BR opendir (2), | |
168 | .BR readdir (2) | |
169 | (but see BUGS), and | |
170 | .BR closedir (2) | |
171 | are called. | |
172 | Without this flag only events for files are created. | |
173 | .TP | |
174 | .B FAN_EVENT_ON_CHILD | |
175 | Events for the immediate children of marked directories shall be created. | |
176 | The flag has no effect when marking mounts. | |
177 | Note that events are not generated for children of the subdirectories | |
178 | of marked directories. | |
179 | To monitor complete directory trees it is necessary to mark the relevant | |
180 | mount. | |
181 | .PP | |
182 | The following composed value is defined: | |
183 | .TP | |
184 | .B FAN_CLOSE | |
185 | A file is closed | |
186 | .RB ( FAN_CLOSE_WRITE | FAN_CLOSE_NOWRITE ). | |
187 | .PP | |
188 | The filesystem object to be marked is determined by the file descriptor | |
189 | .I dirfd | |
190 | and the pathname specified in | |
191 | .IR pathname : | |
192 | .IP * 3 | |
193 | If | |
194 | .I pathname | |
195 | is NULL, | |
196 | .I dirfd | |
197 | defines the filesystem object to be marked. | |
198 | .IP * | |
199 | If | |
200 | .I pathname | |
201 | is NULL, and | |
202 | .I dirfd | |
203 | takes the special value | |
204 | .BR AT_FDCWD , | |
205 | the current working directory is to be marked. | |
206 | .IP * | |
207 | If | |
208 | .I pathname | |
209 | is absolute, it defines the filesystem object to be marked, and | |
210 | .I dirfd | |
211 | is ignored. | |
212 | .IP * | |
213 | If | |
214 | .I pathname | |
215 | is relative, and | |
216 | .I dirfd | |
217 | does not have the value | |
218 | .BR AT_FDCWD , | |
219 | then the filesystem object to be marked is determined by interpreting | |
220 | .I pathname | |
221 | relative the directory referred to by | |
222 | .IR dirfd . | |
223 | .IP * | |
224 | If | |
225 | .I pathname | |
226 | is relative, and | |
227 | .I dirfd | |
228 | has the value | |
229 | .BR AT_FDCWD, | |
230 | then the filesystem object to be marked is determined by interpreting | |
231 | .I pathname | |
232 | relative the current working directory. | |
233 | .SH RETURN VALUE | |
234 | On success, | |
235 | .BR fanotify_mark () | |
236 | returns 0. | |
237 | In case of an error, \-1 is returned, and | |
238 | .I errno | |
239 | is set to indicate the error. | |
240 | .SH ERRORS | |
241 | .TP | |
242 | .B EBADF | |
243 | An invalid file descriptor was passed in | |
244 | .IR fanotify_fd . | |
245 | .TP | |
246 | .B EINVAL | |
247 | An invalid value was passed in | |
248 | .IR flags | |
249 | or | |
250 | .IR mask , | |
251 | or | |
252 | .I fanotify_fd | |
253 | was not an fanotify file descriptor. | |
254 | .TP | |
255 | .B EINVAL | |
256 | The fanotify file descriptor was opened with | |
257 | .B FAN_CLASS_NOTIF | |
258 | and mask contains a flag for permission events | |
259 | .RB ( FAN_OPEN_PERM | |
260 | or | |
261 | .BR FAN_ACCESS_PERM ). | |
262 | .TP | |
263 | .B ENOENT | |
264 | The filesystem object indicated by | |
265 | .IR dirfd | |
266 | and | |
267 | .IR pathname | |
268 | does not exist. | |
269 | This error also occurs when trying to remove a mark from an object which is not | |
270 | marked. | |
271 | .TP | |
272 | .B ENOMEM | |
273 | The necessary memory could not be allocated. | |
274 | .TP | |
275 | .B ENOSPC | |
276 | The number of marks exceeds the limit of 8192 and | |
277 | .B FAN_UNLIMITED_MARKS | |
278 | was not specified in the call to | |
279 | .BR fanotify_init (2). | |
280 | .TP | |
281 | .B ENOTDIR | |
282 | .I flags | |
283 | contains | |
284 | .BR FAN_MARK_ONLYDIR , | |
285 | and | |
286 | .I dirfd | |
287 | and | |
288 | .I pathname | |
289 | do not specify a directory. | |
290 | .SH VERSIONS | |
291 | .BR fanotify_mark () | |
292 | was introduced in version 2.6.36 of the Linux kernel and enabled in version | |
293 | 2.6.37. | |
294 | .SH CONFORMING TO | |
295 | This system call is Linux-specific. | |
296 | .SH BUGS | |
297 | As of Linux 3.15, | |
298 | the following bugs exist: | |
299 | .IP * 3 | |
300 | .\" FIXME: Patch is in next-20140424. | |
301 | If | |
302 | .I flags | |
303 | contains | |
304 | .BR FAN_MARK_FLUSH , | |
305 | .I dfd | |
306 | and | |
307 | .I pathname | |
308 | must indicate a valid path. | |
309 | This path is not used. | |
310 | .IP * | |
311 | .\" FIXME: Patch is in next-20140424. | |
312 | .BR readdir (2) | |
313 | does not result in a | |
314 | .B FAN_ACCESS | |
315 | event. | |
316 | .IP * | |
317 | .\" FIXME: Patch proposed. | |
318 | If | |
319 | .BR fanotify_mark (2) | |
320 | is called with | |
321 | .B FAN_MARK_FLUSH, | |
322 | .I flags | |
323 | is not checked for invalid values. | |
324 | .SH SEE ALSO | |
325 | .BR fanotify_init (2), | |
326 | .BR fanotify (7) |