What action does Kqueue dir extended watch?

I'm playing around with rb-kqueue on OS X and I can't work out how to get the extend flag to fire.

From the OpenBSD kqueue man page (which also matches the OS X man page):

NOTE_EXTEND The file referenced by the descriptor was extended

Which is very circular.

NOTE_EXTEND For regular file, the file referenced by the descriptor was extended. For directory, reports that a directory entry was added or removed, as the result of rename operation. The NOTE_EXTEND event is not reported when a name is changed inside the directory.

This is a lot more descriptive, however, I've been running a kqueue on a directory and try as I might I cannot get the extend flag to fire. I've tried mv, rename, xattr (because searching for "extended" brings back lots of results on extended attributes), adding sub dirs and files with mkdir and touch and redirects but nothing results in the extend flag being part of an event, just write and/or link.

Hence I'm confused as to what extend really is. Is it just because I'm running it on OS X?

Solution

I hope to shed some light on this issue.

The flag NOTE_EXTEND corresponds to the action taken on a file. In your case you should trigger the action when a file size has increased.

The reasoning

To quote the original paper - Kquote: A generic and scalable event notification facility:

The fflags field is used to specify which actions on the descriptor the application is interested in on registration, and upon return, which actions have occurred. The possible actions are:

NOTE DELETE

NOTE WRITE

NOTE EXTEND

NOTE ATTRIB

NOTE LINK

NOTE RENAME

These correspond to the actions that the filesystem performs on the file and thus will not be explained here. These notes may be OR-d together in the returned kevent, if multiple actions have occurred. E.g.: a file was written, then renamed. The final general purpose filter is the PROC filter, which detects process changes. For this filter, the ident field is interpreted as a process identifier. This filter can watch for several types of events, and the fflags that control this filter are outlined in Figure 3

The Figure 3 for EVFILT PROC:

Input/Output Flags:

NOTE EXIT Process exited.

NOTE FORK Process called fork()

NOTE EXEC Process executed a new process via execve(2) or similar call.

NOTE TRACK Follow a process across fork() calls. The parent process will return with NOTE TRACK set in the flags field, while the child process will return with NOTE CHILD set in fflags and the parent PID in data.

Output Flags only:

NOTE CHILD This is the child process of a TRACKed process which called fork().

NOTE TRACKERR This flag is returned if the system was unable to attach an event to the child process, usually due to resource limitations.