1 INOTIFY(5) Standards, Environments, and Macros INOTIFY(5)
2
3
4
5 NAME
6 inotify - Linux-compatible file event notification facility
7
8 SYNOPSIS
9 #include <sys/inotify.h>
10
11
12 DESCRIPTION
13 inotify is a facility for receiving file system events on specified
14 files or directories. When monitoring a directory, inotify can be used
15 to retrieve events not only on the directory, but also on any files
16 that the directory contains. inotify originated with Linux, and this
17 facility is designed to be binary-compatible with the Linux facility,
18 including the following interfaces:
19
20
21 o inotify_init(3C) creates an inotify instance, returning a
22 file descriptor associated with the in-kernel event queue.
23
24 o inotify_init1(3C) also creates an inotify instance, but
25 allows for a flags argument that controls some attributes of
26 the returned file descriptor.
27
28 o inotify_add_watch(3C) allows a watch of a particular file or
29 directory to be added to a watch list associated with the
30 specified inotify instance. inotify_add_watch(3C) returns a
31 watch descriptor that will be reflected in the wd member of
32 the inotify_event structure returned via a read(2) of the
33 instance.
34
35 o inotify_rm_watch(3C) removes the watch that corresponds to
36 the specified watch descriptor.
37
38 When all file descriptors referring to a particular inotify instance
39 are closed, the instance and all watches associated with that instance
40 are freed.
41
42 To consume events on an inotify instance, an application should issue a
43 read(2) to the instance. If no events are available (and the inotify
44 instance has not been explicitly made non-blocking via
45 inotify_init1(3C)) the read(2) will block until a watched event occurs.
46 If and when events are available, read(2) will return an array of the
47 following structures:
48
49
50 struct inotify_event {
51 int wd; /* watch descriptor */
52 uint32_t mask; /* mask of event */
53 uint32_t cookie; /* cookie for associating renames */
54 uint32_t len; /* size of name field */
55 char name[]; /* optional name */
56 };
57
58 wd contains the watch descriptor that corresponds to the event, as
59 returned by inotify_add_watch(3C).
60
61 mask is a bitwise OR of event masks (see below) that describes the
62 event.
63
64 cookie is an opaque value that can be used to associate different
65 events into a single logical event. In particular, it allows consumers
66 to associate IN_MOVED_FROM events with subsequent IN_MOVED_TO events.
67
68 len denotes the length of the name field, including any padding
69 required for trailing null bytes and alignment. The size of the entire
70 event is therefore the size of the inotify_event structure plus the
71 value of len.
72
73 name contains the name of the file associated with the event, if any.
74 This field is only present when the watched entity is a directory and
75 the event corresponds to a file that was contained by the watched
76 directory (though see NOTES and WARNINGS for details and limitations).
77 When present, name is null terminated, and may contain additional zero
78 bytes to pad for alignment. (The length of this field -- including any
79 bytes for alignment -- is denoted by the len field.)
80
81
82 Events
83 The events that can be generated on a watched entity are as follows:
84
85
86
87 Event Description
88 IN_ACCESS File/directory was accessed
89 IN_ATTRIB File/directory attributes were changed
90 IN_CLOSE_WRITE File/directory opened for writing was closed
91 IN_CLOSE_NOWRITE File/directory not opened for writing was closed
92 IN_CREATE File/directory created in watched directory
93 IN_DELETE File/directory deleted from watched directory
94 IN_DELETE_SELF Watched file/directory was deleted
95 IN_MODIFY File/directory was modified
96 IN_MODIFY_SELF Watched file/directory was modified
97 IN_MOVED_FROM File was renamed from entity in watched directory
98 IN_MOVED_TO File was renamed to entity in watched directory
99 IN_OPEN File/directory was opened
100
101 Of these, all events except IN_MOVE_SELF and IN_DELETE_SELF can refer
102 to either the watched entity or (if the watched entity is a directory)
103 a file or directory contained by the watched directory. (See NOTES and
104 WARNINGS, below for details on this mechanism and its limitations.) If
105 the event corresponds to a contained entity, name will be set to the
106 name of the affected entity.
107
108 In addition to speciyfing events of interest, watched events may be
109 modified by potentially setting any of the following when adding a
110 watch via inotify_add_watch(3C):
111
112
113 IN_DONT_FOLLOW
114 Don't follow the specified pathname if it is a symbolic
115 link.
116
117
118 IN_EXCL_UNLINK
119 If watching a directory and a contained entity becomes
120 unlinked, cease generating events for that entity. (By
121 default, contained entities will continue to generate
122 events on their former parent directory.)
123
124
125 IN_MASK_ADD
126 If the specified pathname is already being watched, the
127 specified events will be added to the watched events
128 instead of the default behavior of replacing them. (If one
129 may forgive the editorializing, this particular interface
130 gewgaw seems entirely superfluous, and a canonical example
131 of feasibility trumping wisdom.)
132
133
134 IN_ONESHOT
135 Once an event has been generated for the watched entity,
136 remove the watch from the watch list as if
137 inotify_rm_watch(3C) had been called on it (thereby
138 inducing an IN_IGNORED event).
139
140
141 IN_ONLYDIR
142 Only watch the specified pathname if it is a directory.
143
144 In addition to the specified events, the following bits may be
145 specified in the mask field as returned from read(2):
146
147
148 IN_IGNORED
149 A watch was removed explicitly (i.e, via
150 inotify_rm_watch(3C)) or implicitly (e.g., because
151 IN_ONESHOT was set or because the watched entity was
152 deleted).
153
154
155 IN_ISDIR
156 The entity inducing the event is a directory.
157
158
159 IN_Q_OVERFLOW
160 The event queue exceeded the maximum event queue length per
161 instance. (By default, this is 16384, but it can be tuned
162 by setting inotify_maxevents via /etc/system.)
163
164
165 IN_UNMOUNT
166 The filesystem containing the watched entity was unmounted.
167
168
169
170 NOTES
171 inotify instances can be monitored via poll(2), port_get(3C), epoll(5),
172 etc.
173
174 The event queue associated with an inotify instance is serialized and
175 ordered: events will be placed on the tail of the queue in the order
176 that they occur.
177
178 If at the time an event occurs the tail of the event queue is identical
179 to the newly received event, the newly received event will be dropped,
180 effectively coalescing the two events.
181
182 When watching a directory and receieving events on contained elements
183 (i.e., a contained file or subdirectory), note that the information
184 received in the name field may be stale: the file may have been
185 renamed between the event and its processing. If a file has been
186 unlinked (and if IN_EXCL_UNLINK has not been set), the name will
187 reflect the last name that resolved to the file. If a new file is
188 created in the same directory with the old name, events on the new file
189 and the old (unlinked) file will become undistinguishable.
190
191 The number of bytes that are available to be read on an inotify
192 instance can be determined via a FIONREAD ioctl(2).
193
194
195
196 WARNINGS
197 While a best effort has been made to mimic the Linux semantics, there
198 remains a fundamental difference with respect to hard links: on Linux,
199 if a file has multiple hard links to it, a notification on a watched
200 directory or file will be received if and only if that event was
201 received via the watched path. For events that are induced by open
202 files (such as IN_MODIFY), these semantics seem peculiar: the watched
203 file is in fact changing, but because it is not changing via the
204 watched path, no notification is received. By contrast, the
205 implementation here will always yield an event in this case -- even if
206 the event was induced by an open(2) via an unwatched path. If an event
207 occurs within a watched directory on a file for which there exist
208 multiple hard links within the same (watched) directory, the event's
209 name will correspond to one of the links to the file. If multiple hard
210 links exist to the same file in the same watched directory and one of
211 the links is removed, notifications may not necessarily continue to be
212 received for the file, despite the (remaining) link in the watched
213 directory; users of inotify should exercise extreme caution when
214 watching directories that contain files with multiple hard links in the
215 same directory.
216
217
218 SEE ALSO
219 inotify_init(3C), inotify_init1(3C), inotify_add_watch(3C),
220 inotify_rm_watch(3C), port_get(3C), epoll(5)
221
222
223
224 September 17, 2014 INOTIFY(5)