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