A Linux rename() observed through inotify can produce two records carrying the same nonzero cookie: IN_MOVED_FROM for the old directory entry and IN_MOVED_TO for the new one. The cookie correlates those records, but it does not turn them into one atomic queue item.

That boundary matters for software maintaining a pathname index, synchronizing directory state, or converting filesystem notifications into higher-level change records. A rename is one filesystem operation while its inotify representation can be a pair whose delivery has weaker grouping properties.

Each struct inotify_event contains a cookie field. Linux currently uses a nonzero cookie to connect rename-related IN_MOVED_FROM and IN_MOVED_TO events; other event types use zero.

struct inotify_event {
    int      wd;
    uint32_t mask;
    uint32_t cookie;
    uint32_t len;
    char     name[];
};

For a move between two watched directories, the source-side event names the old entry and the destination-side event names the new entry. Matching cookies let user space associate the two observations.

The watch descriptor and name still describe each side independently. The cookie does not contain a pathname, inode number, generation counter, or durable transaction identifier. Its useful scope is correlation among the rename events delivered by that inotify instance.

Matching events need not be adjacent

The inotify event stream is ordered, but a matching IN_MOVED_FROM and IN_MOVED_TO pair is not guaranteed to occupy consecutive positions. Activity from other processes can place unrelated records between them.

The pair is also not inserted into the queue as an indivisible unit. User space can observe a point at which the source event is available while its matching destination event has not yet appeared.

A consumer that treats the next record after IN_MOVED_FROM as its required partner therefore encodes a stronger condition than the interface provides. Cookie-based matching needs state that can tolerate intervening records.

IN_MOVED_FROM  cookie=41  name=old.db
IN_CREATE      cookie=0   name=marker
IN_MOVED_TO    cookie=41  name=new.db

The middle record does not break the rename relationship. Adjacency is not part of that relationship.

Watch boundaries can leave one side absent

Pairing is further constrained by the monitored namespace. If a file moves out of a watched directory into a directory that is not watched by the same inotify instance, the source can produce IN_MOVED_FROM without a corresponding visible IN_MOVED_TO.

The reverse shape can occur for an object arriving from outside the watched set: the destination is visible while the source is not.

This makes an unmatched move record ambiguous at the instant it is read. It may represent a move crossing the monitored boundary, or its partner may simply not have arrived yet. Waiting for a partner is consequently a policy decision in user space, not a completion guarantee supplied by the cookie.

Queue overflow invalidates event-derived state

An inotify instance has a finite event queue. If it overflows, Linux reports IN_Q_OVERFLOW and events have been lost. At that point, a pathname cache derived only from prior notifications can no longer assume that it represents every filesystem transition.

Rename pairing cannot repair missing history. A pending cookie might have lost its partner, and unrelated create, delete, or attribute events may also be absent.

Systems that require a coherent mirror commonly need a recovery path that rebuilds affected state from the filesystem after overflow. The notification stream is then an incremental signal source between reconciliations rather than an authoritative journal.

Event coalescing also limits counting semantics

Linux may coalesce successive unread inotify events when their watch descriptor, mask, cookie, and name are identical. This reduces queue pressure, but it also means the stream is not a reliable operation counter.

That property is separate from rename pairing, yet it reinforces the same architectural boundary: inotify reports filesystem activity for reactive state maintenance; it does not expose a lossless transactional log.

For rename handling, the cookie provides a precise relation when both move records are present. Correct state machines still need to account for delayed partners, monitored-set boundaries, queue overflow, and reconciliation with current filesystem state.

Software Engineering Linux Filesystems Event Loops