INOTIFY(7) Standards, Environments, and Macros INOTIFY(7)

inotify - Linux-compatible file event notification facility

#include <sys/inotify.h>

inotify is a facility for receiving file system events on specified files or directories. When monitoring a directory, inotify can be used to retrieve events not only on the directory, but also on any files that the directory contains. inotify originated with Linux, and this facility is designed to be binary-compatible with the Linux facility, including the following interfaces:

inotify_init(3C) creates an inotify instance, returning a file descriptor associated with the in-kernel event queue.
inotify_init1(3C) also creates an inotify instance, but allows for a flags argument that controls some attributes of the returned file descriptor.
inotify_add_watch(3C) allows a watch of a particular file or directory to be added to a watch list associated with the specified inotify instance. inotify_add_watch(3C) returns a watch descriptor that will be reflected in the wd member of the inotify_event structure returned via a read(2) of the instance.
inotify_rm_watch(3C) removes the watch that corresponds to the specified watch descriptor.

When all file descriptors referring to a particular inotify instance are closed, the instance and all watches associated with that instance are freed.

To consume events on an inotify instance, an application should issue a read(2) to the instance. If no events are available (and the inotify instance has not been explicitly made non-blocking via inotify_init1(3C)) the read(2) will block until a watched event occurs. If and when events are available, read(2) will return an array of the following structures:

struct inotify_event {

int wd; /* watch descriptor */
uint32_t mask; /* mask of event */
uint32_t cookie; /* cookie for associating renames */
uint32_t len; /* size of name field */
char name[]; /* optional name */ };

wd contains the watch descriptor that corresponds to the event, as returned by inotify_add_watch(3C).

mask is a bitwise OR of event masks (see below) that describes the event.

cookie is an opaque value that can be used to associate different events into a single logical event. In particular, it allows consumers to associate IN_MOVED_FROM events with subsequent IN_MOVED_TO events.

len denotes the length of the name field, including any padding required for trailing null bytes and alignment. The size of the entire event is therefore the size of the inotify_event structure plus the value of len.

name contains the name of the file associated with the event, if any. This field is only present when the watched entity is a directory and the event corresponds to a file that was contained by the watched directory (though see NOTES and WARNINGS for details and limitations). When present, name is null terminated, and may contain additional zero bytes to pad for alignment. (The length of this field -- including any bytes for alignment -- is denoted by the len field.)

The events that can be generated on a watched entity are as follows:

Event Description
IN_ACCESS File/directory was accessed
IN_ATTRIB File/directory attributes were changed
IN_CLOSE_WRITE File/directory opened for writing was closed
IN_CLOSE_NOWRITE File/directory not opened for writing was closed
IN_CREATE File/directory created in watched directory
IN_DELETE File/directory deleted from watched directory
IN_DELETE_SELF Watched file/directory was deleted
IN_MODIFY File/directory was modified
IN_MODIFY_SELF Watched file/directory was modified
IN_MOVED_FROM File was renamed from entity in watched directory
IN_MOVED_TO File was renamed to entity in watched directory
IN_OPEN File/directory was opened

Of these, all events except IN_MOVE_SELF and IN_DELETE_SELF can refer to either the watched entity or (if the watched entity is a directory) a file or directory contained by the watched directory. (See NOTES and WARNINGS, below for details on this mechanism and its limitations.) If the event corresponds to a contained entity, name will be set to the name of the affected entity.

In addition to speciyfing events of interest, watched events may be modified by potentially setting any of the following when adding a watch via inotify_add_watch(3C):


Don't follow the specified pathname if it is a symbolic link.


If watching a directory and a contained entity becomes unlinked, cease generating events for that entity. (By default, contained entities will continue to generate events on their former parent directory.)


If the specified pathname is already being watched, the specified events will be added to the watched events instead of the default behavior of replacing them. (If one may forgive the editorializing, this particular interface gewgaw seems entirely superfluous, and a canonical example of feasibility trumping wisdom.)


Once an event has been generated for the watched entity, remove the watch from the watch list as if inotify_rm_watch(3C) had been called on it (thereby inducing an IN_IGNORED event).


Only watch the specified pathname if it is a directory.

In addition to the specified events, the following bits may be specified in the mask field as returned from read(2):


A watch was removed explicitly (i.e, via inotify_rm_watch(3C)) or implicitly (e.g., because IN_ONESHOT was set or because the watched entity was deleted).


The entity inducing the event is a directory.


The event queue exceeded the maximum event queue length per instance. (By default, this is 16384, but it can be tuned by setting inotify_maxevents via /etc/system.)


The filesystem containing the watched entity was unmounted.

inotify instances can be monitored via poll(2), port_get(3C), epoll(7), etc.

The event queue associated with an inotify instance is serialized and ordered: events will be placed on the tail of the queue in the order that they occur.

If at the time an event occurs the tail of the event queue is identical to the newly received event, the newly received event will be dropped, effectively coalescing the two events.

When watching a directory and receieving events on contained elements (i.e., a contained file or subdirectory), note that the information received in the name field may be stale: the file may have been renamed between the event and its processing. If a file has been unlinked (and if IN_EXCL_UNLINK has not been set), the name will reflect the last name that resolved to the file. If a new file is created in the same directory with the old name, events on the new file and the old (unlinked) file will become undistinguishable.

The number of bytes that are available to be read on an inotify instance can be determined via a FIONREAD ioctl(2).

While a best effort has been made to mimic the Linux semantics, there remains a fundamental difference with respect to hard links: on Linux, if a file has multiple hard links to it, a notification on a watched directory or file will be received if and only if that event was received via the watched path. For events that are induced by open files (such as IN_MODIFY), these semantics seem peculiar: the watched file is in fact changing, but because it is not changing via the watched path, no notification is received. By contrast, the implementation here will always yield an event in this case -- even if the event was induced by an open(2) via an unwatched path. If an event occurs within a watched directory on a file for which there exist multiple hard links within the same (watched) directory, the event's name will correspond to one of the links to the file. If multiple hard links exist to the same file in the same watched directory and one of the links is removed, notifications may not necessarily continue to be received for the file, despite the (remaining) link in the watched directory; users of inotify should exercise extreme caution when watching directories that contain files with multiple hard links in the same directory.

inotify_init(3C), inotify_init1(3C), inotify_add_watch(3C), inotify_rm_watch(3C), port_get(3C), epoll(7)

September 17, 2014 OmniOS