---
name: "inotify_add_watch"
section: "2"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/inotify_add_watch"
---

# inotify\_add\_watch(2)

add a watch to an initialized inotify instance

## NAME

inotify\_add\_watch - add a watch to an initialized inotify instance

## LIBRARY

Standard C library (*libc*, *-lc*)

## SYNOPSIS

```
#include <sys/inotify.h>
```

**int inotify\_add\_watch(int** *fd***, const char \****path***, uint32\_t** *mask***);**

## DESCRIPTION

**inotify\_add\_watch**() adds a new watch, or modifies an existing watch, for the file whose location is specified in *path*; 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 *path* are specified in the *mask* bit-mask argument. See [**inotify**(7)](/inotify/7.md) 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 *path*. 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 is returned.

The watch descriptor is returned by later [**read**(2)](/read/2.md)s from the inotify file descriptor. These reads fetch *inotify\_event* structures (see [**inotify**(7)](/inotify/7.md)) indicating filesystem events; the watch descriptor inside this structure identifies the object for which the event occurred.

## RETURN VALUE

On success, **inotify\_add\_watch**() returns a watch descriptor (a nonnegative integer). On error, -1 is returned and *errno* is set to indicate the error.

## ERRORS

- **EACCES**

  Read access to the given file is not permitted.

- **EBADF**

  The given file descriptor is not valid.

- **EEXIST**

  *mask* contains **IN\_MASK\_CREATE** and *path* refers to a file already being watched by the same *fd*.

- **EFAULT**

  *path* points outside of the process's accessible address space.

- **EINVAL**

  The given event mask contains no valid events; or *mask* contains both **IN\_MASK\_ADD** and **IN\_MASK\_CREATE**; or *fd* is not an inotify file descriptor.

- **ENAMETOOLONG**

  *path* is too long.

- **ENOENT**

  A directory component in *path* does not exist or is a dangling symbolic link.

- **ENOMEM**

  Insufficient kernel memory was available.

- **ENOSPC**

  The user limit on the total number of inotify watches was reached or the kernel failed to allocate a needed resource.

- **ENOTDIR**

  *mask* contains **IN\_ONLYDIR** and *path* is not a directory.

## STANDARDS

Linux.

## HISTORY

Linux 2.6.13.

## EXAMPLES

See [**inotify**(7)](/inotify/7.md).

## SEE ALSO

[**inotify\_init**(2)](/inotify_init/2.md), [**inotify\_rm\_watch**(2)](/inotify_rm_watch/2.md), [**inotify**(7)](/inotify/7.md)