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