LIBINOTIFY(3)

🦋 LIBINOTIFY(3) 🦋

okay bestie, this is the Library Functions Manual page for libinotify, and the vibe is literally “monitor file system events.” no cap. ✨

💖 NAME 💖

libinotify, inotify_init, inotify_init1, inotify_add_watch, inotify_rm_watch, libinotify_set_param, inotify_event, libinotify_direct_readv, libinotify_free_iovec, libinotify_direct_close — monitor file system events 💅

✨ SYNOPSIS ✨

#include <sys/inotify.h>

int
inotify_init();

int
inotify_init1(int flags);

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

int
inotify_rm_watch(int fd, int wd);

int
libinotify_set_param(int fd, int param, intptr_t value);

int
libinotify_direct_readv(int fd, struct iovec **events, int size,
    int no_block);

void
libinotify_free_iovec(struct iovec *events);

int
libinotify_direct_close(int fd);

💅 DESCRIPTION 💅

inotify_init() and inotify_init1() create an inotify instance and return a file descriptor referring to the instance. inotify_init1() is similar to inotify_init() except it takes an additional flags parameter, and the values can be:

• IN_NONBLOCK — Set I_NONBLOCK file status flag on the inotify file descriptor.
• IN_CLOSEXEC — Set FD_CLOEXEC flag on the new file descriptor. See the O_CLOEXEC flag in open(2).
• IN_DIRECT — libinotify-specific flag that enables direct mode (see below).

The function returns the file descriptor to the inotify handle if successful, otherwise it returns -1. Possible errno values are:

• EINVAL — Invalid flag value passed.
• EMFILE — System wide limit of inotify instances reached.
• ENFILE — System limit on total number of fd's reached.
• ENOMEM — Insufficient kernel memory.

inotify_add_watch() adds a new watch to the inotify instance. The list of possible masks is described below. If the watch for the given filename already exists, it gets updated with the new mask value passed. The function returns an integer called a watch descriptor if successful, otherwise -1.

Possible errno values are:

• EACCES — Permission for read access is denied for given file.
• EBADF — Invalid file descriptor.
• EFAULT — Pathname points outside process's allocated address space.
• EINVAL — Invalid event mask passed.
• ENOENT — A component of path that must exist does not exist.
• ENOMEM — Insufficient kernel memory available.
• ENOSPC — User limit on total number of inotify watches has crossed or kernel failed to allocate a needed resource.

inotify_rm_watch() removes watch wd from the instance described by file descriptor fd. The function returns zero on success and -1 on error. Possible errno values are:

• EBADF — Invalid file descriptor fd.
• EINVAL — Invalid watch descriptor wd.

libinotify_set_param() is libinotify-specific. Replacement for the Linux procfs interface. Set an inotify parameter for the instance described by file descriptor fd. An fd value of -1 is used for setting global parameters. Possible param values are:

• IN_SOCKBUFSIZE — Size of communication socket buffer in bytes. Should match read(2) buffer size for libinotify event consumers. Lower values can cause partial event reads. Bigger values are just wasting memory. Default value is arbitrary, has been acquired from the code sample in the Linux inotify(7) man page and seems to be very common among inotify clients. Default value 4096 (exported as IN_DEF_SOCKBUFSIZE).
• IN_MAX_QUEUED_EVENTS — Upper limit on the queue length per inotify handle. Linux's /proc/sys/fs/inotify/max_queued_events counterpart. Default value 16384 (exported as IN_DEF_MAX_QUEUED_EVENTS).
• IN_MAX_USER_INSTANCES — Global upper limit on the number of inotify instances that can be created. Linux's /proc/sys/fs/inotify/max_user_instances counterpart. Default value 2147483646 (exported as IN_DEF_MAX_USER_INSTANCES).

🧚 inotify_event structure 🧚

struct inotify_event {
    int         wd;       /* Watch descriptor */
    uint32_t    mask;     /* Mask of events */
    uint32_t    cookie;   /* Unique integer associating related events */
    uint32_t    len;      /* Size of name field */
    char        name[];   /* Optional null-terminated name */
};

🎀 inotify events — 🎀

These are the masks supported by the libinotify implementation:

• IN_OPEN — File was opened.
• IN_ACCESS — File was accessed (read).
• IN_ATTRIB — Metadata changed.
• IN_CREATE — File/directory was created in watched directory.
• IN_CLOSE_WRITE — File opened for writing was closed.
• IN_CLOSE_NOWRITE — File not opened for writing was closed.
• IN_DELETE — File/directory in watched directory was deleted.
• IN_DELETE_SELF — Watched file/directory was deleted.
• IN_MODIFY — File/Directory was modified.
• IN_MOVE_SELF — Watched file/directory was moved.
• IN_MOVED_FROM — A file in watched directory was moved out.
• IN_MOVED_TO — A file was moved into watched directory.
• IN_ALL_EVENTS — Bit mask of all the above events.
• IN_MOVE — Equal to IN_MOVED_FROM|IN_MOVED_TO.
• IN_CLOSE — Equal to IN_CLOSE_WRITE|IN_CLOSE_NOWRITE.

IN_DELETE_SELF and IN_MOVE_SELF can occur only for a watched file/directory. Other events can be marked for a file/directory in a watched directory. In that case, the name of the file for which the event is generated can be read by the name field in the inotify_event structure.

🫶 extra bits you can set in mask when calling inotify_add_watch() 🫶

• IN_DONT_FOLLOW — Don't dereference the path name if it's a symlink.
• IN_EXCL_UNLINK — Do not generate events for unlinked children. (Currently not supported).
• IN_MASK_ADD — Add event mask for watch for given pathname.
• IN_ONESHOT — Remove watch after retrieving one event.
• IN_ONLYDIR — Only watch the pathname if it is a directory.

🌸 bits that may be set by the mask field returned by read(3) 🌸

• IN_IGNORED — Watch was removed (explicitly, revoked, or unmounted).
• IN_ISDIR — Subject of this event is a directory.
• IN_Q_OVERFLOW — Event queue has overflowed.
• IN_UNMOUNT — File system containing watched file/directory was unmounted.

🌈 DIRECT MODE 🌈

In this mode, the fd handed over to the user isn't a read()able one, but is actually a kqueue fd. This allows reducing some copying overhead at the cost of being incompatible with how the Linux inotify fd works. The mode is activated by passing IN_DIRECT to inotify_init1().

libinotify_direct_readv() is a replacement for the read call in direct mode. Pass it an array of struct iovec* of desired size to fill it with lists of events. Each struct iovec* points to an array of structs terminated with a null iovec (iov_base = NULL). It is the caller responsibility to free these arrays.

libinotify_free_iovec() frees a list of iovec structs returned by the previous call.

libinotify_direct_close() is a replacement for the close call in direct mode.

👀 SEE ALSO 👀

read(3)

📜 HISTORY 📜

inotify first appeared in Linux 2.6.13.

---

okay that's the whole page, bestie 💖 brought to you by Debian, dated July 22, 2024, and officially titled LIBINOTIFY(3). mwah 🎀✨