inotify_add_watch() shall add a watch to, or modify an existing watch on, the watch list of the inotify instance specified by the file descriptor fd, for the file specified by path, to monitor the events specified by the bitmask mask. The caller must have read access to the file.
On success, inotify_add_watch() shall return the unique, non-negative watch descriptor associated with the file path and the inotify instance specified by the file descriptor fd.
If path was already on the watch list, then inotify_add_watch() shall return the existing watch descriptor.
If path was not already on the watch list, then inotify_add_watch() shall allocate a new watch descriptor.
inotify_add_watch() shall not work recursively. Monitoring subdirectories of path shall require adding watches to them.
On failure, inotify_add_watch() shall return -1
errno to an appropriate value.
The caller does not have read access to path.
The file descriptor fd is invalid.
path is outside of the address space accessible by the process.
mask contains no legal events, or fd is not a valid inotify file descriptor.
There is not enough kernel memory available.
The maximum number of watches has been created for this user, or the kernel cannot allocate a resource.
The function read() can be used to determine which inotify events have occurred. A blocking file descriptor will make read() block until at least one event has occurred.
If successful, read() will return at least one
of the following
inotify_event structures in a buffer:
wd is a watch descriptor that
specifies the watch associated with the event.
It is obtained from a previous invocation of
mask is a bit mask describing inotify events.
See the section on masks below.
cookie is an integer associating related inotify events.
The integer value is unique, and currently
only enables the application to associate
IN_MOVE_TO rename events.
len is a count of the bytes in
including null bytes.
This means that the total length of an
path is only returned when an event occurs for a file within
a watched directory. This string is null-terminated, and it may contain
more null bytes so that future reads will be aligned properly on an
In kernels before 2.6.21, read()
returns 0 when the buffer given to it is too small
to return data about the next event. In subsequent kernels, it fails with the
For a given file descriptor, the inotify events are returned in an ordered queue.
Events on a file descriptor will always be returned in the correct order of occurrence.
If two or more inotify events for a given file descriptor have identical values for all
fields, then only one
will be returned to represent all of them.
The number of bytes that can be read from an inotify file descriptor
can be determined by making a
FIONREAD ioctl() call.
The mask argument of
inotify_add_watch() and the
mask field of the
inotify_event structure are bit masks that specify inotify events.
The bits in the list below can be set in the mask argument of
inotify_add_watch() and returned in the
mask field of
File was read.
Bit mask of all events in this list.
File's metadata changed (including timestamps and permissions).
File that was opened for writing was closed.
File that was not opened for writing was closed.
File or directory was created in a watched directory.
File or directory was deleted in a watched directory.
Watched file or directory was deleted.
File was changed.
Watched file or directory was moved
File was moved out of watched directory.
File was moved into watched directory.
File was opened.
All of the events above, except for
cause the name field of the
inotify_event structure to contain
the name of the file or directory being monitored.
The following bit is valid for inotify_add_watch() only.
Monitor path for an event, and then remove it from the watch list.
The following bits are valid for the
inotify_event structure only.
Watch was removed, either explicitly (via inotify_rm_watch()) or implicitly (file deletion or file system unmounting).
Object being watched is a directory.
The event queue overflowed (wd is set to -1).
File system of object being watched was unmounted.