When you rename a file (mv file1 file2), inotify generates two linked events:

The cookie field has the same value in both events. This lets you match the FROM and TO events together to know it was a rename operation, not a delete + create.

Example: You watch /tmp/mydir. Someone deletes /tmp/mydir/notes.txt → you get IN_DELETE (name = “notes.txt”). Someone then deletes /tmp/mydir itself → you get IN_DELETE_SELF (no name field).

When an event occurs for a directory (not a file), the kernel sets the IN_ISDIR bit in the mask field of the returned event. You check it like this:

if (event->mask & IN_CREATE) {
    if (event->mask & IN_ISDIR)
        printf("New subdirectory created: %s\n", event->name);
    else
        printf("New file created: %s\n", event->name);
}

This is important because inotify is not recursive — if a new subdirectory is created and you want to watch it too, you need to call inotify_add_watch() again for that new subdirectory.

Some bits in the mask don’t describe events — they modify how inotify_add_watch() behaves:

A common daemon pattern: reload config when it changes, but only care about IN_CLOSE_WRITE (not every intermediate write).

#include <stdio.h>
#include <stdlib.h>
#include <sys/inotify.h>
#include <unistd.h>

#define BUF_SIZE 4096
#define CONFIG_FILE "/etc/myapp/config.conf"

void reload_config(void) {
    printf("Config changed! Reloading...\n");
    /* Your config reload logic here */
}

int main(void)
{
    int fd, wd;
    char buf[BUF_SIZE];
    ssize_t numRead;
    struct inotify_event *event;
    char *p;

    fd = inotify_init1(IN_CLOEXEC);
    if (fd == -1) { perror("inotify_init1"); exit(EXIT_FAILURE); }

    /*
     * Watch for IN_CLOSE_WRITE: triggered after the editor finishes
     * writing and closes the file. More reliable than IN_MODIFY
     * which fires on every single write() call.
     */
    wd = inotify_add_watch(fd, CONFIG_FILE, IN_CLOSE_WRITE);
    if (wd == -1) { perror("inotify_add_watch"); close(fd); exit(EXIT_FAILURE); }

    printf("Monitoring %s for changes...\n", CONFIG_FILE);

    for (;;) {
        numRead = read(fd, buf, BUF_SIZE);
        if (numRead <= 0) break;

        for (p = buf; p < buf + numRead; ) {
            event = (struct inotify_event *) p;

            if (event->mask & IN_CLOSE_WRITE)
                reload_config();

            p += sizeof(struct inotify_event) + event->len;
        }
    }

    close(fd);
    return 0;
}

Link IN_MOVED_FROM and IN_MOVED_TO events together using the cookie field.

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/inotify.h>
#include <unistd.h>

#define BUF_SIZE 4096

int main(void)
{
    int fd, wd;
    char buf[BUF_SIZE];
    ssize_t numRead;
    struct inotify_event *event;
    char *p;

    /* Store the "from" side of a rename temporarily */
    uint32_t pending_cookie = 0;
    char pending_name[256] = {0};

    fd = inotify_init1(IN_CLOEXEC);
    if (fd == -1) { perror("inotify_init1"); exit(EXIT_FAILURE); }

    /* Watch /tmp/testdir for move events */
    wd = inotify_add_watch(fd, "/tmp/testdir", IN_MOVE);
    if (wd == -1) { perror("inotify_add_watch"); close(fd); exit(EXIT_FAILURE); }

    printf("Watching /tmp/testdir for renames...\n");
    printf("Try: mv /tmp/testdir/foo.txt /tmp/testdir/bar.txt\n\n");

    for (;;) {
        numRead = read(fd, buf, BUF_SIZE);
        if (numRead <= 0) break;

        for (p = buf; p < buf + numRead; ) {
            event = (struct inotify_event *) p;

            if (event->mask & IN_MOVED_FROM) {
                /* Store the old name and its cookie */
                pending_cookie = event->cookie;
                strncpy(pending_name, event->name, sizeof(pending_name) - 1);
            }

            if (event->mask & IN_MOVED_TO) {
                /* Match by cookie — same rename operation */
                if (event->cookie == pending_cookie && pending_cookie != 0) {
                    printf("Renamed: %s  →  %s\n", pending_name, event->name);
                    pending_cookie = 0;
                } else {
                    printf("Moved in from outside: %s\n", event->name);
                }
            }

            p += sizeof(struct inotify_event) + event->len;
        }
    }

    close(fd);
    return 0;
}

Use IN_ONESHOT to wait for exactly one event, then stop watching. Useful in scripts or one-time checks.

#include <stdio.h>
#include <stdlib.h>
#include <sys/inotify.h>
#include <unistd.h>

#define BUF_SIZE 4096

int main(int argc, char *argv[])
{
    int fd, wd;
    char buf[BUF_SIZE];
    ssize_t numRead;
    struct inotify_event *event;

    if (argc < 2) {
        fprintf(stderr, "Usage: %s <file-to-watch>\n", argv[0]);
        exit(EXIT_FAILURE);
    }

    fd = inotify_init1(IN_CLOEXEC);
    if (fd == -1) { perror("inotify_init1"); exit(EXIT_FAILURE); }

    /*
     * IN_ONESHOT: after the first event fires, the watch is
     * automatically removed by the kernel.
     */
    wd = inotify_add_watch(fd, argv[1], IN_MODIFY | IN_ONESHOT);
    if (wd == -1) { perror("inotify_add_watch"); close(fd); exit(EXIT_FAILURE); }

    printf("Waiting for first modification to: %s\n", argv[1]);
    printf("(Will exit immediately after first change)\n");

    /* Block until one event arrives */
    numRead = read(fd, buf, BUF_SIZE);
    if (numRead > 0) {
        event = (struct inotify_event *) buf;
        if (event->mask & IN_MODIFY)
            printf("File was modified! Taking action...\n");
    }

    close(fd);
    return 0;
}

gcc -o oneshot oneshot.c
./oneshot /tmp/myfile.txt &
echo "hello" >> /tmp/myfile.txt
# Output: File was modified! Taking action...