1 '\" te
2 .\" Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
3 .\" This file and its contents are supplied under the terms of the
4 .\" Common Development and Distribution License ("CDDL"), version 1.0.
5 .\" You may only use this file in accordance with the terms of version
6 .\" 1.0 of the CDDL.
7 .\"
8 .\" A full copy of the text of the CDDL should have accompanied this
9 .\" source. A copy of the CDDL is also available via the Internet at
10 .\" http://www.illumos.org/license/CDDL.
11 .TH INOTIFY 5 "Sep 17, 2014"
12 .SH NAME
13 inotify \- Linux-compatible file event notification facility
14 .SH SYNOPSIS
15
16 .LP
17 .nf
18 #include <sys/inotify.h>
19 .fi
20
21 .SH DESCRIPTION
22 .sp
23 .LP
24
25 \fBinotify\fR is a facility for receiving file system events on specified
26 files or directories. When monitoring a directory, \fBinotify\fR can be
27 used to retrieve events not only on the directory, but also on any files
28 that the directory contains. \fBinotify\fR originated with Linux, and
29 this facility is designed to be binary-compatible with the Linux facility,
30 including the following interfaces:
31
32 .RS +4
33 .TP
34 .ie t \(bu
35 .el o
36 \fBinotify_init\fR(3C) creates an \fBinotify\fR instance, returning a file
37 descriptor associated with the in-kernel event queue.
38 .RE
39 .RS +4
40 .TP
41 .ie t \(bu
42 .el o
43 \fBinotify_init1\fR(3C) also creates an \fBinotify\fR instance, but allows
44 for a flags argument that controls some attributes of the returned file
45 descriptor.
46 .RE
47 .RS +4
48 .TP
49 .ie t \(bu
50 .el o
51 \fBinotify_add_watch\fR(3C) allows a watch of a particular file or directory
52 to be added to a watch list associated with the specified \fBinotify\fR
53 instance. \fBinotify_add_watch\fR(3C) returns a watch descriptor that will
54 be reflected in the \fIwd\fR member of the \fIinotify_event\fR structure
55 returned via a \fBread\fR(2) of the instance.
56 .RE
57 .RS +4
58 .TP
59 .ie t \(bu
60 .el o
61 \fBinotify_rm_watch\fR(3C) removes the watch that corresponds to the specified
62 watch descriptor.
63 .RE
64
65 When all file descriptors referring to a particular \fBinotify\fR instance
66 are closed, the instance and all watches associated with that instance are
67 freed.
68
69 To consume events on an \fBinotify\fR instance, an application should
70 issue a \fBread\fR(2) to the instance. If no events are available
71 (and the \fBinotify\fR instance has not been explicitly made non-blocking
72 via \fBinotify_init1\fR(3C)) the \fBread\fR(2) will block until a
73 watched event occurs. If and when events are available, \fBread\fR(2) will
74 return an array of the following structures:
75
76 .sp
77 .in +2
78 .nf
79 struct inotify_event {
80 int wd; /* watch descriptor */
81 uint32_t mask; /* mask of event */
82 uint32_t cookie; /* cookie for associating renames */
83 uint32_t len; /* size of name field */
84 char name[]; /* optional name */
85 };
86 .fi
87 .in -2
88
89 \fIwd\fR contains the watch descriptor that corresponds to the event,
90 as returned by \fBinotify_add_watch\fR(3C).
91
92 \fImask\fR is a bitwise \fBOR\fR of event masks (see below) that
93 describes the event.
94
95 \fIcookie\fR is an opaque value that can be used to associate different
96 events into a single logical event. In particular, it allows consumers to
97 associate \fBIN_MOVED_FROM\fR events with subsequent \fBIN_MOVED_TO\fR
98 events.
99
100 \fIlen\fR denotes the length of the \fIname\fR field, including any padding
101 required for trailing null bytes and alignment. The size of the entire
102 event is therefore the size of the \fIinotify_event\fR structure plus the
103 value of \fIlen\fR.
104
105 \fIname\fR contains the name of the file associated with the event, if any.
106 This field is only present when the watched entity is a directory and
107 the event corresponds to a file that was contained by the watched directory
108 (though see \fBNOTES\fR and \fBWARNINGS\fR for details and limitations).
109 When present, \fIname\fR is null terminated, and may contain additional
110 zero bytes
111 to pad for alignment. (The length of this field -- including any bytes
112 for alignment -- is denoted by the \fIlen\fR field.)
113
114 .SS "Events"
115
116 The events that can be generated on a watched entity are as follows:
117
118 .sp
119 .in +2
120 .TS
121 c c
122 l l .
123 \fIEvent\fR \fIDescription\fR
124 \fBIN_ACCESS\fR File/directory was accessed
125 \fBIN_ATTRIB\fR File/directory attributes were changed
126 \fBIN_CLOSE_WRITE\fR File/directory opened for writing was closed
127 \fBIN_CLOSE_NOWRITE\fR File/directory not opened for writing was closed
128 \fBIN_CREATE\fR File/directory created in watched directory
129 \fBIN_DELETE\fR File/directory deleted from watched directory
130 \fBIN_DELETE_SELF\fR Watched file/directory was deleted
131 \fBIN_MODIFY\fR File/directory was modified
132 \fBIN_MODIFY_SELF\fR Watched file/directory was modified
133 \fBIN_MOVED_FROM\fR File was renamed from entity in watched directory
134 \fBIN_MOVED_TO\fR File was renamed to entity in watched directory
135 \fBIN_OPEN\fR File/directory was opened
136 .TE
137 .in -2
138
139 Of these, all events except \fBIN_MOVE_SELF\fR and \fBIN_DELETE_SELF\fR
140 can refer to either the watched entity or (if the watched entity
141 is a directory) a file or directory contained by the watched directory.
142 (See \fBNOTES\fR and \fBWARNINGS\fR, below for details on this
143 mechanism and its limitations.)
144 If the event corresponds to a contained entity,
145 \fIname\fR will be set to the name of the affected
146 entity.
147
148 In addition to speciyfing events of interest, watched events may
149 be modified by potentially setting any of the following when adding a
150 watch via \fBinotify_add_watch\fR(3C):
151
152 .sp
153 .ne 2
154 .na
155 \fBIN_DONT_FOLLOW\fR
156 .ad
157 .RS 12n
158 Don't follow the specified pathname if it is a symbolic link.
159 .RE
160
161 .sp
162 .ne 2
163 .na
164 \fBIN_EXCL_UNLINK\fR
165 .ad
166 .RS 12n
167 If watching a directory and a contained entity becomes unlinked, cease
168 generating events for that entity. (By default, contained entities will
169 continue to generate events on their former parent directory.)
170 .RE
171
172 .sp
173 .ne 2
174 .na
175 \fBIN_MASK_ADD\fR
176 .ad
177 .RS 12n
178 If the specified pathname is already being watched, the specified events
179 will be added to the watched events instead of the default behavior of
180 replacing them. (If one
181 may forgive the editorializing, this particular interface gewgaw
182 seems entirely superfluous, and a canonical example of
183 feasibility trumping wisdom.)
184 .RE
185
186 .sp
187 .ne 2
188 .na
189 \fBIN_ONESHOT\fR
190 .ad
191 .RS 12n
192 Once an event has been generated for the watched entity, remove the
193 watch from the watch list as if \fBinotify_rm_watch\fR(3C) had been called
194 on it (thereby inducing an \fBIN_IGNORED\fR event).
195 .RE
196
197 .sp
198 .ne 2
199 .na
200 \fBIN_ONLYDIR\fR
201 .ad
202 .RS 12n
203 Only watch the specified pathname if it is a directory.
204 .RE
205
206 In addition to the specified events, the following bits may be specified
207 in the \fImask\fR field as returned from \fBread\fR(2):
208
209 .sp
210 .ne 2
211 .na
212 \fBIN_IGNORED\fR
213 .ad
214 .RS 12n
215 A watch was removed explicitly (i.e, via \fBinotify_rm_watch\fR(3C)) or
216 implicitly (e.g., because \fBIN_ONESHOT\fR was set or because the watched
217 entity was deleted).
218 .RE
219
220 .sp
221 .ne 2
222 .na
223 \fBIN_ISDIR\fR
224 .ad
225 .RS 12n
226 The entity inducing the event is a directory.
227 .RE
228
229 .sp
230 .ne 2
231 .na
232 \fBIN_Q_OVERFLOW\fR
233 .ad
234 .RS 12n
235 The event queue exceeded the maximum event queue length per instance.
236 (By default, this is 16384, but it can be tuned by setting
237 \fBinotify_maxevents\fR via \fB/etc/system\fR.)
238 .RE
239
240 .sp
241 .ne 2
242 .na
243 \fBIN_UNMOUNT\fR
244 .ad
245 .RS 12n
246 The filesystem containing the watched entity was unmounted.
247 .RE
248
249 .sp
250 .SH NOTES
251 .sp
252 .LP
253
254 \fBinotify\fR instances can be monitored via \fBpoll\fR(2),
255 \fBport_get\fR(3C), \fBepoll\fR(5), etc.
256
257 The event queue associated with an \fBinotify\fR instance is serialized
258 and ordered: events will be placed on the tail of the queue in the order
259 that they occur.
260
261 If at the time an event occurs the tail of the event queue is identical
262 to the newly received event, the newly received event will be dropped,
263 effectively coalescing the two events.
264
265 When watching a directory and receieving events on contained elements
266 (i.e., a contained file or subdirectory), note that the information
267 received in the \fIname\fR field may be stale: the file may have been
268 renamed between the event and its processing. If a file has been unlinked
269 (and if \fBIN_EXCL_UNLINK\fR has not been set),
270 the \fIname\fR will reflect the last name that resolved to the file.
271 If a new file is created in the same directory with the old name, events
272 on the new file and the old (unlinked) file will become undistinguishable.
273
274 The number of bytes that are available to be read on an \fBinotify\fR
275 instance can be determined via a \fBFIONREAD\fR \fBioctl\fR(2).
276
277 .sp
278 .SH WARNINGS
279 .sp
280 .LP
281
282 While a best effort has been made to mimic the Linux semantics, there
283 remains a fundamental difference with respect to hard links: on Linux,
284 if a file has multiple hard links to it, a notification on a watched
285 directory or file will be received if and only if that event was received
286 via the watched path. For events that are induced by open files
287 (such as \fBIN_MODIFY\fR), these semantics seem peculiar: the watched
288 file is in fact changing, but because it is not changing via the watched
289 path, no notification is received. By contrast, the implementation here
290 will always yield an event in this case -- even if the event was induced
291 by an \fBopen\fR(2) via an unwatched path. If an event occurs within a
292 watched directory on a file for which there exist multiple hard links within
293 the same (watched) directory, the event's \fIname\fR will correspond to one
294 of the links to the file. If multiple hard links exist to the
295 same file in the same watched directory and one of the links is removed,
296 notifications may not necessarily continue to be received for the file,
297 despite the (remaining) link in the watched directory; users of
298 \fBinotify\fR should exercise extreme caution when watching directories
299 that contain files with multiple hard links in the same directory.
300
301 .SH SEE ALSO
302 .sp
303 .LP
304 \fBinotify_init\fR(3C), \fBinotify_init1\fR(3C), \fBinotify_add_watch\fR(3C),
305 \fBinotify_rm_watch\fR(3C), \fBport_get\fR(3C), \fBepoll\fR(5)