1INOTIFY(7) Linux Programmer's Manual INOTIFY(7)
2
6 inotify - monitoring filesystem events
7
9 The inotify API provides a mechanism for monitoring filesystem events.
10 Inotify can be used to monitor individual files, or to monitor directo‐
11 ries. When a directory is monitored, inotify will return events for
12 the directory itself, and for files inside the directory.
13 The following system calls are used with this API:
15 * inotify_init(2) creates an inotify instance and returns a file
17 descriptor referring to the inotify instance. The more recent ino‐
18 tify_init1(2) is like inotify_init(2), but has a flags argument that
19 provides access to some extra functionality.
20 * inotify_add_watch(2) manipulates the "watch list" associated with an
22 inotify instance. Each item ("watch") in the watch list specifies
23 the pathname of a file or directory, along with some set of events
24 that the kernel should monitor for the file referred to by that
25 pathname. inotify_add_watch(2) either creates a new watch item, or
26 modifies an existing watch. Each watch has a unique "watch descrip‐
27 tor", an integer returned by inotify_add_watch(2) when the watch is
28 created.
29 * When events occur for monitored files and directories, those events
31 are made available to the application as structured data that can be
32 read from the inotify file descriptor using read(2) (see below).
33 * inotify_rm_watch(2) removes an item from an inotify watch list.
35 * When all file descriptors referring to an inotify instance have been
37 closed (using close(2)), the underlying object and its resources are
38 freed for reuse by the kernel; all associated watches are automati‐
39 cally freed.
40 With careful programming, an application can use inotify to efficiently
42 monitor and cache the state of a set of filesystem objects. However,
43 robust applications should allow for the fact that bugs in the monitor‐
44 ing logic or races of the kind described below may leave the cache
45 inconsistent with the filesystem state. It is probably wise to do some
46 consistency checking, and rebuild the cache when inconsistencies are
47 detected.
48 Reading events from an inotify file descriptor
50 To determine what events have occurred, an application read(2)s from
51 the inotify file descriptor. If no events have so far occurred, then,
52 assuming a blocking file descriptor, read(2) will block until at least
53 one event occurs (unless interrupted by a signal, in which case the
54 call fails with the error EINTR; see signal(7)).
55 Each successful read(2) returns a buffer containing one or more of the
57 following structures:
58 struct inotify_event {
60 int wd; /* Watch descriptor */
61 uint32_t mask; /* Mask describing event */
62 uint32_t cookie; /* Unique cookie associating related