]>
Commit | Line | Data |
---|---|---|
4d2b74dd | 1 | '\" t |
c11b1abf | 2 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
4d2b74dd | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
4d2b74dd MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
4d2b74dd MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
17 | .\" the use of the information contained herein. The author(s) may not |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
4d2b74dd MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
4d2b74dd | 25 | .\" |
99e603bd | 26 | .TH INOTIFY 7 2013-02-25 "Linux" "Linux Programmer's Manual" |
4d2b74dd | 27 | .SH NAME |
3a20b4ca | 28 | inotify \- monitoring file system events |
4d2b74dd MK |
29 | .SH DESCRIPTION |
30 | The | |
c13182ef | 31 | .I inotify |
4d2b74dd MK |
32 | API provides a mechanism for monitoring file system events. |
33 | Inotify can be used to monitor individual files, | |
34 | or to monitor directories. | |
35 | When a directory is monitored, inotify will return events | |
36 | for the directory itself, and for files inside the directory. | |
37 | ||
c13182ef | 38 | The following system calls are used with this API: |
43bb5faf | 39 | .BR inotify_init (2) |
c5571b61 | 40 | (or |
43bb5faf | 41 | .BR inotify_init1 (2)), |
63f6a20a MK |
42 | .BR inotify_add_watch (2), |
43 | .BR inotify_rm_watch (2), | |
44 | .BR read (2), | |
c13182ef | 45 | and |
63f6a20a | 46 | .BR close (2). |
4d2b74dd MK |
47 | |
48 | .BR inotify_init (2) | |
c13182ef | 49 | creates an inotify instance and returns a file descriptor |
a2cc46ca | 50 | referring to the inotify instance. |
43bb5faf MK |
51 | The more recent |
52 | .BR inotify_init1 (2) | |
53 | is like | |
54 | .BR inotify_init (2), | |
55 | but provides some extra functionality. | |
4d2b74dd MK |
56 | |
57 | .BR inotify_add_watch (2) | |
a2cc46ca | 58 | manipulates the "watch list" associated with an inotify instance. |
3a065ac0 | 59 | Each item ("watch") in the watch list specifies the pathname of |
c13182ef | 60 | a file or directory, |
4d2b74dd MK |
61 | along with some set of events that the kernel should monitor for the |
62 | file referred to by that pathname. | |
63f6a20a | 63 | .BR inotify_add_watch (2) |
4d2b74dd MK |
64 | either creates a new watch item, or modifies an existing watch. |
65 | Each watch has a unique "watch descriptor", an integer | |
66 | returned by | |
63f6a20a | 67 | .BR inotify_add_watch (2) |
4d2b74dd MK |
68 | when the watch is created. |
69 | ||
70 | .BR inotify_rm_watch (2) | |
71 | removes an item from an inotify watch list. | |
72 | ||
c13182ef | 73 | When all file descriptors referring to an inotify |
a2cc46ca | 74 | instance have been closed, |
c13182ef | 75 | the underlying object and its resources are |
3b777aff | 76 | freed for reuse by the kernel; |
4d2b74dd MK |
77 | all associated watches are automatically freed. |
78 | ||
79 | To determine what events have occurred, an application | |
80 | .BR read (2)s | |
81 | from the inotify file descriptor. | |
c13182ef | 82 | If no events have so far occurred, then, |
11da88fb | 83 | assuming a blocking file descriptor, |
63f6a20a | 84 | .BR read (2) |
01538d0d MK |
85 | will block until at least one event occurs |
86 | (unless interrupted by a signal, | |
87 | in which case the call fails with the error | |
88 | .BR EINTR ; | |
89 | see | |
90 | .BR signal (7)). | |
4d2b74dd MK |
91 | |
92 | Each successful | |
63f6a20a | 93 | .BR read (2) |
4d2b74dd | 94 | returns a buffer containing one or more of the following structures: |
a08ea57c | 95 | .in +4n |
4d2b74dd MK |
96 | .nf |
97 | ||
98 | struct inotify_event { | |
99 | int wd; /* Watch descriptor */ | |
24bbe02c MK |
100 | .\" FIXME . The type of the 'wd' field should probably be "int32_t". |
101 | .\" I submitted a patch to fix this. See the LKML thread | |
102 | .\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 | |
6e6231c1 | 103 | .\" Glibc bug filed: http://sources.redhat.com/bugzilla/show_bug.cgi?id=7040 |
4d2b74dd | 104 | uint32_t mask; /* Mask of events */ |
c13182ef | 105 | uint32_t cookie; /* Unique cookie associating related |
4d2b74dd | 106 | events (for rename(2)) */ |
84c517a4 | 107 | uint32_t len; /* Size of \fIname\fP field */ |
4d2b74dd MK |
108 | char name[]; /* Optional null-terminated name */ |
109 | }; | |
110 | .fi | |
a08ea57c | 111 | .in |
4d2b74dd MK |
112 | |
113 | .I wd | |
114 | identifies the watch for which this event occurs. | |
c13182ef | 115 | It is one of the watch descriptors returned by a previous call to |
63f6a20a | 116 | .BR inotify_add_watch (2). |
4d2b74dd MK |
117 | |
118 | .I mask | |
119 | contains bits that describe the event that occurred (see below). | |
120 | ||
121 | .I cookie | |
122 | is a unique integer that connects related events. | |
123 | Currently this is only used for rename events, and | |
124 | allows the resulting pair of | |
bc636d8a | 125 | .B IN_MOVED_FROM |
c13182ef | 126 | and |
bc636d8a | 127 | .B IN_MOVED_TO |
4d2b74dd | 128 | events to be connected by the application. |
591b7a5f MK |
129 | For all other event types, |
130 | .I cookie | |
131 | is set to 0. | |
4d2b74dd | 132 | |
c13182ef | 133 | The |
4d2b74dd MK |
134 | .I name |
135 | field is only present when an event is returned | |
c13182ef | 136 | for a file inside a watched directory; |
4d2b74dd | 137 | it identifies the file pathname relative to the watched directory. |
c13182ef | 138 | This pathname is null-terminated, |
ad31978e | 139 | and may include further null bytes to align subsequent reads to a |
4d2b74dd MK |
140 | suitable address boundary. |
141 | ||
142 | The | |
143 | .I len | |
c13182ef | 144 | field counts all of the bytes in |
4d2b74dd | 145 | .IR name , |
c13182ef | 146 | including the null bytes; |
4d2b74dd MK |
147 | the length of each |
148 | .I inotify_event | |
149 | structure is thus | |
655684a9 | 150 | .IR "sizeof(struct inotify_event)+len" . |
c7e3ee6f | 151 | |
988db661 | 152 | The behavior when the buffer given to |
c7e3ee6f | 153 | .BR read (2) |
988db661 | 154 | is too small to return information about the next event depends |
c7e3ee6f MK |
155 | on the kernel version: in kernels before 2.6.21, |
156 | .BR read (2) | |
157 | returns 0; since kernel 2.6.21, | |
158 | .BR read (2) | |
159 | fails with the error | |
160 | .BR EINVAL . | |
4ba272b3 MK |
161 | Specifying a buffer of size |
162 | ||
163 | sizeof(struct inotify_event) + NAME_MAX + 1 | |
164 | ||
165 | will be sufficient to read at least one event. | |
4d2b74dd | 166 | .SS inotify events |
c13182ef | 167 | The |
4d2b74dd MK |
168 | .BR inotify_add_watch (2) |
169 | .I mask | |
c13182ef | 170 | argument and the |
4d2b74dd MK |
171 | .I mask |
172 | field of the | |
173 | .I inotify_event | |
174 | structure returned when | |
175 | .BR read (2)ing | |
176 | an inotify file descriptor are both bit masks identifying | |
177 | inotify events. | |
178 | The following bits can be specified in | |
179 | .I mask | |
180 | when calling | |
63f6a20a | 181 | .BR inotify_add_watch (2) |
c13182ef | 182 | and may be returned in the |
4d2b74dd MK |
183 | .I mask |
184 | field returned by | |
63f6a20a | 185 | .BR read (2): |
3f174f7d MK |
186 | .RS 4 |
187 | .sp | |
188 | .PD 0 | |
189 | .TP 18 | |
190 | .B IN_ACCESS | |
191 | File was accessed (read) (*). | |
192 | .TP | |
193 | .B IN_ATTRIB | |
3a5c365a MK |
194 | Metadata changed, e.g., permissions, timestamps, extended attributes, |
195 | link count (since Linux 2.6.25), UID, GID, etc. (*). | |
3f174f7d MK |
196 | .TP |
197 | .B IN_CLOSE_WRITE | |
198 | File opened for writing was closed (*). | |
199 | .TP | |
200 | .B IN_CLOSE_NOWRITE | |
201 | File not opened for writing was closed (*). | |
202 | .TP | |
203 | .B IN_CREATE | |
204 | File/directory created in watched directory (*). | |
205 | .TP | |
206 | .B IN_DELETE | |
207 | File/directory deleted from watched directory (*). | |
208 | .TP | |
209 | .B IN_DELETE_SELF | |
210 | Watched file/directory was itself deleted. | |
211 | .TP | |
212 | .B IN_MODIFY | |
213 | File was modified (*). | |
214 | .TP | |
215 | .B IN_MOVE_SELF | |
216 | Watched file/directory was itself moved. | |
217 | .TP | |
218 | .B IN_MOVED_FROM | |
219 | File moved out of watched directory (*). | |
220 | .TP | |
221 | .B IN_MOVED_TO | |
222 | File moved into watched directory (*). | |
223 | .TP | |
224 | .B IN_OPEN | |
225 | File was opened (*). | |
226 | .PD | |
227 | .RE | |
4d2b74dd | 228 | .PP |
c13182ef MK |
229 | When monitoring a directory, |
230 | the events marked with an asterisk (*) above can occur for | |
4d2b74dd MK |
231 | files in the directory, in which case the |
232 | .I name | |
233 | field in the returned | |
234 | .I inotify_event | |
235 | structure identifies the name of the file within the directory. | |
236 | .PP | |
237 | The | |
238 | .B IN_ALL_EVENTS | |
239 | macro is defined as a bit mask of all of the above events. | |
240 | This macro can be used as the | |
241 | .I mask | |
242 | argument when calling | |
63f6a20a | 243 | .BR inotify_add_watch (2). |
4d2b74dd MK |
244 | |
245 | Two additional convenience macros are | |
246 | .BR IN_MOVE , | |
247 | which equates to | |
248 | IN_MOVED_FROM|IN_MOVED_TO, | |
249 | and | |
fe252985 | 250 | .BR IN_CLOSE , |
4d2b74dd MK |
251 | which equates to |
252 | IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. | |
253 | .PP | |
c13182ef | 254 | The following further bits can be specified in |
4d2b74dd MK |
255 | .I mask |
256 | when calling | |
63f6a20a | 257 | .BR inotify_add_watch (2): |
3f174f7d MK |
258 | .RS 4 |
259 | .sp | |
260 | .PD 0 | |
261 | .TP 18 | |
31daf529 MK |
262 | .BR IN_DONT_FOLLOW " (since Linux 2.6.15)" |
263 | Don't dereference \fIpathname\fP if it is a symbolic link. | |
dda869a4 | 264 | .TP |
0ff2cc88 | 265 | .BR IN_EXCL_UNLINK " (since Linux 2.6.36)" |
b3ad7609 MK |
266 | .\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 |
267 | By default, when watching events on the children of a directory, | |
268 | events are generated for children even after they have been unlinked | |
269 | from the directory. | |
270 | This can result in large numbers of uninteresting events for | |
271 | some applications (e.g., if watching | |
272 | .IR /tmp , | |
273 | in which many applications create temporary files whose | |
274 | names are immediately unlinked). | |
275 | Specifying | |
276 | .B IN_EXCL_UNLINK | |
277 | changes the default behavior, | |
278 | so that events are not generated for children after | |
279 | they have been unlinked from the watched directory. | |
280 | .TP | |
dda869a4 MK |
281 | .B IN_MASK_ADD |
282 | Add (OR) events to watch mask for this pathname if | |
283 | it already exists (instead of replacing mask). | |
284 | .TP | |
285 | .B IN_ONESHOT | |
286 | Monitor \fIpathname\fP for one event, then remove from | |
287 | watch list. | |
288 | .TP | |
31daf529 MK |
289 | .BR IN_ONLYDIR " (since Linux 2.6.15)" |
290 | Only watch \fIpathname\fP if it is a directory. | |
3f174f7d MK |
291 | .PD |
292 | .RE | |
4d2b74dd MK |
293 | .PP |
294 | The following bits may be set in the | |
295 | .I mask | |
296 | field returned by | |
63f6a20a | 297 | .BR read (2): |
3f174f7d MK |
298 | .RS 4 |
299 | .sp | |
300 | .PD 0 | |
301 | .TP 18 | |
dda869a4 MK |
302 | .B IN_IGNORED |
303 | Watch was removed explicitly (\fBinotify_rm_watch\fP(2)) | |
304 | or automatically (file was deleted, or file system was unmounted). | |
305 | .TP | |
306 | .B IN_ISDIR | |
307 | Subject of this event is a directory. | |
308 | .TP | |
309 | .B IN_Q_OVERFLOW | |
310 | Event queue overflowed (\fIwd\fP is \-1 for this event). | |
311 | .TP | |
312 | .B IN_UNMOUNT | |
313 | File system containing watched object was unmounted. | |
3f174f7d MK |
314 | .PD |
315 | .RE | |
4d2b74dd | 316 | .SS /proc interfaces |
c13182ef | 317 | The following interfaces can be used to limit the amount of |
4d2b74dd MK |
318 | kernel memory consumed by inotify: |
319 | .TP | |
0daa9e92 | 320 | .I /proc/sys/fs/inotify/max_queued_events |
4d2b74dd MK |
321 | The value in this file is used when an application calls |
322 | .BR inotify_init (2) | |
c13182ef | 323 | to set an upper limit on the number of events that can be |
4d2b74dd MK |
324 | queued to the corresponding inotify instance. |
325 | Events in excess of this limit are dropped, but an | |
326 | .B IN_Q_OVERFLOW | |
327 | event is always generated. | |
328 | .TP | |
0daa9e92 | 329 | .I /proc/sys/fs/inotify/max_user_instances |
c13182ef | 330 | This specifies an upper limit on the number of inotify instances |
4d2b74dd MK |
331 | that can be created per real user ID. |
332 | .TP | |
0daa9e92 | 333 | .I /proc/sys/fs/inotify/max_user_watches |
31546b46 VN |
334 | This specifies an upper limit on the number of watches |
335 | that can be created per real user ID. | |
47297adb | 336 | .SH VERSIONS |
2b2581ee MK |
337 | Inotify was merged into the 2.6.13 Linux kernel. |
338 | The required library interfaces were added to glibc in version 2.4. | |
339 | .RB ( IN_DONT_FOLLOW , | |
340 | .BR IN_MASK_ADD , | |
341 | and | |
342 | .B IN_ONLYDIR | |
343 | were only added in version 2.5.) | |
47297adb | 344 | .SH CONFORMING TO |
8382f16d | 345 | The inotify API is Linux-specific. |
47297adb | 346 | .SH NOTES |
4d2b74dd MK |
347 | Inotify file descriptors can be monitored using |
348 | .BR select (2), | |
349 | .BR poll (2), | |
c13182ef | 350 | and |
2315114c | 351 | .BR epoll (7). |
0000daa5 MK |
352 | When an event is available, the file descriptor indicates as readable. |
353 | ||
354 | Since Linux 2.6.25, | |
355 | signal-driven I/O notification is available for inotify file descriptors; | |
356 | see the discussion of | |
357 | .B F_SETFL | |
358 | (for setting the | |
359 | .B O_ASYNC | |
360 | flag), | |
361 | .BR F_SETOWN , | |
362 | and | |
363 | .B F_SETSIG | |
364 | in | |
365 | .BR fcntl (2). | |
366 | The | |
367 | .I siginfo_t | |
368 | structure (described in | |
369 | .BR sigaction (2)) | |
370 | that is passed to the signal handler has the following fields set: | |
371 | .IR si_fd | |
372 | is set to the inotify file descriptor number; | |
373 | .IR si_signo | |
374 | is set to the signal number; | |
375 | .IR si_code | |
376 | is set to | |
377 | .BR POLL_IN ; | |
378 | and | |
379 | .B POLLIN | |
380 | is set in | |
381 | .IR si_band . | |
4d2b74dd | 382 | |
c13182ef MK |
383 | If successive output inotify events produced on the |
384 | inotify file descriptor are identical (same | |
385 | .IR wd , | |
386 | .IR mask , | |
4d2b74dd MK |
387 | .IR cookie , |
388 | and | |
389 | .IR name ) | |
6f0ab035 MK |
390 | then they are coalesced into a single event if the |
391 | older event has not yet been read (but see BUGS). | |
4d2b74dd | 392 | |
c13182ef MK |
393 | The events returned by reading from an inotify file descriptor |
394 | form an ordered queue. | |
395 | Thus, for example, it is guaranteed that when renaming from | |
396 | one directory to another, events will be produced in the | |
4d2b74dd MK |
397 | correct order on the inotify file descriptor. |
398 | ||
399 | The | |
400 | .B FIONREAD | |
63f6a20a | 401 | .BR ioctl (2) |
c13182ef | 402 | returns the number of bytes available to read from an |
4d2b74dd | 403 | inotify file descriptor. |
613836aa | 404 | .SS Limitations and caveats |
4d2b74dd MK |
405 | Inotify monitoring of directories is not recursive: |
406 | to monitor subdirectories under a directory, | |
407 | additional watches must be created. | |
613836aa MK |
408 | This can take a significant amount time for large directory trees. |
409 | ||
4d2ddb4e MK |
410 | The inotify API provides no information about the user or process that |
411 | triggered the inotify event. | |
99e603bd MK |
412 | In particular, there is no easy |
413 | way for a process that is monitoring events via inotify | |
414 | to distinguish events that it triggers | |
415 | itself from those that are triggered by other processes. | |
4d2ddb4e | 416 | |
613836aa MK |
417 | Note that the event queue can overflow. |
418 | In this case, events are lost. | |
09fa72fa | 419 | Robust applications should handle the possibility of |
613836aa MK |
420 | lost events gracefully. |
421 | ||
422 | The inotify API identifies affected files by filename. | |
423 | However, by the time an application processes an inotify event, | |
424 | the filename may already have been deleted or renamed. | |
425 | ||
426 | If monitoring an entire directory subtree, | |
427 | and a new subdirectory is created in that tree, | |
428 | be aware that by the time you create a watch for the new subdirectory, | |
429 | new files may already have been created in the subdirectory. | |
430 | Therefore, you may want to scan the contents of the subdirectory | |
431 | immediately after adding the watch. | |
47297adb | 432 | .SH BUGS |
ed7b0235 MK |
433 | In kernels before 2.6.16, the |
434 | .B IN_ONESHOT | |
c13182ef | 435 | .I mask |
ed7b0235 | 436 | flag does not work. |
6f0ab035 MK |
437 | |
438 | Before kernel 2.6.25, | |
9ed6b517 | 439 | the kernel code that was intended to coalesce successive identical events |
6f0ab035 MK |
440 | (i.e., the two most recent events could potentially be coalesced |
441 | if the older had not yet been read) | |
442 | instead checked if the most recent event could be coalesced with the | |
443 | .I oldest | |
444 | unread event. | |
47297adb | 445 | .SH SEE ALSO |
4d2b74dd MK |
446 | .BR inotify_add_watch (2), |
447 | .BR inotify_init (2), | |
43bb5faf | 448 | .BR inotify_init1 (2), |
4d2b74dd MK |
449 | .BR inotify_rm_watch (2), |
450 | .BR read (2), | |
173fe7e7 DP |
451 | .BR stat (2) |
452 | ||
453 | .IR Documentation/filesystems/inotify.txt | |
454 | in the Linux kernel source tree |