inotify_add_watch

Name

inotify_add_watch -- add a watch to a watch list

Synopsis

#include <sys/inotify.h>

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

Description

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.

Errors

EACCESS 

The caller does not have read access to path.

EBADF 

The file descriptor fd is invalid.

EFAULT 

path is outside of the address space accessible by the process.

EINVAL 

mask contains no legal events, or fd is not a valid inotify file descriptor.

ENOMEM 

There is not enough kernel memory available.

ENOSPC 

The maximum number of watches has been created for this user, or the kernel cannot allocate a resource.

Application Usage

Reading

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

sizeof(inotify_event)+len
  

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.

Masks

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.

IN_ACCESS 

File was read.

IN_ALL_EVENTS 

Bit mask of all events in this list.

IN_ATTRIB 

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

IN_CLOSE 

Same as

IN_CLOSE_WRITE | IN_CLOSE_NOWRITE
  

IN_CLOSE_WRITE 

File that was opened for writing was closed.

IN_CLOSE_NOWRITE 

File that was not opened for writing was closed.

IN_CREATE 

File or directory was created in a watched directory.

IN_DELETE 

File or directory was deleted in a watched directory.

IN_DELETE_SELF 

Watched file or directory was deleted.

IN_MODIFY 

File was changed.

IN_MOVE 

Same as

IN_MOVED_FROM | IN_MOVED_TO
  

IN_MOVE_SELF 

Watched file or directory was moved

IN_MOVED_FROM 

File was moved out of watched directory.

IN_MOVED_TO 

File was moved into watched directory.

IN_OPEN 

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.

IN_ONESHOT 

Monitor path for an event, and then remove it from the watch list.

The following bits are valid for the inotify_event structure only.

IN_IGNORED 

Watch was removed, either explicitly (via inotify_rm_watch()) or implicitly (file deletion or file system unmounting).

IN_ISDIR 

Object being watched is a directory.

IN_Q_OVERFLOW 

The event queue overflowed (wd is set to -1).

IN_UNMOUNT 

File system of object being watched was unmounted.

Notes

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