F_NOTIFY(2const)

🌸 F_NOTIFY(2const) — file & directory change notification 🌸

okay bestie, gather round, because this one is a const page for the fcntl(2) operation F_NOTIFY, and it's giving "your filesystem is gossiping about you and I'm the group chat" energy. it lives in section 2const of the Linux manual, and it's part of the Standard C library (libc, -lc), so you're covered.

---

✨ SYNOPSIS ✨

#define _GNU_SOURCE
#include <fcntl.h>

int fcntl(int fd, F_NOTIFY, int arg);

like yes, it's just fcntl() with a special command, but the vibe is so much more 💅

---

💖 DESCRIPTION 💖

so here's the tea: F_NOTIFY gives you notifications whenever the directory that fd points at gets changed — or whenever any of the files inside it get changed. so basically you get to be nosy about a whole directory and it's completely legal, love that for you 🫶

the events you want to be notified about go in arg, and arg is a bit mask you build by ORing together zero or more of these bits:

• DN_ACCESS — a file got accessed, i.e. read. think read(2), pread(2), readv(2), and similar. someone peeked 👀
• DN_MODIFY — a file got modified. that's write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar. glow-up gone different, honestly.
• DN_CREATE — a file got created. covers open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), and rename(2) into this directory. new bestie just dropped 🎀
• DN_DELETE — a file got unlinked. that's unlink(2), rename(2) to another directory, and rmdir(2). rip bozo 😭
• DN_RENAME — a file got renamed within this directory, via rename(2). same girl, new name ✨
• DN_ATTRIB — a file's attributes changed. chown(2), chmod(2), utime(2), utimensat(2), and similar. she's reinventing herself.

heads up bestie: to even get these definitions you have to define the _GNU_SOURCE feature test macro before including any header files. no skipping that step, it's not optional, it's the entry fee 💀

directory notifications are normally "one-shot" — meaning you fire it once and you're done, and the application must reregister to keep receiving further notifications. rude? a little. but alternatively, if you include DN_MULTISHOT in arg, then the notification stays in effect until you explicitly remove it. iconic behaviour honestly 👑

a series of F_NOTIFY requests is cumulative — the events in arg get added to the set you're already monitoring, like stacking bracelets. and to disable notification of all events, you make an F_NOTIFY call with arg set to 0. clean slate, we love a reset 🌈

notifications arrive by delivering a signal. the default signal is SIGIO, but you can change that with the F_SETSIG operation to fcntl(). (note that SIGIO is one of the nonqueuing standard signals — so if you switch to using a real-time signal, that means multiple notifications can actually be queued to the process.) in that latter case, the signal handler receives a siginfo_t structure as its second argument — if the handler was set up using SA_SIGINFO — and the si_fd field of that structure contains the file descriptor which generated the notification. which is super useful when you've set up notification on multiple directories at once, because otherwise you'd have no idea which one was yapping 🦋

especially when you're using DN_MULTISHOT, you really should use a real time signal for notification, so that multiple notifications can be queued. fr fr, don't skip this one.

NOTE: new applications should use the inotify interface (available since Linux 2.6.13), which provides a much superior interface for obtaining notifications of filesystem events. see inotify(7). like, F_NOTIFY is your aunt's facebook, inotify is the group chat. just saying 💜

---

🎀 RETURN VALUE 🎀

Zero. yes, zero. success is just... zero. no confetti, no fanfare, just zero.

on error, -1 is returned, and errno is set to indicate the error. sadness.

---

💀 ERRORS 💀

• see fcntl(2) — it's got the full drama.
• ENOTDIR — fd does not refer to a directory. bestie. that's not a folder. that's not even giving folder. that's giving file 🙈

---

⭐ STANDARDS ⭐

Linux. that's it, that's the standard. homegrown, no cap.

---

🧚 HISTORY 🧚

Linux 2.4. vintage, but make it functional.

---

👑 SEE ALSO 👑

• fcntl(2)

---

okay that's the whole page, and as always: this was brought to you by Linux man-pages 6.20, dated 2025-07-20, with love, glitter, and a concerning amount of fcntl() fangirling. go set up your notifications, bestie, and slay 💅✨🌸