]>
Commit | Line | Data |
---|---|---|
3e6ebb33 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 | |
4b8c67d9 | 24 | .TH FANOTIFY_INIT 2 2017-09-15 "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) | |
1b24e2ee MK |
43 | to specify the files, directories, and mounts for which fanotify events |
44 | 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 | |
97 | .B FAN_CLASS_NOTIF | |
98 | This is the default value. | |
99 | It does not need to be specified. | |
100 | This value only allows the receipt of events notifying that a file has been | |
101 | accessed. | |
102 | Permission decisions before the file is accessed are not possible. | |
103 | .PP | |
104 | Listeners with different notification classes will receive events in the | |
cd505a8a | 105 | order |
3e6ebb33 HS |
106 | .BR FAN_CLASS_PRE_CONTENT , |
107 | .BR FAN_CLASS_CONTENT , | |
108 | .BR FAN_CLASS_NOTIF . | |
8d605e55 MK |
109 | The order of notification for listeners in the same notification class |
110 | is undefined. | |
3e6ebb33 | 111 | .PP |
8d605e55 | 112 | The following bits can additionally be set in |
3e6ebb33 HS |
113 | .IR flags : |
114 | .TP | |
115 | .B FAN_CLOEXEC | |
8d605e55 | 116 | Set the close-on-exec flag |
3e6ebb33 HS |
117 | .RB ( FD_CLOEXEC ) |
118 | on the new file descriptor. | |
119 | See the description of the | |
120 | .B O_CLOEXEC | |
121 | flag in | |
122 | .BR open (2). | |
123 | .TP | |
124 | .B FAN_NONBLOCK | |
8d605e55 | 125 | Enable the nonblocking flag |
3e6ebb33 HS |
126 | .RB ( O_NONBLOCK ) |
127 | for the file descriptor. | |
128 | Reading from the file descriptor will not block. | |
f199b308 | 129 | Instead, if no data is available, |
3e6ebb33 | 130 | .BR read (2) |
a23d8efa | 131 | fails with the error |
f199b308 | 132 | .BR EAGAIN . |
3e6ebb33 HS |
133 | .TP |
134 | .B FAN_UNLIMITED_QUEUE | |
8d605e55 MK |
135 | Remove the limit of 16384 events for the event queue. |
136 | Use of this flag requires the | |
3e6ebb33 HS |
137 | .B CAP_SYS_ADMIN |
138 | capability. | |
139 | .TP | |
140 | .B FAN_UNLIMITED_MARKS | |
8d605e55 MK |
141 | Remove the limit of 8192 marks. |
142 | Use of this flag requires the | |
3e6ebb33 HS |
143 | .B CAP_SYS_ADMIN |
144 | capability. | |
145 | .PP | |
8d605e55 | 146 | The |
3e6ebb33 | 147 | .I event_f_flags |
8d605e55 MK |
148 | argument |
149 | defines the file status flags that will be set on the open file descriptions | |
150 | that are created for fanotify events. | |
151 | For details of these flags, see the description of the | |
3e6ebb33 | 152 | .I flags |
8d605e55 MK |
153 | values in |
154 | .BR open (2). | |
1caffed4 | 155 | .I event_f_flags |
be5c465e | 156 | includes a multi-bit field for the access mode. |
1caffed4 | 157 | This field can take the following values: |
3e6ebb33 HS |
158 | .TP |
159 | .B O_RDONLY | |
160 | This value allows only read access. | |
161 | .TP | |
162 | .B O_WRONLY | |
163 | This value allows only write access. | |
164 | .TP | |
165 | .B O_RDWR | |
166 | This value allows read and write access. | |
1caffed4 HS |
167 | .PP |
168 | Additional bits can be set in | |
169 | .IR event_f_flags . | |
170 | The most useful values are: | |
3e6ebb33 HS |
171 | .TP |
172 | .B O_LARGEFILE | |
c4b7e5ac | 173 | Enable support for files exceeding 2\ GB. |
3e6ebb33 HS |
174 | Failing to set this flag will result in an |
175 | .B EOVERFLOW | |
1b24e2ee MK |
176 | error when trying to open a large file which is monitored by |
177 | an fanotify group on a 32-bit system. | |
1caffed4 | 178 | .TP |
d38a09fc MK |
179 | .BR O_CLOEXEC " (since Linux 3.18)" |
180 | .\" commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 | |
1caffed4 | 181 | Enable the close-on-exec flag for the file descriptor. |
be5c465e MK |
182 | See the description of the |
183 | .B O_CLOEXEC | |
184 | flag in | |
185 | .BR open (2) | |
186 | for reasons why this may be useful. | |
1caffed4 HS |
187 | .PP |
188 | The following are also allowable: | |
189 | .BR O_APPEND , | |
190 | .BR O_DSYNC , | |
191 | .BR O_NOATIME , | |
192 | .BR O_NONBLOCK , | |
193 | and | |
194 | .BR O_SYNC . | |
be5c465e MK |
195 | Specifying any other flag in |
196 | .I event_f_flags | |
197 | yields the error | |
1caffed4 HS |
198 | .B EINVAL |
199 | (but see BUGS). | |
3e6ebb33 HS |
200 | .SH RETURN VALUE |
201 | On success, | |
202 | .BR fanotify_init () | |
203 | returns a new file descriptor. | |
ddfa9db7 | 204 | On error, \-1 is returned, and |
3e6ebb33 HS |
205 | .I errno |
206 | is set to indicate the error. | |
207 | .SH ERRORS | |
208 | .TP | |
209 | .B EINVAL | |
210 | An invalid value was passed in | |
1caffed4 HS |
211 | .I flags |
212 | or | |
213 | .IR event_f_flags . | |
3e6ebb33 | 214 | .B FAN_ALL_INIT_FLAGS |
1caffed4 HS |
215 | defines all allowable bits for |
216 | .IR flags . | |
3e6ebb33 HS |
217 | .TP |
218 | .B EMFILE | |
8d605e55 | 219 | The number of fanotify groups for this user exceeds 128. |
3e6ebb33 | 220 | .TP |
356a2957 | 221 | .B EMFILE |
71d597e9 MK |
222 | The per-process limit on the number of open file descriptors has been reached. |
223 | .TP | |
3e6ebb33 HS |
224 | .B ENOMEM |
225 | The allocation of memory for the notification group failed. | |
226 | .TP | |
a8972eed HS |
227 | .B ENOSYS |
228 | This kernel does not implement | |
229 | .BR fanotify_init (). | |
8d605e55 MK |
230 | The fanotify API is available only if the kernel was configured with |
231 | .BR CONFIG_FANOTIFY . | |
a8972eed | 232 | .TP |
3e6ebb33 HS |
233 | .B EPERM |
234 | The operation is not permitted because the caller lacks the | |
235 | .B CAP_SYS_ADMIN | |
236 | capability. | |
237 | .SH VERSIONS | |
238 | .BR fanotify_init () | |
239 | was introduced in version 2.6.36 of the Linux kernel and enabled in version | |
240 | 2.6.37. | |
d282bb24 | 241 | .SH CONFORMING TO |
3e6ebb33 | 242 | This system call is Linux-specific. |
6448be7e | 243 | .SH BUGS |
692b4bcc | 244 | The following bug was present in Linux kernels before version 3.18: |
0d69c093 | 245 | .IP * 3 |
692b4bcc | 246 | .\" Fixed by commit 0b37e097a648aa71d4db1ad108001e95b69a2da4 |
51d266b7 | 247 | The |
0d69c093 | 248 | .B O_CLOEXEC |
51d266b7 MK |
249 | is ignored when passed in |
250 | .IR event_f_flags . | |
0d69c093 | 251 | .PP |
f479e19c | 252 | The following bug was present in Linux kernels before version 3.14: |
6448be7e | 253 | .IP * 3 |
f479e19c | 254 | .\" Fixed by commit 48149e9d3a7e924010a0daab30a6197b7d7b6580 |
20abed53 | 255 | The |
6448be7e | 256 | .I event_f_flags |
491bc783 | 257 | argument is not checked for invalid flags. |
20abed53 MK |
258 | Flags that are intended only for internal use, |
259 | such as | |
6448be7e | 260 | .BR FMODE_EXEC , |
20abed53 MK |
261 | can be set, and will consequently be set for the file descriptors |
262 | returned when reading from the fanotify file descriptor. | |
d282bb24 | 263 | .SH SEE ALSO |
3e6ebb33 HS |
264 | .BR fanotify_mark (2), |
265 | .BR fanotify (7) |