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)