]>
Commit | Line | Data |
---|---|---|
4d2b74dd MK |
1 | '\" t |
2 | .\" Hey Emacs! This file is -*- nroff -*- source. | |
3 | .\" | |
c11b1abf | 4 | .\" Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> |
4d2b74dd MK |
5 | .\" |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
4d2b74dd MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
c13182ef MK |
18 | .\" the use of the information contained herein. |
19 | .\" | |
4d2b74dd MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
c7e3ee6f | 23 | .TH INOTIFY 7 2007-06-03 "Linux" "Linux Programmer's Manual" |
4d2b74dd | 24 | .SH NAME |
3a20b4ca | 25 | inotify \- monitoring file system events |
4d2b74dd MK |
26 | .SH DESCRIPTION |
27 | The | |
c13182ef | 28 | .I inotify |
4d2b74dd MK |
29 | API provides a mechanism for monitoring file system events. |
30 | Inotify can be used to monitor individual files, | |
31 | or to monitor directories. | |
32 | When a directory is monitored, inotify will return events | |
33 | for the directory itself, and for files inside the directory. | |
34 | ||
c13182ef | 35 | The following system calls are used with this API: |
63f6a20a MK |
36 | .BR inotify_init (2), |
37 | .BR inotify_add_watch (2), | |
38 | .BR inotify_rm_watch (2), | |
39 | .BR read (2), | |
c13182ef | 40 | and |
63f6a20a | 41 | .BR close (2). |
4d2b74dd MK |
42 | |
43 | .BR inotify_init (2) | |
c13182ef | 44 | creates an inotify instance and returns a file descriptor |
a2cc46ca | 45 | referring to the inotify instance. |
4d2b74dd MK |
46 | |
47 | .BR inotify_add_watch (2) | |
a2cc46ca | 48 | manipulates the "watch list" associated with an inotify instance. |
3a065ac0 | 49 | Each item ("watch") in the watch list specifies the pathname of |
c13182ef | 50 | a file or directory, |
4d2b74dd MK |
51 | along with some set of events that the kernel should monitor for the |
52 | file referred to by that pathname. | |
63f6a20a | 53 | .BR inotify_add_watch (2) |
4d2b74dd MK |
54 | either creates a new watch item, or modifies an existing watch. |
55 | Each watch has a unique "watch descriptor", an integer | |
56 | returned by | |
63f6a20a | 57 | .BR inotify_add_watch (2) |
4d2b74dd MK |
58 | when the watch is created. |
59 | ||
60 | .BR inotify_rm_watch (2) | |
61 | removes an item from an inotify watch list. | |
62 | ||
c13182ef | 63 | When all file descriptors referring to an inotify |
a2cc46ca | 64 | instance have been closed, |
c13182ef | 65 | the underlying object and its resources are |
a2cc46ca | 66 | freed for re-use by the kernel; |
4d2b74dd MK |
67 | all associated watches are automatically freed. |
68 | ||
69 | To determine what events have occurred, an application | |
70 | .BR read (2)s | |
71 | from the inotify file descriptor. | |
c13182ef | 72 | If no events have so far occurred, then, |
11da88fb | 73 | assuming a blocking file descriptor, |
63f6a20a | 74 | .BR read (2) |
4d2b74dd MK |
75 | will block until at least one event occurs. |
76 | ||
77 | Each successful | |
63f6a20a | 78 | .BR read (2) |
4d2b74dd | 79 | returns a buffer containing one or more of the following structures: |
a08ea57c | 80 | .in +4n |
4d2b74dd MK |
81 | .nf |
82 | ||
83 | struct inotify_event { | |
84 | int wd; /* Watch descriptor */ | |
85 | uint32_t mask; /* Mask of events */ | |
c13182ef | 86 | uint32_t cookie; /* Unique cookie associating related |
4d2b74dd MK |
87 | events (for rename(2)) */ |
88 | uint32_t len; /* Size of 'name' field */ | |
89 | char name[]; /* Optional null-terminated name */ | |
90 | }; | |
91 | .fi | |
a08ea57c | 92 | .in |
4d2b74dd MK |
93 | |
94 | .I wd | |
95 | identifies the watch for which this event occurs. | |
c13182ef | 96 | It is one of the watch descriptors returned by a previous call to |
63f6a20a | 97 | .BR inotify_add_watch (2). |
4d2b74dd MK |
98 | |
99 | .I mask | |
100 | contains bits that describe the event that occurred (see below). | |
101 | ||
102 | .I cookie | |
103 | is a unique integer that connects related events. | |
104 | Currently this is only used for rename events, and | |
105 | allows the resulting pair of | |
106 | .B IN_MOVE_FROM | |
c13182ef | 107 | and |
4d2b74dd MK |
108 | .B IN_MOVE_TO |
109 | events to be connected by the application. | |
110 | ||
c13182ef | 111 | The |
4d2b74dd MK |
112 | .I name |
113 | field is only present when an event is returned | |
c13182ef | 114 | for a file inside a watched directory; |
4d2b74dd | 115 | it identifies the file pathname relative to the watched directory. |
c13182ef | 116 | This pathname is null-terminated, |
ad31978e | 117 | and may include further null bytes to align subsequent reads to a |
4d2b74dd MK |
118 | suitable address boundary. |
119 | ||
120 | The | |
121 | .I len | |
c13182ef | 122 | field counts all of the bytes in |
4d2b74dd | 123 | .IR name , |
c13182ef | 124 | including the null bytes; |
4d2b74dd MK |
125 | the length of each |
126 | .I inotify_event | |
127 | structure is thus | |
128 | .IR "sizeof(inotify_event)+len" . | |
c7e3ee6f | 129 | |
988db661 | 130 | The behavior when the buffer given to |
c7e3ee6f | 131 | .BR read (2) |
988db661 | 132 | is too small to return information about the next event depends |
c7e3ee6f MK |
133 | on the kernel version: in kernels before 2.6.21, |
134 | .BR read (2) | |
135 | returns 0; since kernel 2.6.21, | |
136 | .BR read (2) | |
137 | fails with the error | |
138 | .BR EINVAL . | |
4d2b74dd | 139 | .SS inotify events |
c13182ef | 140 | The |
4d2b74dd MK |
141 | .BR inotify_add_watch (2) |
142 | .I mask | |
c13182ef | 143 | argument and the |
4d2b74dd MK |
144 | .I mask |
145 | field of the | |
146 | .I inotify_event | |
147 | structure returned when | |
148 | .BR read (2)ing | |
149 | an inotify file descriptor are both bit masks identifying | |
150 | inotify events. | |
151 | The following bits can be specified in | |
152 | .I mask | |
153 | when calling | |
63f6a20a | 154 | .BR inotify_add_watch (2) |
c13182ef | 155 | and may be returned in the |
4d2b74dd MK |
156 | .I mask |
157 | field returned by | |
63f6a20a | 158 | .BR read (2): |
4d2b74dd | 159 | .TS |
4d2b74dd | 160 | lB l. |
4d2b74dd | 161 | IN_ACCESS File was accessed (read) (*) |
c13182ef | 162 | IN_ATTRIB Metadata changed (permissions, timestamps, |
4d2b74dd MK |
163 | extended attributes, etc.) (*) |
164 | IN_CLOSE_WRITE File opened for writing was closed (*) | |
165 | IN_CLOSE_NOWRITE File not opened for writing was closed (*) | |
166 | IN_CREATE File/directory created in watched directory (*) | |
167 | IN_DELETE File/directory deleted from watched directory (*) | |
168 | IN_DELETE_SELF Watched file/directory was itself deleted | |
169 | IN_MODIFY File was modified (*) | |
170 | IN_MOVE_SELF Watched file/directory was itself moved | |
171 | IN_MOVED_FROM File moved out of watched directory (*) | |
172 | IN_MOVED_TO File moved into watched directory (*) | |
173 | IN_OPEN File was opened (*) | |
174 | .TE | |
4d2b74dd | 175 | .PP |
c13182ef MK |
176 | When monitoring a directory, |
177 | the events marked with an asterisk (*) above can occur for | |
4d2b74dd MK |
178 | files in the directory, in which case the |
179 | .I name | |
180 | field in the returned | |
181 | .I inotify_event | |
182 | structure identifies the name of the file within the directory. | |
183 | .PP | |
184 | The | |
185 | .B IN_ALL_EVENTS | |
186 | macro is defined as a bit mask of all of the above events. | |
187 | This macro can be used as the | |
188 | .I mask | |
189 | argument when calling | |
63f6a20a | 190 | .BR inotify_add_watch (2). |
4d2b74dd MK |
191 | |
192 | Two additional convenience macros are | |
193 | .BR IN_MOVE , | |
194 | which equates to | |
195 | IN_MOVED_FROM|IN_MOVED_TO, | |
196 | and | |
0daa9e92 | 197 | .B IN_CLOSE |
4d2b74dd MK |
198 | which equates to |
199 | IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. | |
200 | .PP | |
c13182ef | 201 | The following further bits can be specified in |
4d2b74dd MK |
202 | .I mask |
203 | when calling | |
63f6a20a | 204 | .BR inotify_add_watch (2): |
4d2b74dd | 205 | .TS |
4d2b74dd | 206 | lB l. |
c13182ef | 207 | IN_DONT_FOLLOW Don't dereference \fIpathname\fP if it is a symbolic link |
25d63cde | 208 | (Since Linux 2.6.15) |
b41beb55 | 209 | IN_MASK_ADD Add (OR) events to watch mask for this pathname if |
4d2b74dd | 210 | it already exists (instead of replacing mask) |
c13182ef | 211 | IN_ONESHOT Monitor \fIpathname\fP for one event, then remove from |
4d2b74dd | 212 | watch list |
b41beb55 | 213 | IN_ONLYDIR Only watch \fIpathname\fP if it is a directory |
25d63cde | 214 | (Since Linux 2.6.15) |
4d2b74dd | 215 | .TE |
4d2b74dd MK |
216 | .PP |
217 | The following bits may be set in the | |
218 | .I mask | |
219 | field returned by | |
63f6a20a | 220 | .BR read (2): |
4d2b74dd | 221 | .TS |
4d2b74dd | 222 | lB l. |
63f6a20a | 223 | IN_IGNORED Watch was removed explicitly (\fBinotify_rm_watch\fP(2)) |
4d2b74dd MK |
224 | or automatically (file was deleted, or |
225 | file system was unmounted) | |
226 | IN_ISDIR Subject of this event is a directory | |
227 | IN_Q_OVERFLOW Event queue overflowed (\fIwd\fP is \-1 for this event) | |
228 | IN_UNMOUNT File system containing watched object was unmounted | |
229 | .TE | |
4d2b74dd | 230 | .SS /proc interfaces |
c13182ef | 231 | The following interfaces can be used to limit the amount of |
4d2b74dd MK |
232 | kernel memory consumed by inotify: |
233 | .TP | |
0daa9e92 | 234 | .I /proc/sys/fs/inotify/max_queued_events |
4d2b74dd MK |
235 | The value in this file is used when an application calls |
236 | .BR inotify_init (2) | |
c13182ef | 237 | to set an upper limit on the number of events that can be |
4d2b74dd MK |
238 | queued to the corresponding inotify instance. |
239 | Events in excess of this limit are dropped, but an | |
240 | .B IN_Q_OVERFLOW | |
241 | event is always generated. | |
242 | .TP | |
0daa9e92 | 243 | .I /proc/sys/fs/inotify/max_user_instances |
c13182ef | 244 | This specifies an upper limit on the number of inotify instances |
4d2b74dd MK |
245 | that can be created per real user ID. |
246 | .TP | |
0daa9e92 | 247 | .I /proc/sys/fs/inotify/max_user_watches |
c13182ef | 248 | This specifies a limit on the number of watches that can be associated |
4d2b74dd | 249 | with each inotify instance. |
2b2581ee MK |
250 | .SH "VERSIONS" |
251 | Inotify was merged into the 2.6.13 Linux kernel. | |
252 | The required library interfaces were added to glibc in version 2.4. | |
253 | .RB ( IN_DONT_FOLLOW , | |
254 | .BR IN_MASK_ADD , | |
255 | and | |
256 | .B IN_ONLYDIR | |
257 | were only added in version 2.5.) | |
258 | .SH "CONFORMING TO" | |
8382f16d | 259 | The inotify API is Linux-specific. |
4d2b74dd MK |
260 | .SH "NOTES" |
261 | Inotify file descriptors can be monitored using | |
262 | .BR select (2), | |
263 | .BR poll (2), | |
c13182ef | 264 | and |
2315114c | 265 | .BR epoll (7). |
4d2b74dd | 266 | |
c13182ef MK |
267 | If successive output inotify events produced on the |
268 | inotify file descriptor are identical (same | |
269 | .IR wd , | |
270 | .IR mask , | |
4d2b74dd MK |
271 | .IR cookie , |
272 | and | |
273 | .IR name ) | |
274 | then they are coalesced into a single event. | |
275 | ||
c13182ef MK |
276 | The events returned by reading from an inotify file descriptor |
277 | form an ordered queue. | |
278 | Thus, for example, it is guaranteed that when renaming from | |
279 | one directory to another, events will be produced in the | |
4d2b74dd MK |
280 | correct order on the inotify file descriptor. |
281 | ||
282 | The | |
283 | .B FIONREAD | |
63f6a20a | 284 | .BR ioctl (2) |
c13182ef | 285 | returns the number of bytes available to read from an |
4d2b74dd MK |
286 | inotify file descriptor. |
287 | ||
288 | Inotify monitoring of directories is not recursive: | |
289 | to monitor subdirectories under a directory, | |
290 | additional watches must be created. | |
ed7b0235 MK |
291 | .SH "BUGS" |
292 | In kernels before 2.6.16, the | |
293 | .B IN_ONESHOT | |
c13182ef | 294 | .I mask |
ed7b0235 | 295 | flag does not work. |
4d2b74dd MK |
296 | .SH "SEE ALSO" |
297 | .BR inotify_add_watch (2), | |
298 | .BR inotify_init (2), | |
299 | .BR inotify_rm_watch (2), | |
300 | .BR read (2), | |
301 | .BR stat (2), | |
302 | .IR Documentation/filesystems/inotify.txt . |