1INOTIFY(7) Linux Programmer's Manual INOTIFY(7)
2
6 inotify - monitoring file system events
7
9 The inotify API provides a mechanism for monitoring file system 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: inotify_init(2) (or
15 inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2), read(2),
16 and close(2).
17 inotify_init(2) creates an inotify instance and returns a file descrip‐
19 tor referring to the inotify instance. The more recent ino‐
20 tify_init1(2) is like inotify_init(2), but provides some extra func‐
21 tionality.
22 inotify_add_watch(2) manipulates the "watch list" associated with an
24 inotify instance. Each item ("watch") in the watch list specifies the
25 pathname of a file or directory, along with some set of events that the
26 kernel should monitor for the file referred to by that pathname. ino‐
27 tify_add_watch(2) either creates a new watch item, or modifies an
28 existing watch. Each watch has a unique "watch descriptor", an integer
29 returned by inotify_add_watch(2) when the watch is created.
30 inotify_rm_watch(2) removes an item from an inotify watch list.
32 When all file descriptors referring to an inotify instance have been
34 closed, the underlying object and its resources are freed for reuse by
35 the kernel; all associated watches are automatically freed.
36 To determine what events have occurred, an application read(2)s from
38 the inotify file descriptor. If no events have so far occurred, then,
39 assuming a blocking file descriptor, read(2) will block until at least
40 one event occurs (unless interrupted by a signal, in which case the
41 call fails with the error EINTR; see signal(7)).
42 Each successful read(2) returns a buffer containing one or more of the
44 following structures:
45 struct inotify_event {
47 int wd; /* Watch descriptor */
48 uint32_t mask; /* Mask of events */
49 uint32_t cookie; /* Unique cookie associating related
50 events (for rename(2)) */
51 uint32_t len; /* Size of name field */
52 char name[]; /* Optional null-terminated name */
53 };
54 wd identifies the watch for which this event occurs. It is one of the
56 watch descriptors returned by a previous call to inotify_add_watch(2).
57 mask contains bits that describe the event that occurred (see below).
59 cookie is a unique integer that connects related events. Currently
61 this is used only for rename events, and allows the resulting pair of
62 IN_MOVED_FROM and IN_MOVED_TO events to be connected by the applica‐
63 tion. For all other event types, cookie is set to 0.
64 The name field is present only when an event is returned for a file
66 inside a watched directory; it identifies the file pathname relative to
67 the watched directory. This pathname is null-terminated, and may
68 include further null bytes ('\0') to align subsequent reads to a suit‐
69 able address boundary.
70 The len field counts all of the bytes in name, including the null
72 bytes; the length of each inotify_event structure is thus sizeof(struct
73 inotify_event)+len.
74 The behavior when the buffer given to read(2) is too small to return
76 information about the next event depends on the kernel version: in ker‐
77 nels before 2.6.21, read(2) returns 0; since kernel 2.6.21, read(2)
78 fails with the error EINVAL. Specifying a buffer of size
79 sizeof(struct inotify_event) + NAME_MAX + 1
81 will be sufficient to read at least one event.
83 inotify events
85 The inotify_add_watch(2) mask argument and the mask field of the ino‐
86 tify_event structure returned when read(2)ing an inotify file descrip‐
87 tor are both bit masks identifying inotify events. The following bits
88 can be specified in mask when calling inotify_add_watch(2) and may be
89 returned in the mask field returned by read(2):
90 IN_ACCESS File was accessed (read) (*).
92 IN_ATTRIB Metadata changed, e.g., permissions, timestamps,
93 extended attributes, link count (since Linux
94 2.6.25), UID, GID, etc. (*).
95 IN_CLOSE_WRITE File opened for writing was closed (*).
96 IN_CLOSE_NOWRITE File not opened for writing was closed (*).
97 IN_CREATE File/directory created in watched directory (*).
98 IN_DELETE File/directory deleted from watched directory
99 (*).
100 IN_DELETE_SELF Watched file/directory was itself deleted.
101 IN_MODIFY File was modified (*).
102 IN_MOVE_SELF Watched file/directory was itself moved.
103 IN_MOVED_FROM Generated for the directory containing the old
104 filename when a file is renamed (*).
105 IN_MOVED_TO Generated for the directory containing the new
106 filename when a file is renamed (*).
107 IN_OPEN File was opened (*).
108 When monitoring a directory, the events marked with an asterisk (*)
110 above can occur for files in the directory, in which case the name
111 field in the returned inotify_event structure identifies the name of
112 the file within the directory.
113 The IN_ALL_EVENTS macro is defined as a bit mask of all of the above
115 events. This macro can be used as the mask argument when calling ino‐
116 tify_add_watch(2).
117 Two additional convenience macros are IN_MOVE, which equates to
119 IN_MOVED_FROM|IN_MOVED_TO, and IN_CLOSE, which equates to
120 IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.
121 The following further bits can be specified in mask when calling ino‐
123 tify_add_watch(2):
124 IN_DONT_FOLLOW (since Linux 2.6.15)
126 Don't dereference pathname if it is a symbolic
127 link.
128 IN_EXCL_UNLINK (since Linux 2.6.36)
129 By default, when watching events on the children
130 of a directory, events are generated for children
131 even after they have been unlinked from the
132 directory. This can result in large numbers of
133 uninteresting events for some applications (e.g.,
134 if watching /tmp, in which many applications cre‐
135 ate temporary files whose names are immediately
136 unlinked). Specifying IN_EXCL_UNLINK changes the
137 default behavior, so that events are not gener‐
138 ated for children after they have been unlinked
139 from the watched directory.
140 IN_MASK_ADD Add (OR) events to watch mask for this pathname
141 if it already exists (instead of replacing mask).
142 IN_ONESHOT Monitor pathname for one event, then remove from
143 watch list.
144 IN_ONLYDIR (since Linux 2.6.15)
145 Only watch pathname if it is a directory.
146 The following bits may be set in the mask field returned by read(2):
148 IN_IGNORED Watch was removed explicitly (ino‐
150 tify_rm_watch(2)) or automatically (file was
151 deleted, or file system was unmounted).
152 IN_ISDIR Subject of this event is a directory.
153 IN_Q_OVERFLOW Event queue overflowed (wd is -1 for this event).
154 IN_UNMOUNT File system containing watched object was
155 unmounted.
156 /proc interfaces
158 The following interfaces can be used to limit the amount of kernel mem‐
159 ory consumed by inotify:
160 /proc/sys/fs/inotify/max_queued_events
162 The value in this file is used when an application calls ino‐
163 tify_init(2) to set an upper limit on the number of events that
164 can be queued to the corresponding inotify instance. Events in
165 excess of this limit are dropped, but an IN_Q_OVERFLOW event is
166 always generated.
167 /proc/sys/fs/inotify/max_user_instances
169 This specifies an upper limit on the number of inotify instances
170 that can be created per real user ID.
171 /proc/sys/fs/inotify/max_user_watches
173 This specifies an upper limit on the number of watches that can
174 be created per real user ID.
175
177 Inotify was merged into the 2.6.13 Linux kernel. The required library
178 interfaces were added to glibc in version 2.4. (IN_DONT_FOLLOW,
179 IN_MASK_ADD, and IN_ONLYDIR were added in version 2.5.)
180
182 The inotify API is Linux-specific.
183
185 Inotify file descriptors can be monitored using select(2), poll(2), and
186 epoll(7). When an event is available, the file descriptor indicates as
187 readable.
188 Since Linux 2.6.25, signal-driven I/O notification is available for
190 inotify file descriptors; see the discussion of F_SETFL (for setting
191 the O_ASYNC flag), F_SETOWN, and F_SETSIG in fcntl(2). The siginfo_t
192 structure (described in sigaction(2)) that is passed to the signal han‐
193 dler has the following fields set: si_fd is set to the inotify file
194 descriptor number; si_signo is set to the signal number; si_code is set
195 to POLL_IN; and POLLIN is set in si_band.
196 If successive output inotify events produced on the inotify file
198 descriptor are identical (same wd, mask, cookie, and name) then they
199 are coalesced into a single event if the older event has not yet been
200 read (but see BUGS).
201 The events returned by reading from an inotify file descriptor form an
203 ordered queue. Thus, for example, it is guaranteed that when renaming
204 from one directory to another, events will be produced in the correct
205 order on the inotify file descriptor.
206 The FIONREAD ioctl(2) returns the number of bytes available to read
208 from an inotify file descriptor.
209 Limitations and caveats
211 Inotify monitoring of directories is not recursive: to monitor subdi‐
212 rectories under a directory, additional watches must be created. This
213 can take a significant amount time for large directory trees.
214 The inotify API provides no information about the user or process that
216 triggered the inotify event. In particular, there is no easy way for a
217 process that is monitoring events via inotify to distinguish events
218 that it triggers itself from those that are triggered by other pro‐
219 cesses.
220 Note that the event queue can overflow. In this case, events are lost.
222 Robust applications should handle the possibility of lost events grace‐
223 fully.
224 The inotify API identifies affected files by filename. However, by the
226 time an application processes an inotify event, the filename may
227 already have been deleted or renamed.
228 If monitoring an entire directory subtree, and a new subdirectory is
230 created in that tree, be aware that by the time you create a watch for
231 the new subdirectory, new files may already have been created in the
232 subdirectory. Therefore, you may want to scan the contents of the sub‐
233 directory immediately after adding the watch.
234
236 In kernels before 2.6.16, the IN_ONESHOT mask flag does not work.
237 Before kernel 2.6.25, the kernel code that was intended to coalesce
239 successive identical events (i.e., the two most recent events could
240 potentially be coalesced if the older had not yet been read) instead
241 checked if the most recent event could be coalesced with the oldest
242 unread event.
243
245 inotify_add_watch(2), inotify_init(2), inotify_init1(2), ino‐
246 tify_rm_watch(2), read(2), stat(2)
247 Documentation/filesystems/inotify.txt in the Linux kernel source tree
249
251 This page is part of release 3.53 of the Linux man-pages project. A
252 description of the project, and information about reporting bugs, can
253 be found at http://www.kernel.org/doc/man-pages/.
254Linux 2013-07-21 INOTIFY(7)