]>
Commit | Line | Data |
---|---|---|
817c8240 | 1 | \" Copyright (C) 2013, Heinrich Schuchardt <xypron.glpk@gmx.de> |
3e6ebb33 HS |
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_INIT 2 2019-08-02 "Linux" "Linux Programmer's Manual" |
3e6ebb33 HS |
25 | .SH NAME |
26 | fanotify_init \- create and initialize fanotify group | |
27 | .SH SYNOPSIS | |
28 | .B #include <fcntl.h> | |
29 | .br | |
30 | .B #include <sys/fanotify.h> | |
080522cb | 31 | .PP |
3e6ebb33 HS |
32 | .BI "int fanotify_init(unsigned int " flags ", unsigned int " event_f_flags ); |
33 | .SH DESCRIPTION | |
34 | For an overview of the fanotify API, see | |
35 | .BR fanotify (7). | |
36 | .PP | |
37 | .BR fanotify_init () | |
38 | initializes a new fanotify group and returns a file descriptor for the event | |
39 | queue associated with the group. | |
40 | .PP | |
41 | The file descriptor is used in calls to | |
42 | .BR fanotify_mark (2) | |
0a4db6dc MB |
43 | to specify the files, directories, mounts or filesystems for which fanotify |
44 | events shall be created. | |
3e6ebb33 HS |
45 | These events are received by reading from the file descriptor. |
46 | Some events are only informative, indicating that a file has been accessed. | |
72b14a93 MK |
47 | Other events can be used to determine whether |
48 | another application is permitted to access a file or directory. | |
3e6ebb33 HS |
49 | Permission to access filesystem objects is granted by writing to the file |
50 | descriptor. | |
51 | .PP | |
52 | Multiple programs may be using the fanotify interface at the same time to | |
53 | monitor the same files. | |
54 | .PP | |
55 | In the current implementation, the number of fanotify groups per user is | |
56 | limited to 128. | |
57 | This limit cannot be overridden. | |
58 | .PP | |
59 | Calling | |
60 | .BR fanotify_init () | |
61 | requires the | |
62 | .B CAP_SYS_ADMIN | |
63 | capability. | |
64 | This constraint might be relaxed in future versions of the API. | |
f1282fd0 | 65 | Therefore, certain additional capability checks have been implemented as |
3e6ebb33 HS |
66 | indicated below. |
67 | .PP | |
68 | The | |
69 | .I flags | |
70 | argument contains a multi-bit field defining the notification class of the | |
1b24e2ee MK |
71 | listening application and further single bit fields specifying the behavior |
72 | of the file descriptor. | |
3e6ebb33 | 73 | .PP |
1b24e2ee MK |
74 | If multiple listeners for permission events exist, |
75 | the notification class is used to establish the sequence | |
76 | in which the listeners receive the events. | |
3e6ebb33 | 77 | .PP |
d58f4190 MK |
78 | Only one of the following notification classes may be specified in |
79 | .IR flags : | |
3e6ebb33 HS |
80 | .TP |
81 | .B FAN_CLASS_PRE_CONTENT | |
82 | This value allows the receipt of events notifying that a file has been | |
83 | accessed and events for permission decisions if a file may be accessed. | |
84 | It is intended for event listeners that need to access files before they | |
85 | contain their final data. | |
1b24e2ee MK |
86 | This notification class might be used by hierarchical storage managers, |
87 | for example. | |
3e6ebb33 HS |
88 | .TP |
89 | .B FAN_CLASS_CONTENT | |
90 | This value allows the receipt of events notifying that a file has been | |
91 | accessed and events for permission decisions if a file may be accessed. | |
1b24e2ee MK |
92 | It is intended for event listeners that need to access files when they |
93 | already contain their final content. | |
3e6ebb33 HS |
94 | This notification class might be used by malware detection programs, for |
95 | example. | |
96 | .TP | |
0a4db6dc MB |
97 | .BR FAN_REPORT_FID " (since Linux 5.1)" |
98 | .\" commit a8b13aa20afb69161b5123b4f1acc7ea0a03d360 | |
99 | This value allows the receipt of events which contain additional information | |
eae836e0 | 100 | about the underlying filesystem object correlated to an event. |
0a4db6dc MB |
101 | An additional structure encapsulates the information about the object and is |
102 | included alongside the generic event metadata structure. | |
103 | The file descriptor that is used to represent the object correlated to an | |
104 | event is instead substituted with a file handle. | |
105 | It is intended for applications that may find the use of a file handle to | |
106 | identify an object more suitable than a file descriptor. | |
107 | Additionally, it may be used for applications that are interested in | |
108 | directory entry events, such as | |
109 | .BR FAN_CREATE , | |
110 | .BR FAN_ATTRIB , | |
817c8240 | 111 | .BR FAN_MOVE , |
0a4db6dc MB |
112 | and |
113 | .BR FAN_DELETE | |
114 | for example. | |
115 | Note that the use of directory modification events are not supported when | |
116 | monitoring a mount point. | |
117 | The use of | |
118 | .BR FAN_CLASS_CONTENT | |
119 | or | |
120 | .BR FAN_CLASS_PRE_CONTENT | |
121 | is not permitted with this flag and will result in the error | |
122 | .BR EINVAL . | |
123 | See | |
124 | .BR fanotify (7) | |
125 | for additional information. | |
126 | .TP | |
3e6ebb33 HS |
127 | .B FAN_CLASS_NOTIF |
128 | This is the default value. | |
129 | It does not need to be specified. | |
130 | This value only allows the receipt of events notifying that a file has been | |
131 | accessed. | |
132 | Permission decisions before the file is accessed are not possible. | |
133 | .PP | |
134 | Listeners with different notification classes will receive events in the | |
cd505a8a | 135 | order |
3e6ebb33 HS |
136 | .BR FAN_CLASS_PRE_CONTENT , |
137 | .BR FAN_CLASS_CONTENT , | |
138 | .BR FAN_CLASS_NOTIF . | |
8d605e55 MK |
139 | The order of notification for listeners in the same notification class |
140 | is undefined. | |
3e6ebb33 | 141 | .PP |
8d605e55 | 142 | The following bits can additionally be set in |
3e6ebb33 HS |
143 | .IR flags : |
144 | .TP | |
145 | .B FAN_CLOEXEC | |
8d605e55 | 146 | Set the close-on-exec flag |
3e6ebb33 HS |
147 | .RB ( FD_CLOEXEC ) |
148 | on the new file descriptor. | |
149 | See the description of the | |
150 | .B O_CLOEXEC | |
151 | flag in | |
152 | .BR open (2). | |
153 | .TP | |
154 | .B FAN_NONBLOCK | |
8d605e55 | 155 | Enable the nonblocking flag |
3e6ebb33 HS |
156 | .RB ( O_NONBLOCK ) |
157 | for the file descriptor. | |
158 | Reading from the file descriptor will not block. | |
f199b308 | 159 | Instead, if no data is available, |
3e6ebb33 | 160 | .BR read (2) |
a23d8efa | 161 | fails with the error |
f199b308 | 162 | .BR EAGAIN . |
3e6ebb33 HS |
163 | .TP |
164 | .B FAN_UNLIMITED_QUEUE | |
8d605e55 MK |
165 | Remove the limit of 16384 events for the event queue. |
166 | Use of this flag requires the | |
3e6ebb33 HS |
167 | .B CAP_SYS_ADMIN |
168 | capability. | |
169 | .TP | |
170 | .B FAN_UNLIMITED_MARKS | |
8d605e55 MK |
171 | Remove the limit of 8192 marks. |
172 | Use of this flag requires the | |
3e6ebb33 HS |
173 | .B CAP_SYS_ADMIN |
174 | capability. | |
ebfb6fee | 175 | .TP |
176 | .BR FAN_REPORT_TID " (since Linux 4.20)" | |
177 | .\" commit d0a6a87e40da49cfc7954c491d3065a25a641b29 | |
ce61c76f MK |
178 | Report thread ID (TID) instead of process ID (PID) |
179 | in the | |
180 | .I pid | |
181 | field of the | |
182 | .I "struct fanotify_event_metadata" | |
183 | supplied to | |
184 | .BR read (2) | |
185 | (see | |
186 | .BR fanotify (7)). | |
3e6ebb33 | 187 | .PP |
8d605e55 | 188 | The |
3e6ebb33 | 189 | .I event_f_flags |
8d605e55 MK |
190 | argument |
191 | defines the file status flags that will be set on the open file descriptions | |
192 | that are created for fanotify events. | |
193 | For details of these flags, see the description of the | |
3e6ebb33 | 194 | .I flags |
8d605e55 MK |
195 | values in |
196 | .BR open (2). | |
1caffed4 | 197 | .I event_f_flags |
be5c465e | 198 | includes a multi-bit field for the access mode. |
1caffed4 | 199 | This field can take the following values: |
3e6ebb33 HS |
200 | .TP |
201 | .B O_RDONLY | |
202 | This value allows only read access. | |
203 | .TP | |
204 | .B O_WRONLY | |
205 | This value allows only write access. | |
206 | .TP | |
207 | .B O_RDWR | |
208 | This value allows read and write access. | |
1caffed4 HS |
209 | .PP |
210 | Additional bits can be set in | |
211 | .IR event_f_flags . | |
212 | The most useful values are: | |
3e6ebb33 HS |
213 | .TP |
214 | .B O_LARGEFILE | |
c4b7e5ac | 215 | Enable support for files exceeding 2\ GB. |
3e6ebb33 HS |
216 | Failing to set this flag will result in an |
217 | .B EOVERFLOW | |
1b24e2ee MK |
218 | error when trying to open a large file which is monitored by |
219 | an fanotify group on a 32-bit system. | |
1caffed4 | 220 | .TP |
d38a09fc MK |
221 | .BR O_CLOEXEC " (since Linux 3.18)" |
222 | .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 | |
1caffed4 | 223 | Enable the close-on-exec flag for the file descriptor. |
be5c465e MK |
224 | See the description of the |
225 | .B O_CLOEXEC | |
226 | flag in | |
227 | .BR open (2) | |
228 | for reasons why this may be useful. | |
1caffed4 HS |
229 | .PP |
230 | The following are also allowable: | |
231 | .BR O_APPEND , | |
232 | .BR O_DSYNC , | |
233 | .BR O_NOATIME , | |
234 | .BR O_NONBLOCK , | |
235 | and | |
236 | .BR O_SYNC . | |
be5c465e MK |
237 | Specifying any other flag in |
238 | .I event_f_flags | |
239 | yields the error | |
1caffed4 HS |
240 | .B EINVAL |
241 | (but see BUGS). | |
3e6ebb33 HS |
242 | .SH RETURN VALUE |
243 | On success, | |
244 | .BR fanotify_init () | |
245 | returns a new file descriptor. | |
ddfa9db7 | 246 | On error, \-1 is returned, and |
3e6ebb33 HS |
247 | .I errno |
248 | is set to indicate the error. | |
249 | .SH ERRORS | |
250 | .TP | |
251 | .B EINVAL | |
252 | An invalid value was passed in | |
1caffed4 HS |
253 | .I flags |
254 | or | |
255 | .IR event_f_flags . | |
3e6ebb33 | 256 | .B FAN_ALL_INIT_FLAGS |
0a4db6dc MB |
257 | (deprecated since Linux kernel version 4.20) |
258 | .\" commit 23c9deeb3285d34fd243abb3d6b9f07db60c3cf4 | |
1caffed4 HS |
259 | defines all allowable bits for |
260 | .IR flags . | |
3e6ebb33 HS |
261 | .TP |
262 | .B EMFILE | |
8d605e55 | 263 | The number of fanotify groups for this user exceeds 128. |
3e6ebb33 | 264 | .TP |
356a2957 | 265 | .B EMFILE |
71d597e9 MK |
266 | The per-process limit on the number of open file descriptors has been reached. |
267 | .TP | |
3e6ebb33 HS |
268 | .B ENOMEM |
269 | The allocation of memory for the notification group failed. | |
270 | .TP | |
a8972eed HS |
271 | .B ENOSYS |
272 | This kernel does not implement | |
273 | .BR fanotify_init (). | |
8d605e55 MK |
274 | The fanotify API is available only if the kernel was configured with |
275 | .BR CONFIG_FANOTIFY . | |
a8972eed | 276 | .TP |
3e6ebb33 HS |
277 | .B EPERM |
278 | The operation is not permitted because the caller lacks the | |
279 | .B CAP_SYS_ADMIN | |
280 | capability. | |
281 | .SH VERSIONS | |
282 | .BR fanotify_init () | |
283 | was introduced in version 2.6.36 of the Linux kernel and enabled in version | |
284 | 2.6.37. | |
d282bb24 | 285 | .SH CONFORMING TO |
3e6ebb33 | 286 | This system call is Linux-specific. |
6448be7e | 287 | .SH BUGS |
692b4bcc | 288 | The following bug was present in Linux kernels before version 3.18: |
0d69c093 | 289 | .IP * 3 |
692b4bcc | 290 | .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 |
51d266b7 | 291 | The |
0d69c093 | 292 | .B O_CLOEXEC |
51d266b7 MK |
293 | is ignored when passed in |
294 | .IR event_f_flags . | |
0d69c093 | 295 | .PP |
f479e19c | 296 | The following bug was present in Linux kernels before version 3.14: |
6448be7e | 297 | .IP * 3 |
f479e19c | 298 | .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 |
20abed53 | 299 | The |
6448be7e | 300 | .I event_f_flags |
491bc783 | 301 | argument is not checked for invalid flags. |
20abed53 MK |
302 | Flags that are intended only for internal use, |
303 | such as | |
6448be7e | 304 | .BR FMODE_EXEC , |
20abed53 MK |
305 | can be set, and will consequently be set for the file descriptors |
306 | returned when reading from the fanotify file descriptor. | |
d282bb24 | 307 | .SH SEE ALSO |
3e6ebb33 HS |
308 | .BR fanotify_mark (2), |
309 | .BR fanotify (7) |