| 1 |
.\" Copyright 2006-2014, Michael Kerrisk <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH inotify 7 2026-02-14 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
inotify \- monitoring filesystem events |
| 9 |
.SH DESCRIPTION |
| 10 |
The |
| 11 |
.I inotify |
| 12 |
API provides a mechanism for monitoring filesystem events. |
| 13 |
Inotify can be used to monitor individual files, |
| 14 |
or to monitor directories. |
| 15 |
When a directory is monitored, inotify will return events |
| 16 |
for the directory itself, and for files inside the directory. |
| 17 |
.P |
| 18 |
The following system calls are used with this API: |
| 19 |
.IP \[bu] 3 |
| 20 |
.BR inotify_init (2) |
| 21 |
creates an inotify instance and returns a file descriptor |
| 22 |
referring to the inotify instance. |
| 23 |
The more recent |
| 24 |
.BR inotify_init1 (2) |
| 25 |
is like |
| 26 |
.BR inotify_init (2), |
| 27 |
but has a |
| 28 |
.I flags |
| 29 |
argument that provides access to some extra functionality. |
| 30 |
.IP \[bu] |
| 31 |
.BR inotify_add_watch (2) |
| 32 |
manipulates the "watch list" associated with an inotify instance. |
| 33 |
Each item ("watch") in the watch list specifies the pathname of |
| 34 |
a file or directory, |
| 35 |
along with some set of events that the kernel should monitor for the |
| 36 |
file referred to by that pathname. |
| 37 |
.BR inotify_add_watch (2) |
| 38 |
either creates a new watch item, or modifies an existing watch. |
| 39 |
Each watch has a unique "watch descriptor", an integer |
| 40 |
returned by |
| 41 |
.BR inotify_add_watch (2) |
| 42 |
when the watch is created. |
| 43 |
.IP \[bu] |
| 44 |
When events occur for monitored files and directories, |
| 45 |
those events are made available to the application as structured data that |
| 46 |
can be read from the inotify file descriptor using |
| 47 |
.BR read (2) |
| 48 |
(see below). |
| 49 |
.IP \[bu] |
| 50 |
.BR inotify_rm_watch (2) |
| 51 |
removes an item from an inotify watch list. |
| 52 |
.IP \[bu] |
| 53 |
When all file descriptors referring to an inotify |
| 54 |
instance have been closed (using |
| 55 |
.BR close (2)), |
| 56 |
the underlying object and its resources are |
| 57 |
freed for reuse by the kernel; |
| 58 |
all associated watches are automatically freed. |
| 59 |
.P |
| 60 |
With careful programming, |
| 61 |
an application can use inotify to efficiently monitor and cache |
| 62 |
the state of a set of filesystem objects. |
| 63 |
However, robust applications should allow for the fact that bugs |
| 64 |
in the monitoring logic or races of the kind described below |
| 65 |
may leave the cache inconsistent with the filesystem state. |
| 66 |
It is probably wise to do some consistency checking, |
| 67 |
and rebuild the cache when inconsistencies are detected. |
| 68 |
.SS Reading events from an inotify file descriptor |
| 69 |
To determine what events have occurred, an application |
| 70 |
.BR read (2)s |
| 71 |
from the inotify file descriptor. |
| 72 |
If no events have so far occurred, then, |
| 73 |
assuming a blocking file descriptor, |
| 74 |
.BR read (2) |
| 75 |
will block until at least one event occurs |
| 76 |
(unless interrupted by a signal, |
| 77 |
in which case the call fails with the error |
| 78 |
.BR EINTR ; |
| 79 |
see |
| 80 |
.BR signal (7)). |
| 81 |
.P |
| 82 |
Each successful |
| 83 |
.BR read (2) |
| 84 |
returns a buffer containing one or more of the following structures: |
| 85 |
.P |
| 86 |
.in +4n |
| 87 |
.EX |
| 88 |
struct inotify_event { |
| 89 |
int wd; /* Watch descriptor */ |
| 90 |
.\" FIXME . The type of the 'wd' field should probably be "int32_t". |
| 91 |
.\" I submitted a patch to fix this. See the LKML thread |
| 92 |
.\" "[patch] Fix type errors in inotify interfaces", 18 Nov 2008 |
| 93 |
.\" glibc bug filed: https://www.sourceware.org/bugzilla/show_bug.cgi?id=7040 |
| 94 |
uint32_t mask; /* Mask describing event */ |
| 95 |
uint32_t cookie; /* Unique cookie associating related |
| 96 |
events (for rename(2)) */ |
| 97 |
uint32_t len; /* Size of \f[I]name\f[] field */ |
| 98 |
char name[]; /* Optional null\-terminated name */ |
| 99 |
}; |
| 100 |
.EE |
| 101 |
.in |
| 102 |
.P |
| 103 |
.I wd |
| 104 |
identifies the watch for which this event occurs. |
| 105 |
It is one of the watch descriptors returned by a previous call to |
| 106 |
.BR inotify_add_watch (2). |
| 107 |
.P |
| 108 |
.I mask |
| 109 |
contains bits that describe the event that occurred (see below). |
| 110 |
.P |
| 111 |
.I cookie |
| 112 |
is a unique integer that connects related events. |
| 113 |
Currently, this is used only for rename events, and |
| 114 |
allows the resulting pair of |
| 115 |
.B IN_MOVED_FROM |
| 116 |
and |
| 117 |
.B IN_MOVED_TO |
| 118 |
events to be connected by the application. |
| 119 |
For all other event types, |
| 120 |
.I cookie |
| 121 |
is set to 0. |
| 122 |
.P |
| 123 |
The |
| 124 |
.I name |
| 125 |
field is present only when an event is returned |
| 126 |
for a file inside a watched directory; |
| 127 |
it identifies the filename within the watched directory. |
| 128 |
This filename is null-terminated, |
| 129 |
and may include further null bytes (\[aq]\[rs]0\[aq]) |
| 130 |
to align subsequent reads to a suitable address boundary. |
| 131 |
.P |
| 132 |
The |
| 133 |
.I len |
| 134 |
field counts all of the bytes in |
| 135 |
.IR name , |
| 136 |
including the null bytes; |
| 137 |
the size of each |
| 138 |
.I inotify_event |
| 139 |
structure is thus |
| 140 |
.IR "sizeof(struct inotify_event)+size" . |
| 141 |
.P |
| 142 |
The behavior when the buffer given to |
| 143 |
.BR read (2) |
| 144 |
is too small to return information about the next event depends |
| 145 |
on the kernel version: before Linux 2.6.21, |
| 146 |
.BR read (2) |
| 147 |
returns 0; since Linux 2.6.21, |
| 148 |
.BR read (2) |
| 149 |
fails with the error |
| 150 |
.BR EINVAL . |
| 151 |
Specifying a buffer of size |
| 152 |
.P |
| 153 |
.in +4n |
| 154 |
.EX |
| 155 |
sizeof(struct inotify_event) + NAME_MAX + 1 |
| 156 |
.EE |
| 157 |
.in |
| 158 |
.P |
| 159 |
will be sufficient to read at least one event. |
| 160 |
.SS inotify events |
| 161 |
The |
| 162 |
.BR inotify_add_watch (2) |
| 163 |
.I mask |
| 164 |
argument and the |
| 165 |
.I mask |
| 166 |
field of the |
| 167 |
.I inotify_event |
| 168 |
structure returned when |
| 169 |
.BR read (2)ing |
| 170 |
an inotify file descriptor are both bit masks identifying |
| 171 |
inotify events. |
| 172 |
The following bits can be specified in |
| 173 |
.I mask |
| 174 |
when calling |
| 175 |
.BR inotify_add_watch (2) |
| 176 |
and may be returned in the |
| 177 |
.I mask |
| 178 |
field returned by |
| 179 |
.BR read (2): |
| 180 |
.RS 4 |
| 181 |
.TP |
| 182 |
.BR IN_ACCESS " (+)" |
| 183 |
File was accessed (e.g., |
| 184 |
.BR read (2), |
| 185 |
.BR execve (2)). |
| 186 |
.TP |
| 187 |
.BR IN_ATTRIB " (*)" |
| 188 |
Metadata changed\[em]for example, permissions (e.g., |
| 189 |
.BR chmod (2)), |
| 190 |
timestamps (e.g., |
| 191 |
.BR utimensat (2)), |
| 192 |
extended attributes |
| 193 |
.RB ( setxattr (2)), |
| 194 |
link count |
| 195 |
(since Linux 2.6.25; |
| 196 |
e.g., |
| 197 |
.\" FIXME . |
| 198 |
.\" Events do not occur for link count changes on a file inside a monitored |
| 199 |
.\" directory. This differs from other metadata changes for files inside |
| 200 |
.\" a monitored directory. |
| 201 |
for the target of |
| 202 |
.BR link (2) |
| 203 |
and for |
| 204 |
.BR unlink (2)), |
| 205 |
and user/group ID (e.g., |
| 206 |
.BR chown (2)). |
| 207 |
.TP |
| 208 |
.BR IN_CLOSE_WRITE " (+)" |
| 209 |
File opened for writing was closed. |
| 210 |
.TP |
| 211 |
.BR IN_CLOSE_NOWRITE " (*)" |
| 212 |
File or directory not opened for writing was closed. |
| 213 |
.TP |
| 214 |
.BR IN_CREATE " (+)" |
| 215 |
File/directory created in watched directory (e.g., |
| 216 |
.BR open (2) |
| 217 |
.BR O_CREAT , |
| 218 |
.BR mkdir (2), |
| 219 |
.BR link (2), |
| 220 |
.BR symlink (2), |
| 221 |
.BR bind (2) |
| 222 |
on a UNIX domain socket). |
| 223 |
.TP |
| 224 |
.BR IN_DELETE " (+)" |
| 225 |
File/directory deleted from watched directory. |
| 226 |
.TP |
| 227 |
.B IN_DELETE_SELF |
| 228 |
Watched file/directory was itself deleted. |
| 229 |
(This event also occurs if an object is moved to another filesystem, |
| 230 |
since |
| 231 |
.BR mv (1) |
| 232 |
in effect copies the file to the other filesystem and |
| 233 |
then deletes it from the original filesystem.) |
| 234 |
In addition, an |
| 235 |
.B IN_IGNORED |
| 236 |
event will subsequently be generated for the watch descriptor. |
| 237 |
.TP |
| 238 |
.BR IN_MODIFY " (+)" |
| 239 |
File was modified (e.g., |
| 240 |
.BR write (2), |
| 241 |
.BR truncate (2)). |
| 242 |
.TP |
| 243 |
.B IN_MOVE_SELF |
| 244 |
Watched file/directory was itself moved. |
| 245 |
.TP |
| 246 |
.BR IN_MOVED_FROM " (+)" |
| 247 |
Generated for the directory containing the old filename |
| 248 |
when a file is renamed. |
| 249 |
.TP |
| 250 |
.BR IN_MOVED_TO " (+)" |
| 251 |
Generated for the directory containing the new filename |
| 252 |
when a file is renamed. |
| 253 |
.TP |
| 254 |
.BR IN_OPEN " (*)" |
| 255 |
File or directory was opened. |
| 256 |
.RE |
| 257 |
.P |
| 258 |
Inotify monitoring is inode-based: when monitoring a file |
| 259 |
(but not when monitoring the directory containing a file), |
| 260 |
an event can be generated for activity on any link to the file |
| 261 |
(in the same or a different directory). |
| 262 |
.P |
| 263 |
When monitoring a directory: |
| 264 |
.IP \[bu] 3 |
| 265 |
the events marked above with an asterisk (*) can occur both |
| 266 |
for the directory itself and for objects inside the directory; |
| 267 |
and |
| 268 |
.IP \[bu] |
| 269 |
the events marked with a plus sign (+) occur only for objects |
| 270 |
inside the directory (not for the directory itself). |
| 271 |
.P |
| 272 |
.IR Note : |
| 273 |
when monitoring a directory, |
| 274 |
events are not generated for the files inside the directory |
| 275 |
when the events are performed via a pathname (i.e., a link) |
| 276 |
that lies outside the monitored directory. |
| 277 |
.P |
| 278 |
When events are generated for objects inside a watched directory, the |
| 279 |
.I name |
| 280 |
field in the returned |
| 281 |
.I inotify_event |
| 282 |
structure identifies the name of the file within the directory. |
| 283 |
.P |
| 284 |
The |
| 285 |
.B IN_ALL_EVENTS |
| 286 |
macro is defined as a bit mask of all of the above events. |
| 287 |
This macro can be used as the |
| 288 |
.I mask |
| 289 |
argument when calling |
| 290 |
.BR inotify_add_watch (2). |
| 291 |
.P |
| 292 |
Two additional convenience macros are defined: |
| 293 |
.RS 4 |
| 294 |
.TP |
| 295 |
.B IN_MOVE |
| 296 |
Equates to |
| 297 |
.BR "IN_MOVED_FROM | IN_MOVED_TO" . |
| 298 |
.TP |
| 299 |
.B IN_CLOSE |
| 300 |
Equates to |
| 301 |
.BR "IN_CLOSE_WRITE | IN_CLOSE_NOWRITE" . |
| 302 |
.RE |
| 303 |
.P |
| 304 |
The following further bits can be specified in |
| 305 |
.I mask |
| 306 |
when calling |
| 307 |
.BR inotify_add_watch (2): |
| 308 |
.RS 4 |
| 309 |
.TP |
| 310 |
.BR IN_DONT_FOLLOW " (since Linux 2.6.15)" |
| 311 |
Don't dereference |
| 312 |
.I pathname |
| 313 |
if it is a symbolic link. |
| 314 |
.TP |
| 315 |
.BR IN_EXCL_UNLINK " (since Linux 2.6.36)" |
| 316 |
.\" commit 8c1934c8d70b22ca8333b216aec6c7d09fdbd6a6 |
| 317 |
By default, when watching events on the children of a directory, |
| 318 |
events are generated for children even after they have been unlinked |
| 319 |
from the directory. |
| 320 |
This can result in large numbers of uninteresting events for |
| 321 |
some applications (e.g., if watching |
| 322 |
.IR /tmp , |
| 323 |
in which many applications create temporary files whose |
| 324 |
names are immediately unlinked). |
| 325 |
Specifying |
| 326 |
.B IN_EXCL_UNLINK |
| 327 |
changes the default behavior, |
| 328 |
so that events are not generated for children after |
| 329 |
they have been unlinked from the watched directory. |
| 330 |
.TP |
| 331 |
.B IN_MASK_ADD |
| 332 |
If a watch instance already exists for the filesystem object corresponding to |
| 333 |
.IR pathname , |
| 334 |
add (OR) the events in |
| 335 |
.I mask |
| 336 |
to the watch mask (instead of replacing the mask); |
| 337 |
the error |
| 338 |
.B EINVAL |
| 339 |
results if |
| 340 |
.B IN_MASK_CREATE |
| 341 |
is also specified. |
| 342 |
.TP |
| 343 |
.B IN_ONESHOT |
| 344 |
Monitor the filesystem object corresponding to |
| 345 |
.I pathname |
| 346 |
for one event, then remove from |
| 347 |
watch list. |
| 348 |
.TP |
| 349 |
.BR IN_ONLYDIR " (since Linux 2.6.15)" |
| 350 |
Watch |
| 351 |
.I pathname |
| 352 |
only if it is a directory; |
| 353 |
the error |
| 354 |
.B ENOTDIR |
| 355 |
results if |
| 356 |
.I pathname |
| 357 |
is not a directory. |
| 358 |
Using this flag provides an application with a race-free way of |
| 359 |
ensuring that the monitored object is a directory. |
| 360 |
.TP |
| 361 |
.BR IN_MASK_CREATE " (since Linux 4.18)" |
| 362 |
Watch |
| 363 |
.I pathname |
| 364 |
only if it does not already have a watch associated with it; |
| 365 |
the error |
| 366 |
.B EEXIST |
| 367 |
results if |
| 368 |
.I pathname |
| 369 |
is already being watched. |
| 370 |
.IP |
| 371 |
Using this flag provides an application with a way of ensuring |
| 372 |
that new watches do not modify existing ones. |
| 373 |
This is useful because multiple paths may refer to the same inode, |
| 374 |
and multiple calls to |
| 375 |
.BR inotify_add_watch (2) |
| 376 |
without this flag may clobber existing watch masks. |
| 377 |
.RE |
| 378 |
.P |
| 379 |
The following bits may be set in the |
| 380 |
.I mask |
| 381 |
field returned by |
| 382 |
.BR read (2): |
| 383 |
.RS 4 |
| 384 |
.TP |
| 385 |
.B IN_IGNORED |
| 386 |
Watch was removed explicitly |
| 387 |
.RB ( inotify_rm_watch (2)) |
| 388 |
or automatically (file was deleted, or filesystem was unmounted). |
| 389 |
See also BUGS. |
| 390 |
.TP |
| 391 |
.B IN_ISDIR |
| 392 |
Subject of this event is a directory. |
| 393 |
.TP |
| 394 |
.B IN_Q_OVERFLOW |
| 395 |
Event queue overflowed |
| 396 |
.RI ( wd |
| 397 |
is \-1 for this event). |
| 398 |
.TP |
| 399 |
.B IN_UNMOUNT |
| 400 |
Filesystem containing watched object was unmounted. |
| 401 |
In addition, an |
| 402 |
.B IN_IGNORED |
| 403 |
event will subsequently be generated for the watch descriptor. |
| 404 |
.RE |
| 405 |
.SS Examples |
| 406 |
Suppose an application is watching the directory |
| 407 |
.I dir |
| 408 |
and the file |
| 409 |
.I dir/myfile |
| 410 |
for all events. |
| 411 |
The examples below show some events that will be generated |
| 412 |
for these two objects. |
| 413 |
.RS 4 |
| 414 |
.TP |
| 415 |
fd = open("dir/myfile", O_RDWR); |
| 416 |
Generates |
| 417 |
.B IN_OPEN |
| 418 |
events for both |
| 419 |
.I dir |
| 420 |
and |
| 421 |
.IR dir/myfile . |
| 422 |
.TP |
| 423 |
read(fd, buf, count); |
| 424 |
Generates |
| 425 |
.B IN_ACCESS |
| 426 |
events for both |
| 427 |
.I dir |
| 428 |
and |
| 429 |
.IR dir/myfile . |
| 430 |
.TP |
| 431 |
write(fd, buf, count); |
| 432 |
Generates |
| 433 |
.B IN_MODIFY |
| 434 |
events for both |
| 435 |
.I dir |
| 436 |
and |
| 437 |
.IR dir/myfile . |
| 438 |
.TP |
| 439 |
fchmod(fd, mode); |
| 440 |
Generates |
| 441 |
.B IN_ATTRIB |
| 442 |
events for both |
| 443 |
.I dir |
| 444 |
and |
| 445 |
.IR dir/myfile . |
| 446 |
.TP |
| 447 |
close(fd); |
| 448 |
Generates |
| 449 |
.B IN_CLOSE_WRITE |
| 450 |
events for both |
| 451 |
.I dir |
| 452 |
and |
| 453 |
.IR dir/myfile . |
| 454 |
.RE |
| 455 |
.P |
| 456 |
Suppose an application is watching the directories |
| 457 |
.I dir1 |
| 458 |
and |
| 459 |
.IR dir2 , |
| 460 |
and the file |
| 461 |
.IR dir1/myfile . |
| 462 |
The following examples show some events that may be generated. |
| 463 |
.RS 4 |
| 464 |
.TP |
| 465 |
link("dir1/myfile", "dir2/new"); |
| 466 |
Generates an |
| 467 |
.B IN_ATTRIB |
| 468 |
event for |
| 469 |
.I myfile |
| 470 |
and an |
| 471 |
.B IN_CREATE |
| 472 |
event for |
| 473 |
.IR dir2 . |
| 474 |
.TP |
| 475 |
rename("dir1/myfile", "dir2/myfile"); |
| 476 |
Generates an |
| 477 |
.B IN_MOVED_FROM |
| 478 |
event for |
| 479 |
.IR dir1 , |
| 480 |
an |
| 481 |
.B IN_MOVED_TO |
| 482 |
event for |
| 483 |
.IR dir2 , |
| 484 |
and an |
| 485 |
.B IN_MOVE_SELF |
| 486 |
event for |
| 487 |
.IR myfile . |
| 488 |
The |
| 489 |
.B IN_MOVED_FROM |
| 490 |
and |
| 491 |
.B IN_MOVED_TO |
| 492 |
events will have the same |
| 493 |
.I cookie |
| 494 |
value. |
| 495 |
.RE |
| 496 |
.P |
| 497 |
Suppose that |
| 498 |
.I dir1/xx |
| 499 |
and |
| 500 |
.I dir2/yy |
| 501 |
are (the only) links to the same file, and an application is watching |
| 502 |
.IR dir1 , |
| 503 |
.IR dir2 , |
| 504 |
.IR dir1/xx , |
| 505 |
and |
| 506 |
.IR dir2/yy . |
| 507 |
Executing the following calls in the order given below will generate |
| 508 |
the following events: |
| 509 |
.RS 4 |
| 510 |
.TP |
| 511 |
unlink("dir2/yy"); |
| 512 |
Generates an |
| 513 |
.B IN_ATTRIB |
| 514 |
event for |
| 515 |
.I xx |
| 516 |
(because its link count changes) |
| 517 |
and an |
| 518 |
.B IN_DELETE |
| 519 |
event for |
| 520 |
.IR dir2 . |
| 521 |
.TP |
| 522 |
unlink("dir1/xx"); |
| 523 |
Generates |
| 524 |
.BR IN_ATTRIB , |
| 525 |
.BR IN_DELETE_SELF , |
| 526 |
and |
| 527 |
.B IN_IGNORED |
| 528 |
events for |
| 529 |
.IR xx , |
| 530 |
and an |
| 531 |
.B IN_DELETE |
| 532 |
event for |
| 533 |
.IR dir1 . |
| 534 |
.RE |
| 535 |
.P |
| 536 |
Suppose an application is watching the directory |
| 537 |
.I dir |
| 538 |
and (the empty) directory |
| 539 |
.IR dir/subdir . |
| 540 |
The following examples show some events that may be generated. |
| 541 |
.RS 4 |
| 542 |
.TP |
| 543 |
mkdir("dir/new", mode); |
| 544 |
Generates an |
| 545 |
.B "IN_CREATE | IN_ISDIR" |
| 546 |
event for |
| 547 |
.IR dir . |
| 548 |
.TP |
| 549 |
rmdir("dir/subdir"); |
| 550 |
Generates |
| 551 |
.B IN_DELETE_SELF |
| 552 |
and |
| 553 |
.B IN_IGNORED |
| 554 |
events for |
| 555 |
.IR subdir , |
| 556 |
and an |
| 557 |
.B "IN_DELETE | IN_ISDIR" |
| 558 |
event for |
| 559 |
.IR dir . |
| 560 |
.RE |
| 561 |
.SS /proc interfaces |
| 562 |
The following interfaces can be used to limit the amount of |
| 563 |
kernel memory consumed by inotify: |
| 564 |
.TP |
| 565 |
.I /proc/sys/fs/inotify/max_queued_events |
| 566 |
The value in this file is used when an application calls |
| 567 |
.BR inotify_init (2) |
| 568 |
to set an upper limit on the number of events that can be |
| 569 |
queued to the corresponding inotify instance. |
| 570 |
Events in excess of this limit are dropped, but an |
| 571 |
.B IN_Q_OVERFLOW |
| 572 |
event is always generated. |
| 573 |
.TP |
| 574 |
.I /proc/sys/fs/inotify/max_user_instances |
| 575 |
This specifies an upper limit on the number of inotify instances |
| 576 |
that can be created per real user ID. |
| 577 |
.TP |
| 578 |
.I /proc/sys/fs/inotify/max_user_watches |
| 579 |
This specifies an upper limit on the number of watches |
| 580 |
that can be created per real user ID. |
| 581 |
.SH STANDARDS |
| 582 |
Linux. |
| 583 |
.SH HISTORY |
| 584 |
Inotify was merged into Linux 2.6.13. |
| 585 |
The required library interfaces were added in glibc 2.4. |
| 586 |
.RB ( IN_DONT_FOLLOW , |
| 587 |
.BR IN_MASK_ADD , |
| 588 |
and |
| 589 |
.B IN_ONLYDIR |
| 590 |
were added in glibc 2.5.) |
| 591 |
.SH NOTES |
| 592 |
Inotify file descriptors can be monitored using |
| 593 |
.BR select (2), |
| 594 |
.BR poll (2), |
| 595 |
and |
| 596 |
.BR epoll (7). |
| 597 |
When an event is available, the file descriptor indicates as readable. |
| 598 |
.P |
| 599 |
Since Linux 2.6.25, |
| 600 |
signal-driven I/O notification is available for inotify file descriptors; |
| 601 |
see the discussion of |
| 602 |
.B F_SETFL |
| 603 |
(for setting the |
| 604 |
.B O_ASYNC |
| 605 |
flag), |
| 606 |
.BR F_SETOWN , |
| 607 |
and |
| 608 |
.B F_SETSIG |
| 609 |
in |
| 610 |
.BR fcntl (2). |
| 611 |
The |
| 612 |
.I siginfo_t |
| 613 |
structure (described in |
| 614 |
.BR sigaction (2)) |
| 615 |
that is passed to the signal handler has the following fields set: |
| 616 |
.I si_fd |
| 617 |
is set to the inotify file descriptor number; |
| 618 |
.I si_signo |
| 619 |
is set to the signal number; |
| 620 |
.I si_code |
| 621 |
is set to |
| 622 |
.BR POLL_IN ; |
| 623 |
and |
| 624 |
.B POLLIN |
| 625 |
is set in |
| 626 |
.IR si_band . |
| 627 |
.P |
| 628 |
If successive output inotify events produced on the |
| 629 |
inotify file descriptor are identical (same |
| 630 |
.IR wd , |
| 631 |
.IR mask , |
| 632 |
.IR cookie , |
| 633 |
and |
| 634 |
.IR name ), |
| 635 |
then they are coalesced into a single event if the |
| 636 |
older event has not yet been read (but see BUGS). |
| 637 |
This reduces the amount of kernel memory required for the event queue, |
| 638 |
but also means that an application can't use inotify to reliably count |
| 639 |
file events. |
| 640 |
.P |
| 641 |
The events returned by reading from an inotify file descriptor |
| 642 |
form an ordered queue. |
| 643 |
Thus, for example, it is guaranteed that when renaming from |
| 644 |
one directory to another, events will be produced in the |
| 645 |
correct order on the inotify file descriptor. |
| 646 |
.P |
| 647 |
The set of watch descriptors that is being monitored via |
| 648 |
an inotify file descriptor can be viewed via the entry for |
| 649 |
the inotify file descriptor in the process's |
| 650 |
.IR /proc/ pid /fdinfo |
| 651 |
directory. |
| 652 |
See |
| 653 |
.BR proc (5) |
| 654 |
for further details. |
| 655 |
The |
| 656 |
.B FIONREAD |
| 657 |
.BR ioctl (2) |
| 658 |
returns the number of bytes available to read from an |
| 659 |
inotify file descriptor. |
| 660 |
.SS Limitations and caveats |
| 661 |
The inotify API provides no information about the user or process that |
| 662 |
triggered the inotify event. |
| 663 |
In particular, there is no easy |
| 664 |
way for a process that is monitoring events via inotify |
| 665 |
to distinguish events that it triggers |
| 666 |
itself from those that are triggered by other processes. |
| 667 |
.P |
| 668 |
Inotify reports only events that a user-space program triggers through |
| 669 |
the filesystem API. |
| 670 |
As a result, it does not catch remote events that occur |
| 671 |
on network filesystems. |
| 672 |
(Applications must fall back to polling the filesystem |
| 673 |
to catch such events.) |
| 674 |
Furthermore, various pseudo-filesystems such as |
| 675 |
.IR /proc , |
| 676 |
.IR /sys , |
| 677 |
and |
| 678 |
.I /dev/pts |
| 679 |
are not monitorable with inotify. |
| 680 |
.P |
| 681 |
The inotify API does not report file accesses and modifications that |
| 682 |
may occur because of |
| 683 |
.BR mmap (2), |
| 684 |
.BR msync (2), |
| 685 |
and |
| 686 |
.BR munmap (2). |
| 687 |
.P |
| 688 |
The inotify API identifies affected files by filename. |
| 689 |
However, by the time an application processes an inotify event, |
| 690 |
the filename may already have been deleted or renamed. |
| 691 |
.P |
| 692 |
The inotify API identifies events via watch descriptors. |
| 693 |
It is the application's responsibility to cache a mapping |
| 694 |
(if one is needed) between watch descriptors and pathnames. |
| 695 |
Be aware that directory renamings may affect multiple cached pathnames. |
| 696 |
.P |
| 697 |
Inotify monitoring of directories is not recursive: |
| 698 |
to monitor subdirectories under a directory, |
| 699 |
additional watches must be created. |
| 700 |
This can take a significant amount time for large directory trees. |
| 701 |
.P |
| 702 |
If monitoring an entire directory subtree, |
| 703 |
and a new subdirectory is created in that tree or an existing directory |
| 704 |
is renamed into that tree, |
| 705 |
be aware that by the time you create a watch for the new subdirectory, |
| 706 |
new files (and subdirectories) may already exist inside the subdirectory. |
| 707 |
Therefore, you may want to scan the contents of the subdirectory |
| 708 |
immediately after adding the watch (and, if desired, |
| 709 |
recursively add watches for any subdirectories that it contains). |
| 710 |
.P |
| 711 |
Note that the event queue can overflow. |
| 712 |
In this case, events are lost. |
| 713 |
Robust applications should handle the possibility of |
| 714 |
lost events gracefully. |
| 715 |
For example, it may be necessary to rebuild part or all of |
| 716 |
the application cache. |
| 717 |
(One simple, but possibly expensive, |
| 718 |
approach is to close the inotify file descriptor, empty the cache, |
| 719 |
create a new inotify file descriptor, |
| 720 |
and then re-create watches and cache entries |
| 721 |
for the objects to be monitored.) |
| 722 |
.P |
| 723 |
If a filesystem is mounted on top of a monitored directory, |
| 724 |
no event is generated, and no events are generated |
| 725 |
for objects immediately under the new mount point. |
| 726 |
If the filesystem is subsequently unmounted, |
| 727 |
events will subsequently be generated for the directory and |
| 728 |
the objects it contains. |
| 729 |
.\" |
| 730 |
.SS Dealing with rename() events |
| 731 |
As noted above, the |
| 732 |
.B IN_MOVED_FROM |
| 733 |
and |
| 734 |
.B IN_MOVED_TO |
| 735 |
event pair that is generated by |
| 736 |
.BR rename (2) |
| 737 |
can be matched up via their shared cookie value. |
| 738 |
However, the task of matching has some challenges. |
| 739 |
.P |
| 740 |
These two events are usually consecutive in the event stream available |
| 741 |
when reading from the inotify file descriptor. |
| 742 |
However, this is not guaranteed. |
| 743 |
If multiple processes are triggering events for monitored objects, |
| 744 |
then (on rare occasions) an arbitrary number of |
| 745 |
other events may appear between the |
| 746 |
.B IN_MOVED_FROM |
| 747 |
and |
| 748 |
.B IN_MOVED_TO |
| 749 |
events. |
| 750 |
Furthermore, it is not guaranteed that the event pair is atomically |
| 751 |
inserted into the queue: there may be a brief interval where the |
| 752 |
.B IN_MOVED_FROM |
| 753 |
has appeared, but the |
| 754 |
.B IN_MOVED_TO |
| 755 |
has not. |
| 756 |
.P |
| 757 |
Matching up the |
| 758 |
.B IN_MOVED_FROM |
| 759 |
and |
| 760 |
.B IN_MOVED_TO |
| 761 |
event pair generated by |
| 762 |
.BR rename (2) |
| 763 |
is thus inherently racy. |
| 764 |
(Don't forget that if an object is renamed outside of a monitored directory, |
| 765 |
there may not even be an |
| 766 |
.B IN_MOVED_TO |
| 767 |
event.) |
| 768 |
Heuristic approaches (e.g., assume the events are always consecutive) |
| 769 |
can be used to ensure a match in most cases, |
| 770 |
but will inevitably miss some cases, |
| 771 |
causing the application to perceive the |
| 772 |
.B IN_MOVED_FROM |
| 773 |
and |
| 774 |
.B IN_MOVED_TO |
| 775 |
events as being unrelated. |
| 776 |
If watch descriptors are destroyed and re-created as a result, |
| 777 |
then those watch descriptors will be inconsistent with |
| 778 |
the watch descriptors in any pending events. |
| 779 |
(Re-creating the inotify file descriptor and rebuilding the cache may |
| 780 |
be useful to deal with this scenario.) |
| 781 |
.P |
| 782 |
Applications should also allow for the possibility that the |
| 783 |
.B IN_MOVED_FROM |
| 784 |
event was the last event that could fit in the buffer |
| 785 |
returned by the current call to |
| 786 |
.BR read (2), |
| 787 |
and the accompanying |
| 788 |
.B IN_MOVED_TO |
| 789 |
event might be fetched only on the next |
| 790 |
.BR read (2), |
| 791 |
which should be done with a (small) timeout to allow for the fact that |
| 792 |
insertion of the |
| 793 |
.BR IN_MOVED_FROM + IN_MOVED_TO |
| 794 |
event pair is not atomic, |
| 795 |
and also the possibility that there may not be any |
| 796 |
.B IN_MOVED_TO |
| 797 |
event. |
| 798 |
.SH BUGS |
| 799 |
Before Linux 3.19, |
| 800 |
.BR fallocate (2) |
| 801 |
did not create any inotify events. |
| 802 |
Since Linux 3.19, |
| 803 |
.\" commit 820c12d5d6c0890bc93dd63893924a13041fdc35 |
| 804 |
calls to |
| 805 |
.BR fallocate (2) |
| 806 |
generate |
| 807 |
.B IN_MODIFY |
| 808 |
events. |
| 809 |
.P |
| 810 |
.\" FIXME . kernel commit 611da04f7a31b2208e838be55a42c7a1310ae321 |
| 811 |
.\" implies that unmount events were buggy since Linux 2.6.11 to Linux 2.6.36 |
| 812 |
.\" |
| 813 |
Before Linux 2.6.16, the |
| 814 |
.B IN_ONESHOT |
| 815 |
.I mask |
| 816 |
flag does not work. |
| 817 |
.P |
| 818 |
As originally designed and implemented, the |
| 819 |
.B IN_ONESHOT |
| 820 |
flag did not cause an |
| 821 |
.B IN_IGNORED |
| 822 |
event to be generated when the watch was dropped after one event. |
| 823 |
However, as an unintended effect of other changes, |
| 824 |
since Linux 2.6.36, an |
| 825 |
.B IN_IGNORED |
| 826 |
event is generated in this case. |
| 827 |
.P |
| 828 |
Before Linux 2.6.25, |
| 829 |
.\" commit 1c17d18e3775485bf1e0ce79575eb637a94494a2 |
| 830 |
the kernel code that was intended to coalesce successive identical events |
| 831 |
(i.e., the two most recent events could potentially be coalesced |
| 832 |
if the older had not yet been read) |
| 833 |
instead checked if the most recent event could be coalesced with the |
| 834 |
.I oldest |
| 835 |
unread event. |
| 836 |
.P |
| 837 |
When a watch descriptor is removed by calling |
| 838 |
.BR inotify_rm_watch (2) |
| 839 |
(or because a watch file is deleted or the filesystem |
| 840 |
that contains it is unmounted), |
| 841 |
any pending unread events for that watch descriptor remain available to read. |
| 842 |
As watch descriptors are subsequently allocated with |
| 843 |
.BR inotify_add_watch (2), |
| 844 |
the kernel cycles through the range of possible watch descriptors (1 to |
| 845 |
.BR INT_MAX ) |
| 846 |
incrementally. |
| 847 |
When allocating a free watch descriptor, no check is made to see whether that |
| 848 |
watch descriptor number has any pending unread events in the inotify queue. |
| 849 |
Thus, it can happen that a watch descriptor is reallocated even |
| 850 |
when pending unread events exist for a previous incarnation of |
| 851 |
that watch descriptor number, with the result that the application |
| 852 |
might then read those events and interpret them as belonging to |
| 853 |
the file associated with the newly recycled watch descriptor. |
| 854 |
In practice, the likelihood of hitting this bug may be extremely low, |
| 855 |
since it requires that an application cycle through |
| 856 |
.B INT_MAX |
| 857 |
watch descriptors, |
| 858 |
release a watch descriptor while leaving unread events for that |
| 859 |
watch descriptor in the queue, |
| 860 |
and then recycle that watch descriptor. |
| 861 |
For this reason, and because there have been no reports |
| 862 |
of the bug occurring in real-world applications, |
| 863 |
as of Linux 3.15, |
| 864 |
.\" FIXME . https://bugzilla.kernel.org/show_bug.cgi?id=77111 |
| 865 |
no kernel changes have yet been made to eliminate this possible bug. |
| 866 |
.SH EXAMPLES |
| 867 |
The following program demonstrates the usage of the inotify API. |
| 868 |
It marks the directories passed as a command-line arguments |
| 869 |
and waits for events of type |
| 870 |
.BR IN_OPEN , |
| 871 |
.BR IN_CLOSE_NOWRITE , |
| 872 |
and |
| 873 |
.BR IN_CLOSE_WRITE . |
| 874 |
.P |
| 875 |
The following output was recorded while editing the file |
| 876 |
.I /home/user/temp/foo |
| 877 |
and listing directory |
| 878 |
.IR /tmp . |
| 879 |
Before the file and the directory were opened, |
| 880 |
.B IN_OPEN |
| 881 |
events occurred. |
| 882 |
After the file was closed, an |
| 883 |
.B IN_CLOSE_WRITE |
| 884 |
event occurred. |
| 885 |
After the directory was closed, an |
| 886 |
.B IN_CLOSE_NOWRITE |
| 887 |
event occurred. |
| 888 |
Execution of the program ended when the user pressed the ENTER key. |
| 889 |
.SS Example output |
| 890 |
.in +4n |
| 891 |
.EX |
| 892 |
.RB $ " ./a.out /tmp /home/user/temp" ; |
| 893 |
Press enter key to terminate. |
| 894 |
Listening for events. |
| 895 |
IN_OPEN: /home/user/temp/foo [file] |
| 896 |
IN_CLOSE_WRITE: /home/user/temp/foo [file] |
| 897 |
IN_OPEN: /tmp/ [directory] |
| 898 |
IN_CLOSE_NOWRITE: /tmp/ [directory] |
| 899 |
\& |
| 900 |
Listening for events stopped. |
| 901 |
.EE |
| 902 |
.in |
| 903 |
.SS Program source |
| 904 |
\& |
| 905 |
.EX |
| 906 |
#include <errno.h> |
| 907 |
#include <poll.h> |
| 908 |
#include <stdio.h> |
| 909 |
#include <stdlib.h> |
| 910 |
#include <sys/inotify.h> |
| 911 |
#include <unistd.h> |
| 912 |
#include <string.h> |
| 913 |
\& |
| 914 |
/* Read all available inotify events from the file descriptor \[aq]fd\[aq]. |
| 915 |
wd is the table of watch descriptors for the directories in argv. |
| 916 |
argc is the size of wd and argv. |
| 917 |
argv is the list of watched directories. |
| 918 |
Entry 0 of wd and argv is unused. */ |
| 919 |
\& |
| 920 |
static void |
| 921 |
handle_events(int fd, int *wd, int argc, char* argv[]) |
| 922 |
{ |
| 923 |
/* Some systems cannot read integer variables if they are not |
| 924 |
properly aligned. On other systems, incorrect alignment may |
| 925 |
decrease performance. Hence, the buffer used for reading from |
| 926 |
the inotify file descriptor should have the same alignment as |
| 927 |
struct inotify_event. */ |
| 928 |
\& |
| 929 |
char buf[4096] |
| 930 |
__attribute__ ((aligned(__alignof__(struct inotify_event)))); |
| 931 |
const struct inotify_event *event; |
| 932 |
ssize_t size; |
| 933 |
\& |
| 934 |
/* Loop while events can be read from inotify file descriptor. */ |
| 935 |
\& |
| 936 |
for (;;) { |
| 937 |
\& |
| 938 |
/* Read some events. */ |
| 939 |
\& |
| 940 |
size = read(fd, buf, sizeof(buf)); |
| 941 |
if (size == \-1 && errno != EAGAIN) { |
| 942 |
perror("read"); |
| 943 |
exit(EXIT_FAILURE); |
| 944 |
} |
| 945 |
\& |
| 946 |
/* If the nonblocking read() found no events to read, then |
| 947 |
it returns \-1 with errno set to EAGAIN. In that case, |
| 948 |
we exit the loop. */ |
| 949 |
\& |
| 950 |
if (size <= 0) |
| 951 |
break; |
| 952 |
\& |
| 953 |
/* Loop over all events in the buffer. */ |
| 954 |
\& |
| 955 |
for (char *ptr = buf; ptr < buf + size; |
| 956 |
ptr += sizeof(struct inotify_event) + event\->len) { |
| 957 |
\& |
| 958 |
event = (const struct inotify_event *) ptr; |
| 959 |
\& |
| 960 |
/* Print event type. */ |
| 961 |
\& |
| 962 |
if (event\->mask & IN_OPEN) |
| 963 |
printf("IN_OPEN: "); |
| 964 |
if (event\->mask & IN_CLOSE_NOWRITE) |
| 965 |
printf("IN_CLOSE_NOWRITE: "); |
| 966 |
if (event\->mask & IN_CLOSE_WRITE) |
| 967 |
printf("IN_CLOSE_WRITE: "); |
| 968 |
\& |
| 969 |
/* Print the name of the watched directory. */ |
| 970 |
\& |
| 971 |
for (size_t i = 1; i < argc; ++i) { |
| 972 |
if (wd[i] == event\->wd) { |
| 973 |
printf("%s/", argv[i]); |
| 974 |
break; |
| 975 |
} |
| 976 |
} |
| 977 |
\& |
| 978 |
/* Print the name of the file. */ |
| 979 |
\& |
| 980 |
if (event\->len) |
| 981 |
printf("%s", event\->name); |
| 982 |
\& |
| 983 |
/* Print type of filesystem object. */ |
| 984 |
\& |
| 985 |
if (event\->mask & IN_ISDIR) |
| 986 |
printf(" [directory]\[rs]n"); |
| 987 |
else |
| 988 |
printf(" [file]\[rs]n"); |
| 989 |
} |
| 990 |
} |
| 991 |
} |
| 992 |
\& |
| 993 |
int |
| 994 |
main(int argc, char* argv[]) |
| 995 |
{ |
| 996 |
char buf; |
| 997 |
int fd, i, poll_num; |
| 998 |
int *wd; |
| 999 |
nfds_t nfds; |
| 1000 |
struct pollfd fds[2]; |
| 1001 |
\& |
| 1002 |
if (argc < 2) { |
| 1003 |
printf("Usage: %s PATH [PATH ...]\[rs]n", argv[0]); |
| 1004 |
exit(EXIT_FAILURE); |
| 1005 |
} |
| 1006 |
\& |
| 1007 |
printf("Press ENTER key to terminate.\[rs]n"); |
| 1008 |
\& |
| 1009 |
/* Create the file descriptor for accessing the inotify API. */ |
| 1010 |
\& |
| 1011 |
fd = inotify_init1(IN_NONBLOCK); |
| 1012 |
if (fd == \-1) { |
| 1013 |
perror("inotify_init1"); |
| 1014 |
exit(EXIT_FAILURE); |
| 1015 |
} |
| 1016 |
\& |
| 1017 |
/* Allocate memory for watch descriptors. */ |
| 1018 |
\& |
| 1019 |
wd = calloc(argc, sizeof(int)); |
| 1020 |
if (wd == NULL) { |
| 1021 |
perror("calloc"); |
| 1022 |
exit(EXIT_FAILURE); |
| 1023 |
} |
| 1024 |
\& |
| 1025 |
/* Mark directories for events |
| 1026 |
\- file was opened |
| 1027 |
\- file was closed */ |
| 1028 |
\& |
| 1029 |
for (i = 1; i < argc; i++) { |
| 1030 |
wd[i] = inotify_add_watch(fd, argv[i], |
| 1031 |
IN_OPEN | IN_CLOSE); |
| 1032 |
if (wd[i] == \-1) { |
| 1033 |
fprintf(stderr, "Cannot watch \[aq]%s\[aq]: %s\[rs]n", |
| 1034 |
argv[i], strerror(errno)); |
| 1035 |
exit(EXIT_FAILURE); |
| 1036 |
} |
| 1037 |
} |
| 1038 |
\& |
| 1039 |
/* Prepare for polling. */ |
| 1040 |
\& |
| 1041 |
nfds = 2; |
| 1042 |
\& |
| 1043 |
fds[0].fd = STDIN_FILENO; /* Console input */ |
| 1044 |
fds[0].events = POLLIN; |
| 1045 |
\& |
| 1046 |
fds[1].fd = fd; /* Inotify input */ |
| 1047 |
fds[1].events = POLLIN; |
| 1048 |
\& |
| 1049 |
/* Wait for events and/or terminal input. */ |
| 1050 |
\& |
| 1051 |
printf("Listening for events.\[rs]n"); |
| 1052 |
for (;;) { |
| 1053 |
poll_num = poll(fds, nfds, \-1); |
| 1054 |
if (poll_num == \-1) { |
| 1055 |
if (errno == EINTR) |
| 1056 |
continue; |
| 1057 |
perror("poll"); |
| 1058 |
exit(EXIT_FAILURE); |
| 1059 |
} |
| 1060 |
\& |
| 1061 |
if (poll_num > 0) { |
| 1062 |
\& |
| 1063 |
if (fds[0].revents & POLLIN) { |
| 1064 |
\& |
| 1065 |
/* Console input is available. Empty stdin and quit. */ |
| 1066 |
\& |
| 1067 |
while (read(STDIN_FILENO, &buf, 1) > 0 && buf != \[aq]\[rs]n\[aq]) |
| 1068 |
continue; |
| 1069 |
break; |
| 1070 |
} |
| 1071 |
\& |
| 1072 |
if (fds[1].revents & POLLIN) { |
| 1073 |
\& |
| 1074 |
/* Inotify events are available. */ |
| 1075 |
\& |
| 1076 |
handle_events(fd, wd, argc, argv); |
| 1077 |
} |
| 1078 |
} |
| 1079 |
} |
| 1080 |
\& |
| 1081 |
printf("Listening for events stopped.\[rs]n"); |
| 1082 |
\& |
| 1083 |
/* Close inotify file descriptor. */ |
| 1084 |
\& |
| 1085 |
close(fd); |
| 1086 |
\& |
| 1087 |
free(wd); |
| 1088 |
exit(EXIT_SUCCESS); |
| 1089 |
} |
| 1090 |
.EE |
| 1091 |
.SH SEE ALSO |
| 1092 |
.BR inotifywait (1), |
| 1093 |
.BR inotifywatch (1), |
| 1094 |
.BR inotify_add_watch (2), |
| 1095 |
.BR inotify_init (2), |
| 1096 |
.BR inotify_init1 (2), |
| 1097 |
.BR inotify_rm_watch (2), |
| 1098 |
.BR read (2), |
| 1099 |
.BR stat (2), |
| 1100 |
.BR fanotify (7) |
| 1101 |
.P |
| 1102 |
.I Documentation/filesystems/inotify.rst |
| 1103 |
in the Linux kernel source tree |