NAME

inotify - Linux-compatible file event notification facility

SYNOPSIS

#include <sys/inotify.h>

DESCRIPTION

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:

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.)

NOTES

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).

WARNINGS

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.

SEE ALSO

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