INOTIFY(7) Linux Programmer's Manual INOTIFY(7)
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
directories. 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: inotify_init(2) (or inotify_init1(2)), inotify_add_watch(2), inotify_rm_watch(2),
read(2), and close(2).
inotify_init(2) creates an inotify instance and returns a file descriptor referring to the inotify instance. The more recent ino-
tify_init1(2) is like inotify_init(2), but provides some extra functionality.
inotify_add_watch(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.
inotify_add_watch(2) either creates a new watch item, or modifies an existing watch. Each watch has a unique "watch descriptor", an inte-
ger returned by inotify_add_watch(2) when the watch is created.
inotify_rm_watch(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 inotify_event {
int wd; /* Watch descriptor */
uint32_t mask; /* Mask of events */
uint32_t cookie; /* Unique cookie associating related
events (for rename(2)) */
uint32_t 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 ino-
tify_add_watch(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
IN_MOVED_FROM and IN_MOVED_TO events to be connected by the application. 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 ('