inotify_add_watch(2)

💖 inotify_add_watch — bestie's guide to the inotify_add_watch(2) system call 💖

okay so picture this: it's a System Calls Manual page, and today's main character is inotify_add_watch. she's the one who actually puts a watch on stuff for you. let's get into it 🎀

---

✨ LIBRARY ✨

standard C library — that's libc, and yeah, you link it with -lc. iconic, as always 💅

---

🌸 SYNOPSIS 🌸

#include <sys/inotify.h>

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

that's it. three little args. so much power 🦋

---

💖 DESCRIPTION 💖

so inotify_add_watch() does one of two things, depending on the vibe:

1. adds a new watch, or
2. modifies an existing watch

…for the file whose location lives in path. and heads up bestie — the caller must have read permission for that file. no read permission, no watch. periodt 🔥

the fd argument is a file descriptor that points at the inotify instance whose watch list you're about to mess with. that's the instance getting modified.

the events you wanna monitor for path? those go in the mask bit-mask argument. for a full rundown of which bits can be set in mask, go peek at inotify(7) — she has the lore 📚

now for the good part ✨ A successful call to inotify_add_watch() returns a unique watch descriptor for this inotify instance — specifically for the filesystem object (the inode) that corresponds to path. here's the tea:

• if that filesystem object wasn't already being watched by this inotify instance, the watch descriptor is newly allocated — fresh out the box 🎁
• if that filesystem object was already being watched (maybe via a different link to the same object, iykyk), then you get the descriptor for the existing watch back. no duplicates, she's efficient 💅

and where does that watch descriptor show up later? it gets returned by later read(2)s from the inotify file descriptor 📖 those reads fetch inotify_event structures (again, see inotify(7) for the details) that indicate filesystem events — and the watch descriptor inside that structure is what tells you which object the event happened for. it's giving detective work 🔍

---

👑 RETURN VALUE 👑

• on success, inotify_add_watch() returns a watch descriptor — a nonnegative integer 🎉
• on error, -1 comes back and errno is set to tell you exactly what went wrong 😭

---

💀 ERRORS 💀

• EACCES — read access to the given file is not permitted. bestie you cannot read it, she said no 🙈
• 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. she's already on the list, girl 💅
• EFAULT — path points outside of the process's accessible address space.
• EINVAL — one of these three situations: 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. pick your poison 🧚
• ENAMETOOLONG — path is too long. she's rambling 😭
• ENOENT — a directory component in path does not exist, or it's 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. you maxed out, no cap 🚫
• ENOTDIR — mask contains IN_ONLYDIR and path is not a directory. read the room 💀

---

🌈 STANDARDS 🌈

Linux. that's the whole standards section. short, sweet, unbothered 💜

---

⭐ HISTORY ⭐

Linux 2.6.13. vintage but thriving, a true original 👑

---

🫶 EXAMPLES 🫶

See inotify(7). she's got the examples, go say hi 🍓

---

🌸 SEE ALSO 🌸

• inotify_init(2)
• inotify_rm_watch(2)
• inotify(7)

---

and that's the whole page, bestie 💖 this was Linux man-pages version 6.20, dated 2026-02-08, and it's officially a wrap on inotify_add_watch(2) 🎀 slay, go watch some files ✨