inotify_add_watch -- add a watch to a watch list


#include <sys/inotify.h>

int inotify_add_watch(int fd, const char * path, uint32_t mask);


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.

Return Value

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 and set 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.

Application Usage


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:

struct inotify_event {
    int      wd;
    uint32_t mask;
    uint32_t cookie;
    uint32_t len;
    char     path[];

wd is a watch descriptor that specifies the watch associated with the event. It is obtained from a previous invocation of inotify_add_watch().

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_FROM and IN_MOVE_TO rename events.

len is a count of the bytes in path, including null bytes. This means that the total length of an inotify_event structure is


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 address boundary.

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 error EINVAL.

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


File was read.


Bit mask of all events in this list.


File's metadata changed (including timestamps and permissions).


Same as



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.


Same as



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 IN_DELETE_SELF and IN_MOVE_SELF, 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.


It is possible to monitor file descriptors with the functions epoll(), poll(), and select().

When all of the file descriptors that point to an inotify instance have been closed, the instance and its associated resources and watches are freed by the kernel.

See Also

inotify_init(), inotify_rm_watch()