.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH F_NOTIFY 2const 2025-07-20 "Linux man-pages 6.15"
.SH NAME
F_NOTIFY
\-
file and directory change notification
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #define _GNU_SOURCE
.B #include <fcntl.h>
.P
.BI "int fcntl(int " fd ", F_NOTIFY, int " arg );
.fi
.SH DESCRIPTION
Provide notification when the directory referred to by
.I fd
or any of the files that it contains is changed.
The events to be notified are specified in
.IR arg ,
which is a bit mask specified by ORing together zero or more of
the following bits:
.TP
.B DN_ACCESS
A file was accessed
.RB ( read (2),
.BR pread (2),
.BR readv (2),
and similar)
.TP
.B DN_MODIFY
A file was modified
.RB ( write (2),
.BR pwrite (2),
.BR writev (2),
.BR truncate (2),
.BR ftruncate (2),
and similar).
.TP
.B DN_CREATE
A file was created
.RB ( open (2),
.BR creat (2),
.BR mknod (2),
.BR mkdir (2),
.BR link (2),
.BR symlink (2),
.BR rename (2)
into this directory).
.TP
.B DN_DELETE
A file was unlinked
.RB ( unlink (2),
.BR rename (2)
to another directory,
.BR rmdir (2)).
.TP
.B DN_RENAME
A file was renamed within this directory
.RB ( rename (2)).
.TP
.B DN_ATTRIB
The attributes of a file were changed
.RB ( chown (2),
.BR chmod (2),
.BR utime (2),
.BR utimensat (2),
and similar).
.P
(In order to obtain these definitions, the
.B _GNU_SOURCE
feature test macro must be defined before including
.I any
header files.)
.P
Directory notifications are normally "one-shot", and the application
must reregister to receive further notifications.
Alternatively, if
.B DN_MULTISHOT
is included in
.IR arg ,
then notification will remain in effect until explicitly removed.
.P
.\" The following does seem a poor API-design choice...
A series of
.B F_NOTIFY
requests is cumulative, with the events in
.I arg
being added to the set already monitored.
To disable notification of all events, make an
.B F_NOTIFY
call specifying
.I arg
as 0.
.P
Notification occurs via delivery of a signal.
The default signal is
.BR SIGIO ,
but this can be changed using the
.B F_SETSIG
operation to
.BR fcntl ().
(Note that
.B 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
.I siginfo_t
structure as its second argument (if the handler was
established using
.BR SA_SIGINFO )
and the
.I si_fd
field of this structure contains the file descriptor which
generated the notification (useful when establishing notification
on multiple directories).
.P
Especially when using
.BR DN_MULTISHOT ,
a real time signal should be used for notification,
so that multiple notifications can be queued.
.P
.B NOTE:
New applications should use the
.I inotify
interface (available since Linux 2.6.13),
which provides a much superior interface for obtaining notifications of
filesystem events.
See
.BR inotify (7).
.SH RETURN VALUE
Zero.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
See
.BR fcntl (2).
.TP
.B ENOTDIR
.I fd
does not refer to a directory.
.SH STANDARDS
Linux.
.SH HISTORY
Linux 2.4.
.SH SEE ALSO
.BR fcntl (2)