]>
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 | |
10d76543 MK |
18 | .\" the use of the information contained herein. The author(s) may not |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
4d2b74dd MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
0000daa5 | 26 | .TH INOTIFY 7 2008-03-25 "Linux" "Linux Programmer's Manual" |
4d2b74dd | 27 | .SH NAME |
3a20b4ca | 28 | inotify \- monitoring file system events |
4d2b74dd MK |
29 | .SH DESCRIPTION |
30 | The | |
c13182ef | 31 | .I inotify |
4d2b74dd MK |
32 | API provides a mechanism for monitoring file system events. |
33 | Inotify can be used to monitor individual files, | |
34 | or to monitor directories. | |
35 | When a directory is monitored, inotify will return events | |
36 | for the directory itself, and for files inside the directory. | |
37 | ||
c13182ef | 38 | The following system calls are used with this API: |
63f6a20a MK |
39 | .BR inotify_init (2), |
40 | .BR inotify_add_watch (2), | |
41 | .BR inotify_rm_watch (2), | |
42 | .BR read (2), | |
c13182ef | 43 | and |
63f6a20a | 44 | .BR close (2). |
4d2b74dd MK |
45 | |
46 | .BR inotify_init (2) | |
c13182ef | 47 | creates an inotify instance and returns a file descriptor |
a2cc46ca | 48 | referring to the inotify instance. |
4d2b74dd MK |
49 | |
50 | .BR inotify_add_watch (2) | |
a2cc46ca | 51 | manipulates the "watch list" associated with an inotify instance. |
3a065ac0 | 52 | Each item ("watch") in the watch list specifies the pathname of |
c13182ef | 53 | a file or directory, |
4d2b74dd MK |
54 | along with some set of events that the kernel should monitor for the |
55 | file referred to by that pathname. | |
63f6a20a | 56 | .BR inotify_add_watch (2) |
4d2b74dd MK |
57 | either creates a new watch item, or modifies an existing watch. |
58 | Each watch has a unique "watch descriptor", an integer | |
59 | returned by | |
63f6a20a | 60 | .BR inotify_add_watch (2) |
4d2b74dd MK |
61 | when the watch is created. |
62 | ||
63 | .BR inotify_rm_watch (2) | |
64 | removes an item from an inotify watch list. | |
65 | ||
c13182ef | 66 | When all file descriptors referring to an inotify |
a2cc46ca | 67 | instance have been closed, |
c13182ef | 68 | the underlying object and its resources are |
a2cc46ca | 69 | freed for re-use by the kernel; |
4d2b74dd MK |
70 | all associated watches are automatically freed. |
71 | ||
72 | To determine what events have occurred, an application | |
73 | .BR read (2)s | |
74 | from the inotify file descriptor. | |
c13182ef | 75 | If no events have so far occurred, then, |
11da88fb | 76 | assuming a blocking file descriptor, |
63f6a20a | 77 | .BR read (2) |
4d2b74dd MK |
78 | will block until at least one event occurs. |
79 | ||
80 | Each successful | |
63f6a20a | 81 | .BR read (2) |
4d2b74dd | 82 | returns a buffer containing one or more of the following structures: |
a08ea57c | 83 | .in +4n |
4d2b74dd MK |
84 | .nf |
85 | ||
86 | struct inotify_event { | |
87 | int wd; /* Watch descriptor */ | |
88 | uint32_t mask; /* Mask of events */ | |
c13182ef | 89 | uint32_t cookie; /* Unique cookie associating related |
4d2b74dd MK |
90 | events (for rename(2)) */ |
91 | uint32_t len; /* Size of 'name' field */ | |
92 | char name[]; /* Optional null-terminated name */ | |
93 | }; | |
94 | .fi | |
a08ea57c | 95 | .in |
4d2b74dd MK |
96 | |
97 | .I wd | |
98 | identifies the watch for which this event occurs. | |
c13182ef | 99 | It is one of the watch descriptors returned by a previous call to |
63f6a20a | 100 | .BR inotify_add_watch (2). |
4d2b74dd MK |
101 | |
102 | .I mask | |
103 | contains bits that describe the event that occurred (see below). | |
104 | ||
105 | .I cookie | |
106 | is a unique integer that connects related events. | |
107 | Currently this is only used for rename events, and | |
108 | allows the resulting pair of | |
109 | .B IN_MOVE_FROM | |
c13182ef | 110 | and |
4d2b74dd MK |
111 | .B IN_MOVE_TO |
112 | events to be connected by the application. | |
113 | ||
c13182ef | 114 | The |
4d2b74dd MK |
115 | .I name |
116 | field is only present when an event is returned | |
c13182ef | 117 | for a file inside a watched directory; |
4d2b74dd | 118 | it identifies the file pathname relative to the watched directory. |
c13182ef | 119 | This pathname is null-terminated, |
ad31978e | 120 | and may include further null bytes to align subsequent reads to a |
4d2b74dd MK |
121 | suitable address boundary. |
122 | ||
123 | The | |
124 | .I len | |
c13182ef | 125 | field counts all of the bytes in |
4d2b74dd | 126 | .IR name , |
c13182ef | 127 | including the null bytes; |
4d2b74dd MK |
128 | the length of each |
129 | .I inotify_event | |
130 | structure is thus | |
131 | .IR "sizeof(inotify_event)+len" . | |
c7e3ee6f | 132 | |
988db661 | 133 | The behavior when the buffer given to |
c7e3ee6f | 134 | .BR read (2) |
988db661 | 135 | is too small to return information about the next event depends |
c7e3ee6f MK |
136 | on the kernel version: in kernels before 2.6.21, |
137 | .BR read (2) | |
138 | returns 0; since kernel 2.6.21, | |
139 | .BR read (2) | |
140 | fails with the error | |
141 | .BR EINVAL . | |
4d2b74dd | 142 | .SS inotify events |
c13182ef | 143 | The |
4d2b74dd MK |
144 | .BR inotify_add_watch (2) |
145 | .I mask | |
c13182ef | 146 | argument and the |
4d2b74dd MK |
147 | .I mask |
148 | field of the | |
149 | .I inotify_event | |
150 | structure returned when | |
151 | .BR read (2)ing | |
152 | an inotify file descriptor are both bit masks identifying | |
153 | inotify events. | |
154 | The following bits can be specified in | |
155 | .I mask | |
156 | when calling | |
63f6a20a | 157 | .BR inotify_add_watch (2) |
c13182ef | 158 | and may be returned in the |
4d2b74dd MK |
159 | .I mask |
160 | field returned by | |
63f6a20a | 161 | .BR read (2): |
3f174f7d MK |
162 | .RS 4 |
163 | .sp | |
164 | .PD 0 | |
165 | .TP 18 | |
166 | .B IN_ACCESS | |
167 | File was accessed (read) (*). | |
168 | .TP | |
169 | .B IN_ATTRIB | |
170 | Metadata changed (permissions, timestamps, extended attributes, etc.) (*). | |
171 | .TP | |
172 | .B IN_CLOSE_WRITE | |
173 | File opened for writing was closed (*). | |
174 | .TP | |
175 | .B IN_CLOSE_NOWRITE | |
176 | File not opened for writing was closed (*). | |
177 | .TP | |
178 | .B IN_CREATE | |
179 | File/directory created in watched directory (*). | |
180 | .TP | |
181 | .B IN_DELETE | |
182 | File/directory deleted from watched directory (*). | |
183 | .TP | |
184 | .B IN_DELETE_SELF | |
185 | Watched file/directory was itself deleted. | |
186 | .TP | |
187 | .B IN_MODIFY | |
188 | File was modified (*). | |
189 | .TP | |
190 | .B IN_MOVE_SELF | |
191 | Watched file/directory was itself moved. | |
192 | .TP | |
193 | .B IN_MOVED_FROM | |
194 | File moved out of watched directory (*). | |
195 | .TP | |
196 | .B IN_MOVED_TO | |
197 | File moved into watched directory (*). | |
198 | .TP | |
199 | .B IN_OPEN | |
200 | File was opened (*). | |
201 | .PD | |
202 | .RE | |
4d2b74dd | 203 | .PP |
c13182ef MK |
204 | When monitoring a directory, |
205 | the events marked with an asterisk (*) above can occur for | |
4d2b74dd MK |
206 | files in the directory, in which case the |
207 | .I name | |
208 | field in the returned | |
209 | .I inotify_event | |
210 | structure identifies the name of the file within the directory. | |
211 | .PP | |
212 | The | |
213 | .B IN_ALL_EVENTS | |
214 | macro is defined as a bit mask of all of the above events. | |
215 | This macro can be used as the | |
216 | .I mask | |
217 | argument when calling | |
63f6a20a | 218 | .BR inotify_add_watch (2). |
4d2b74dd MK |
219 | |
220 | Two additional convenience macros are | |
221 | .BR IN_MOVE , | |
222 | which equates to | |
223 | IN_MOVED_FROM|IN_MOVED_TO, | |
224 | and | |
0daa9e92 | 225 | .B IN_CLOSE |
4d2b74dd MK |
226 | which equates to |
227 | IN_CLOSE_WRITE|IN_CLOSE_NOWRITE. | |
228 | .PP | |
c13182ef | 229 | The following further bits can be specified in |
4d2b74dd MK |
230 | .I mask |
231 | when calling | |
63f6a20a | 232 | .BR inotify_add_watch (2): |
3f174f7d MK |
233 | .RS 4 |
234 | .sp | |
235 | .PD 0 | |
236 | .TP 18 | |
31daf529 MK |
237 | .BR IN_DONT_FOLLOW " (since Linux 2.6.15)" |
238 | Don't dereference \fIpathname\fP if it is a symbolic link. | |
dda869a4 MK |
239 | .TP |
240 | .B IN_MASK_ADD | |
241 | Add (OR) events to watch mask for this pathname if | |
242 | it already exists (instead of replacing mask). | |
243 | .TP | |
244 | .B IN_ONESHOT | |
245 | Monitor \fIpathname\fP for one event, then remove from | |
246 | watch list. | |
247 | .TP | |
31daf529 MK |
248 | .BR IN_ONLYDIR " (since Linux 2.6.15)" |
249 | Only watch \fIpathname\fP if it is a directory. | |
3f174f7d MK |
250 | .PD |
251 | .RE | |
4d2b74dd MK |
252 | .PP |
253 | The following bits may be set in the | |
254 | .I mask | |
255 | field returned by | |
63f6a20a | 256 | .BR read (2): |
3f174f7d MK |
257 | .RS 4 |
258 | .sp | |
259 | .PD 0 | |
260 | .TP 18 | |
dda869a4 MK |
261 | .B IN_IGNORED |
262 | Watch was removed explicitly (\fBinotify_rm_watch\fP(2)) | |
263 | or automatically (file was deleted, or file system was unmounted). | |
264 | .TP | |
265 | .B IN_ISDIR | |
266 | Subject of this event is a directory. | |
267 | .TP | |
268 | .B IN_Q_OVERFLOW | |
269 | Event queue overflowed (\fIwd\fP is \-1 for this event). | |
270 | .TP | |
271 | .B IN_UNMOUNT | |
272 | File system containing watched object was unmounted. | |
3f174f7d MK |
273 | .PD |
274 | .RE | |
4d2b74dd | 275 | .SS /proc interfaces |
c13182ef | 276 | The following interfaces can be used to limit the amount of |
4d2b74dd MK |
277 | kernel memory consumed by inotify: |
278 | .TP | |
0daa9e92 | 279 | .I /proc/sys/fs/inotify/max_queued_events |
4d2b74dd MK |
280 | The value in this file is used when an application calls |
281 | .BR inotify_init (2) | |
c13182ef | 282 | to set an upper limit on the number of events that can be |
4d2b74dd MK |
283 | queued to the corresponding inotify instance. |
284 | Events in excess of this limit are dropped, but an | |
285 | .B IN_Q_OVERFLOW | |
286 | event is always generated. | |
287 | .TP | |
0daa9e92 | 288 | .I /proc/sys/fs/inotify/max_user_instances |
c13182ef | 289 | This specifies an upper limit on the number of inotify instances |
4d2b74dd MK |
290 | that can be created per real user ID. |
291 | .TP | |
0daa9e92 | 292 | .I /proc/sys/fs/inotify/max_user_watches |
c13182ef | 293 | This specifies a limit on the number of watches that can be associated |
4d2b74dd | 294 | with each inotify instance. |
2b2581ee MK |
295 | .SH "VERSIONS" |
296 | Inotify was merged into the 2.6.13 Linux kernel. | |
297 | The required library interfaces were added to glibc in version 2.4. | |
298 | .RB ( IN_DONT_FOLLOW , | |
299 | .BR IN_MASK_ADD , | |
300 | and | |
301 | .B IN_ONLYDIR | |
302 | were only added in version 2.5.) | |
303 | .SH "CONFORMING TO" | |
8382f16d | 304 | The inotify API is Linux-specific. |
4d2b74dd MK |
305 | .SH "NOTES" |
306 | Inotify file descriptors can be monitored using | |
307 | .BR select (2), | |
308 | .BR poll (2), | |
c13182ef | 309 | and |
2315114c | 310 | .BR epoll (7). |
0000daa5 MK |
311 | When an event is available, the file descriptor indicates as readable. |
312 | ||
313 | Since Linux 2.6.25, | |
314 | signal-driven I/O notification is available for inotify file descriptors; | |
315 | see the discussion of | |
316 | .B F_SETFL | |
317 | (for setting the | |
318 | .B O_ASYNC | |
319 | flag), | |
320 | .BR F_SETOWN , | |
321 | and | |
322 | .B F_SETSIG | |
323 | in | |
324 | .BR fcntl (2). | |
325 | The | |
326 | .I siginfo_t | |
327 | structure (described in | |
328 | .BR sigaction (2)) | |
329 | that is passed to the signal handler has the following fields set: | |
330 | .IR si_fd | |
331 | is set to the inotify file descriptor number; | |
332 | .IR si_signo | |
333 | is set to the signal number; | |
334 | .IR si_code | |
335 | is set to | |
336 | .BR POLL_IN ; | |
337 | and | |
338 | .B POLLIN | |
339 | is set in | |
340 | .IR si_band . | |
4d2b74dd | 341 | |
c13182ef MK |
342 | If successive output inotify events produced on the |
343 | inotify file descriptor are identical (same | |
344 | .IR wd , | |
345 | .IR mask , | |
4d2b74dd MK |
346 | .IR cookie , |
347 | and | |
348 | .IR name ) | |
349 | then they are coalesced into a single event. | |
350 | ||
c13182ef MK |
351 | The events returned by reading from an inotify file descriptor |
352 | form an ordered queue. | |
353 | Thus, for example, it is guaranteed that when renaming from | |
354 | one directory to another, events will be produced in the | |
4d2b74dd MK |
355 | correct order on the inotify file descriptor. |
356 | ||
357 | The | |
358 | .B FIONREAD | |
63f6a20a | 359 | .BR ioctl (2) |
c13182ef | 360 | returns the number of bytes available to read from an |
4d2b74dd MK |
361 | inotify file descriptor. |
362 | ||
363 | Inotify monitoring of directories is not recursive: | |
364 | to monitor subdirectories under a directory, | |
365 | additional watches must be created. | |
ed7b0235 MK |
366 | .SH "BUGS" |
367 | In kernels before 2.6.16, the | |
368 | .B IN_ONESHOT | |
c13182ef | 369 | .I mask |
ed7b0235 | 370 | flag does not work. |
4d2b74dd MK |
371 | .SH "SEE ALSO" |
372 | .BR inotify_add_watch (2), | |
373 | .BR inotify_init (2), | |
374 | .BR inotify_rm_watch (2), | |
375 | .BR read (2), | |
376 | .BR stat (2), | |
377 | .IR Documentation/filesystems/inotify.txt . |