1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
|
.\" 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 (unreleased)"
.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)
|
