Inotify

Inotify (inode notify) is a Linux kernel subsystem that acts to extend filesystems to notice changes to the filesystem, and report those changes to applications. It replaces an earlier facility, dnotify, which had similar goals.

Inotify was created by John McCutchan, and it was merged into the Linux kernel mainline in kernel version 2.6.13, released on August 29, 2005; later kernel versions included further improvements. The required library interfaces were added into the GNU C Library (glibc) in its version 2.4, released in March 2006, while the support for inotify was completed in glibc version 2.5, released in September 2006.

One major use is in desktop search utilities like Beagle, where its functionality permits reindexing of changed files without scanning the filesystem for changes every few minutes, which would be very inefficient. By being told directly by the kernel that a file has changed, indexing utilities can achieve change-to-reindexing times of only about a second.

Inotify can also be used to automatically update directory views, reload configuration files, log changes, backup, synchronize, and upload.

Usage

Inotify is used through a series of system calls specifically created for inotify.

#include <sys/inotify.h>

Include this header file to use inotify. It defines the C struct (inotify_event) which describes the packet returned by the kernel for a read() call, as well as several symbolic constants for event types.

int inotify_init(void)

This function creates an inotify instance. It returns a file descriptor which is used to add watches, and from which all events are read. Calls to read() are used to receive event information. To prevent the need for polling, read() blocks until an event is received. However, select() and poll() may be used with the returned file descriptor if desired. The FIONREAD ioctl() may be called to indicate the number of bytes which can be read out of the returned file descriptor.

int inotify_add_watch(int fd, const char *pathname, int mask)

This function starts watching the inode pointed to by pathname for events contained in mask, or modifies the active mask for pathname. It returns a watch descriptor which is unique (within this inotify instance) to the inode pointed to by the pathname (multiple pathnames can point to the same inode/watch descriptor, for example due to symbolic links being followed).

int inotify_rm_watch(int fd, int wd)

Calling this function cancels a watch on the given watch descriptor for the given inotify instance.

Events generated by inotify contain the following information:

Identifier	contents
wd	watch descriptor
mask	bitmask of events which happened to the pathname identified by wd
cookie	Opaque identifier (cookie) used to tie separate IN_MOVED_FROM and IN_MOVED_TO events together
len	length of name field
name	the (optional, NUL terminated) filename associated with this event (relative to its parent directory)

name occupies an integral number of inotify_event-sized bytes (i.e., len will be a multiple of the size of the struct). This is possible because the end of the string is marked by a NUL byte, so the returned packet is simply padded to match the correct length. If the read() call did not specify enough bytes to read an event (for example, if a single struct inotify_event-sized buffer is specified, and a name needs to be returned), the read() call will return 0. The process can then increase the number of bytes to read to receive the complete event description.

Some of the events that can be monitored for are:

• IN_ACCESS - read of the file
• IN_MODIFY - file was modified (e.g. write(2) was called)
• IN_ATTRIB - attributes of file changed (chmod(2), chown(2), etc.)
• IN_OPEN - file is opened
• IN_CLOSE_WRITE - sent when a file opened for writing is closed
• IN_CLOSE_NOWRITE - sent when a file opened not for writing is closed
• IN_MOVED_FROM and IN_MOVED_TO - when the file is moved or renamed
• IN_DELETE - a file/directory unlinked (deleted)
• IN_CREATE - a file in a watched directory is created
• IN_DELETE_SELF - file monitored is deleted

Limitations

Limitations imposed by inotify include the following:

• Inotify does not support recursively watching directories, meaning that a separate inotify watch must be created for every subdirectory.
• Inotify does report some but not all events in sysfs and procfs.
• Notification via inotify requires the kernel to be aware of all relevant filesystem events, which is not always possible for networked filesystems such as NFS where changes made by one client are not immediately broadcast to other clients.
• Rename events are not handled directly; i.e., inotify issues two separate events that must be examined and matched in a context of potential race conditions.

History

• July 2004: the first release announcement
• August 29, 2005: Linux kernel version 2.6.13 released, containing merged inotify code
• March 2006: GNU C Library (glibc) version 2.4 released, bringing initial inotify support
• September 2006: Glibc version 2.5 released, bringing complete inotify support

Advantages over dnotify

There are a number of advantages when using inotify when compared to the older dnotify API that it replaced. With dnotify, a program had to use one file descriptor for each directory that it was monitoring. This can become a bottleneck since the limit of file descriptors per process could be reached. Later, fanotify was created to overcome this issue. The use of file descriptors along with dnotify also proved to be a problem when using removable media. Devices could not be unmounted since file descriptors kept the resource busy.

Another drawback of dnotify is the level of granularity, since programmers can only monitor changes at the directory level. To access detailed information about the environmental changes that occur when a notification message is sent, a stat structure must be used; this is considered a necessary evil in that a cache of stat structures has to be maintained, for every new stat structure generated a comparison is run against the cached one.

The inotify API uses fewer file descriptors, allowing programmers to use the established select and poll interface, rather than the signal notification system used by dnotify. This also makes integration with existing select- or poll-based libraries (like GLib) easier.

See also

• File Alteration Monitor
• Gamin
• DMAPI
• kqueue
• FSEvents

External links

• Kernel Korner - Intro to inotify by Robert Love (2005)
• LWN Article on Inotify Watching filesystem events with inotify (partly out of date)
• IBM Article Monitor Linux file system events with inotify.
• Filesystem notification, part 1: An overview of dnotify and inotify. LWN.net 2014.