NAME
inotify - monitoring file system events DESCRIPTION The inotify API provides a mechanism for monitoring file system events. Inotify can be used to monitor individual files, or to monitor directo‐ ries. When a directory is monitored, inotify will return events for the directory itself, and for files inside the directory. The following system calls are used with this API: inotifyinit(2) (or inotifyinit1(2)), inotifyaddwatch(2), inotifyrmwatch(2), read(2), and close(2). inotifyinit(2) creates an inotify instance and returns a file descrip‐ tor referring to the inotify instance. The more recent ino‐ tifyinit1(2) is like inotifyinit(2), but provides some extra func‐ tionality. inotifyaddwatch(2) manipulates the "watch list" associated with an inotify instance. Each item ("watch") in the watch list specifies the pathname of a file or directory, along with some set of events that the kernel should monitor for the file referred to by that pathname. ino‐ tifyaddwatch(2) either creates a new watch item, or modifies an existing watch. Each watch has a unique "watch descriptor", an integer returned by inotifyaddwatch(2) when the watch is created. inotifyrmwatch(2) removes an item from an inotify watch list. When all file descriptors referring to an inotify instance have been closed, the underlying object and its resources are freed for reuse by the kernel; all associated watches are automatically freed. To determine what events have occurred, an application read(2)s from the inotify file descriptor. If no events have so far occurred, then, assuming a blocking file descriptor, read(2) will block until at least one event occurs (unless interrupted by a signal, in which case the call fails with the error EINTR; see signal(7)). Each successful read(2) returns a buffer containing one or more of the following structures: struct inotifyevent { int wd; /* Watch descriptor */ uint32t mask; /* Mask of events */ uint32t cookie; /* Unique cookie associating related events (for rename(2)) */ uint32t len; /* Size of name field */
char name[]; /* Optional null-terminated name */ }; wd identifies the watch for which this event occurs. It is one of the watch descriptors returned by a previous call to inotifyaddwatch(2). mask contains bits that describe the event that occurred (see below). cookie is a unique integer that connects related events. Currently this is used only for rename events, and allows the resulting pair of INMOVEDFROM and INMOVEDTO events to be connected by the applica‐ tion. For all other event types, cookie is set to 0. The name field is present only when an event is returned for a file inside a watched directory; it identifies the file pathname relative to
the watched directory. This pathname is null-terminated, and may include further null bytes ('\0') to align subsequent reads to a suit‐ able address boundary. The len field counts all of the bytes in name, including the null bytes; the length of each inotifyevent structure is thus sizeof(struct inotifyevent)+len. The behavior when the buffer given to read(2) is too small to return information about the next event depends on the kernel version: in ker‐ nels before 2.6.21, read(2) returns 0; since kernel 2.6.21, read(2) fails with the error EINVAL. Specifying a buffer of size sizeof(struct inotifyevent) + NAMEMAX + 1 will be sufficient to read at least one event. inotify events The inotifyaddwatch(2) mask argument and the mask field of the ino‐ tifyevent structure returned when read(2)ing an inotify file descrip‐ tor are both bit masks identifying inotify events. The following bits can be specified in mask when calling inotifyaddwatch(2) and may be returned in the mask field returned by read(2): INACCESS File was accessed (read) (*). INATTRIB Metadata changed, e.g., permissions, timestamps, extended attributes, link count (since Linux 2.6.25), UID, GID, etc. (*). INCLOSEWRITE File opened for writing was closed (*). INCLOSENOWRITE File not opened for writing was closed (*). INCREATE File/directory created in watched directory (*). INDELETE File/directory deleted from watched directory (*). INDELETESELF Watched file/directory was itself deleted. INMODIFY File was modified (*). INMOVESELF Watched file/directory was itself moved. INMOVEDFROM Generated for the directory containing the old filename when a file is renamed (*). INMOVEDTO Generated for the directory containing the new filename when a file is renamed (*). INOPEN File was opened (*). When monitoring a directory, the events marked with an asterisk (*) above can occur for files in the directory, in which case the name field in the returned inotifyevent structure identifies the name of the file within the directory. The INALLEVENTS macro is defined as a bit mask of all of the above events. This macro can be used as the mask argument when calling ino‐ tifyaddwatch(2). Two additional convenience macros are INMOVE, which equates to INMOVEDFROM|INMOVEDTO, and INCLOSE, which equates to INCLOSEWRITE|INCLOSENOWRITE. The following further bits can be specified in mask when calling ino‐ tifyaddwatch(2): INDONTFOLLOW (since Linux 2.6.15) Don't dereference pathname if it is a symbolic link. INEXCLUNLINK (since Linux 2.6.36) By default, when watching events on the children of a directory, events are generated for children even after they have been unlinked from the directory. This can result in large numbers of uninteresting events for some applications (e.g., if watching /tmp, in which many applications cre‐ ate temporary files whose names are immediately unlinked). Specifying INEXCLUNLINK changes the default behavior, so that events are not gener‐ ated for children after they have been unlinked from the watched directory. INMASKADD Add (OR) events to watch mask for this pathname if it already exists (instead of replacing mask). INONESHOT Monitor pathname for one event, then remove from watch list. INONLYDIR (since Linux 2.6.15) Only watch pathname if it is a directory. The following bits may be set in the mask field returned by read(2): INIGNORED Watch was removed explicitly (ino‐ tifyrmwatch(2)) or automatically (file was deleted, or file system was unmounted). INISDIR Subject of this event is a directory.
INQOVERFLOW Event queue overflowed (wd is -1 for this event). INUNMOUNT File system containing watched object was unmounted. /proc interfaces The following interfaces can be used to limit the amount of kernel mem‐ ory consumed by inotify: /proc/sys/fs/inotify/maxqueuedevents The value in this file is used when an application calls ino‐ tifyinit(2) to set an upper limit on the number of events that can be queued to the corresponding inotify instance. Events in excess of this limit are dropped, but an INQOVERFLOW event is always generated. /proc/sys/fs/inotify/maxuserinstances This specifies an upper limit on the number of inotify instances that can be created per real user ID. /proc/sys/fs/inotify/maxuserwatches This specifies an upper limit on the number of watches that can be created per real user ID. VERSIONS Inotify was merged into the 2.6.13 Linux kernel. The required library interfaces were added to glibc in version 2.4. (INDONTFOLLOW, INMASKADD, and INONLYDIR were added in version 2.5.) CONFORMING TO
The inotify API is Linux-specific. NOTES Inotify file descriptors can be monitored using select(2), poll(2), and epoll(7). When an event is available, the file descriptor indicates as readable.
Since Linux 2.6.25, signal-driven I/O notification is available for inotify file descriptors; see the discussion of FSETFL (for setting the OASYNC flag), FSETOWN, and FSETSIG in fcntl(2). The siginfot structure (described in sigaction(2)) that is passed to the signal han‐ dler has the following fields set: sifd is set to the inotify file descriptor number; sisigno is set to the signal number; sicode is set to POLLIN; and POLLIN is set in siband. If successive output inotify events produced on the inotify file descriptor are identical (same wd, mask, cookie, and name) then they are coalesced into a single event if the older event has not yet been read (but see BUGS). The events returned by reading from an inotify file descriptor form an ordered queue. Thus, for example, it is guaranteed that when renaming from one directory to another, events will be produced in the correct order on the inotify file descriptor. The FIONREAD ioctl(2) returns the number of bytes available to read from an inotify file descriptor. Limitations and caveats Inotify monitoring of directories is not recursive: to monitor subdi‐ rectories under a directory, additional watches must be created. This can take a significant amount time for large directory trees. The inotify API provides no information about the user or process that triggered the inotify event. In particular, there is no easy way for a process that is monitoring events via inotify to distinguish events that it triggers itself from those that are triggered by other pro‐ cesses. Note that the event queue can overflow. In this case, events are lost. Robust applications should handle the possibility of lost events grace‐ fully. The inotify API identifies affected files by filename. However, by the time an application processes an inotify event, the filename may already have been deleted or renamed. If monitoring an entire directory subtree, and a new subdirectory is created in that tree, be aware that by the time you create a watch for the new subdirectory, new files may already have been created in the subdirectory. Therefore, you may want to scan the contents of the sub‐ directory immediately after adding the watch. BUGS In kernels before 2.6.16, the INONESHOT mask flag does not work. Before kernel 2.6.25, the kernel code that was intended to coalesce successive identical events (i.e., the two most recent events could potentially be coalesced if the older had not yet been read) instead checked if the most recent event could be coalesced with the oldest unread event. SEE ALSO inotifyaddwatch(2), inotifyinit(2), inotifyinit1(2), ino‐ tifyrmwatch(2), read(2), stat(2) Documentation/filesystems/inotify.txt in the Linux kernel source tree COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2013-07-21 INOTIFY(7)