Debian Codegraph @

upstream/debian-unstable/man2/F_NOTIFY.2const

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH F_NOTIFY 2const 2025-07-20 "Linux man-pages 6.18"
6 .SH NAME
7 F_NOTIFY
8 \-
9 file and directory change notification
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #define _GNU_SOURCE
16 .B #include <fcntl.h>
17 .P
18 .BI "int fcntl(int " fd ", F_NOTIFY, int " arg );
19 .fi
20 .SH DESCRIPTION
21 Provide notification when the directory referred to by
22 .I fd
23 or any of the files that it contains is changed.
24 The events to be notified are specified in
25 .IR arg ,
26 which is a bit mask specified by ORing together zero or more of
27 the following bits:
28 .TP
29 .B DN_ACCESS
30 A file was accessed
31 .RB ( read (2),
32 .BR pread (2),
33 .BR readv (2),
34 and similar)
35 .TP
36 .B DN_MODIFY
37 A file was modified
38 .RB ( write (2),
39 .BR pwrite (2),
40 .BR writev (2),
41 .BR truncate (2),
42 .BR ftruncate (2),
43 and similar).
44 .TP
45 .B DN_CREATE
46 A file was created
47 .RB ( open (2),
48 .BR creat (2),
49 .BR mknod (2),
50 .BR mkdir (2),
51 .BR link (2),
52 .BR symlink (2),
53 .BR rename (2)
54 into this directory).
55 .TP
56 .B DN_DELETE
57 A file was unlinked
58 .RB ( unlink (2),
59 .BR rename (2)
60 to another directory,
61 .BR rmdir (2)).
62 .TP
63 .B DN_RENAME
64 A file was renamed within this directory
65 .RB ( rename (2)).
66 .TP
67 .B DN_ATTRIB
68 The attributes of a file were changed
69 .RB ( chown (2),
70 .BR chmod (2),
71 .BR utime (2),
72 .BR utimensat (2),
73 and similar).
74 .P
75 (In order to obtain these definitions, the
76 .B _GNU_SOURCE
77 feature test macro must be defined before including
78 .I any
79 header files.)
80 .P
81 Directory notifications are normally "one-shot", and the application
82 must reregister to receive further notifications.
83 Alternatively, if
84 .B DN_MULTISHOT
85 is included in
86 .IR arg ,
87 then notification will remain in effect until explicitly removed.
88 .P
89 .\" The following does seem a poor API-design choice...
90 A series of
91 .B F_NOTIFY
92 requests is cumulative, with the events in
93 .I arg
94 being added to the set already monitored.
95 To disable notification of all events, make an
96 .B F_NOTIFY
97 call specifying
98 .I arg
99 as 0.
100 .P
101 Notification occurs via delivery of a signal.
102 The default signal is
103 .BR SIGIO ,
104 but this can be changed using the
105 .B F_SETSIG
106 operation to
107 .BR fcntl ().
108 (Note that
109 .B SIGIO
110 is one of the nonqueuing standard signals;
111 switching to the use of a real-time signal means that
112 multiple notifications can be queued to the process.)
113 In the latter case, the signal handler receives a
114 .I siginfo_t
115 structure as its second argument (if the handler was
116 established using
117 .BR SA_SIGINFO )
118 and the
119 .I si_fd
120 field of this structure contains the file descriptor which
121 generated the notification (useful when establishing notification
122 on multiple directories).
123 .P
124 Especially when using
125 .BR DN_MULTISHOT ,
126 a real time signal should be used for notification,
127 so that multiple notifications can be queued.
128 .P
129 .B NOTE:
130 New applications should use the
131 .I inotify
132 interface (available since Linux 2.6.13),
133 which provides a much superior interface for obtaining notifications of
134 filesystem events.
135 See
136 .BR inotify (7).
137 .SH RETURN VALUE
138 Zero.
139 .P
140 On error, \-1 is returned, and
141 .I errno
142 is set to indicate the error.
143 .SH ERRORS
144 See
145 .BR fcntl (2).
146 .TP
147 .B ENOTDIR
148 .I fd
149 does not refer to a directory.
150 .SH STANDARDS
151 Linux.
152 .SH HISTORY
153 Linux 2.4.
154 .SH SEE ALSO
155 .BR fcntl (2)