inotify_add

Linux Standard Base Core Specification 4.0
<<< Previous		Next >>>

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.

<<< Previous	Home	Next >>>
initstate_r	Up	inotify_init

inotify_add_watch

Name

Synopsis