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