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:
-
o
-
inotify_init(3C) creates an inotify instance, returning a file descriptor associated with the in-kernel event queue.
-
o
-
inotify_init1(3C) also creates an inotify instance, but allows for a flags argument that controls some attributes of the returned file descriptor.
-
o
-
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.
-
o
-
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.)
Events
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):
IN_DONT_FOLLOW
Don't follow the specified pathname if it is a symbolic link.
IN_EXCL_UNLINK
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.)
IN_MASK_ADD
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.)
IN_ONESHOT
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).
IN_ONLYDIR
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):
IN_IGNORED
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).
IN_ISDIR
The entity inducing the event is a directory.
IN_Q_OVERFLOW
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.)
IN_UNMOUNT
The filesystem containing the watched entity was unmounted.
NOTES
inotify instances can be monitored via
poll(2),
port_get(3C),
epoll(5), 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.