NAME¶

F_NOTIFY - file and directory change notification

LIBRARY¶

Standard C library (libc, -lc)

SYNOPSIS¶

#define _GNU_SOURCE
#include <fcntl.h>

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

DESCRIPTION¶

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

RETURN VALUE¶

Zero.

On error, -1 is returned, and errno is set to indicate the error.

ERRORS¶

See fcntl(2).

ENOTDIR

fd does not refer to a directory.

STANDARDS¶

Linux.

HISTORY¶

Linux 2.4.

SEE ALSO¶

fcntl(2)