inotify_add_watch - add a watch to an initialized inotify instance
int inotify_add_watch(int fd, const char
*pathname, uint32_t mask);
() adds a new watch, or modifies an existing watch, for
the file whose location is specified in pathname
; the caller must have
read permission for this file. The fd
argument is a file descriptor
referring to the inotify instance whose watch list is to be modified. The
events to be monitored for pathname
are specified in the mask
bit-mask argument. See inotify(7)
for a description of the bits that
can be set in mask
A successful call to inotify_add_watch
() returns a unique watch
descriptor for this inotify instance, for the filesystem object (inode) that
corresponds to pathname
. If the filesystem object was not previously
being watched by this inotify instance, then the watch descriptor is newly
allocated. If the filesystem object was already being watched (perhaps via a
different link to the same object), then the descriptor for the existing watch
The watch descriptor is returned by later read(2)
s from the inotify file
descriptor. These reads fetch inotify_event
) indicating filesystem events; the watch descriptor inside
this structure identifies the object for which the event occurred.
On success, inotify_add_watch
() returns a nonnegative watch descriptor.
On error, -1 is returned and errno
is set appropriately.
- Read access to the given file is not permitted.
- The given file descriptor is not valid.
- pathname points outside of the process's accessible
- The given event mask contains no valid events; or fd
is not an inotify file descriptor.
- pathname is too long.
- A directory component in pathname does not exist or
is a dangling symbolic link.
- Insufficient kernel memory was available.
- The user limit on the total number of inotify watches was
reached or the kernel failed to allocate a needed resource.
Inotify was merged into the 2.6.13 Linux kernel.
This system call is Linux-specific.
This page is part of release 4.13 of the Linux man-pages
description of the project, information about reporting bugs, and the latest
version of this page, can be found at