F_NOTIFY

SYNOPSIS

#define _GNU_SOURCE
#include <fcntl.h>

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

Provide notification when the directory referred to by fd or any of the files that it contains is changed. The events to be notified are specified in arg, which is a bit mask specified by ORing together zero or more of the following bits:

DN_ACCESS: A file was accessed (read(2), pread(2), readv(2), and similar)
DN_MODIFY: A file was modified (write(2), pwrite(2), writev(2), truncate(2), ftruncate(2), and similar).
DN_CREATE: A file was created (open(2), creat(2), mknod(2), mkdir(2), link(2), symlink(2), rename(2) into this directory).
DN_DELETE: A file was unlinked (unlink(2), rename(2) to another directory, rmdir(2)).
DN_RENAME: A file was renamed within this directory (rename(2)).
DN_ATTRIB: The attributes of a file were changed (chown(2), chmod(2), utime(2), utimensat(2), and similar).

(In order to obtain these definitions, the _GNU_SOURCE feature test macro must be defined before including any header files.)

Directory notifications are normally "one-shot", and the application must reregister to receive further notifications. Alternatively, if DN_MULTISHOT is included in arg, then notification will remain in effect until explicitly removed.

A series of F_NOTIFY requests is cumulative, with the events in arg being added to the set already monitored. To disable notification of all events, make an F_NOTIFY call specifying arg as 0.

Notification occurs via delivery of a signal. The default signal is SIGIO, but this can be changed using the F_SETSIG operation to fcntl(). (Note that SIGIO is one of the nonqueuing standard signals; switching to the use of a real-time signal means that multiple notifications can be queued to the process.) In the latter case, the signal handler receives a siginfo_t structure as its second argument (if the handler was established using SA_SIGINFO) and the si_fd field of this structure contains the file descriptor which generated the notification (useful when establishing notification on multiple directories).

Especially when using DN_MULTISHOT, a real time signal should be used for notification, so that multiple notifications can be queued.

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).