1.. SPDX-License-Identifier: GPL-2.0
2
3============================
4Linux Directory Notification
5============================
6
7	   Stephen Rothwell <sfr@canb.auug.org.au>
8
9The intention of directory notification is to allow user applications
10to be notified when a directory, or any of the files in it, are changed.
11The basic mechanism involves the application registering for notification
12on a directory using a fcntl(2) call and the notifications themselves
13being delivered using signals.
14
15The application decides which "events" it wants to be notified about.
16The currently defined events are:
17
18	=========	=====================================================
19	DN_ACCESS	A file in the directory was accessed (read)
20	DN_MODIFY	A file in the directory was modified (write,truncate)
21	DN_CREATE	A file was created in the directory
22	DN_DELETE	A file was unlinked from directory
23	DN_RENAME	A file in the directory was renamed
24	DN_ATTRIB	A file in the directory had its attributes
25			changed (chmod,chown)
26	=========	=====================================================
27
28Usually, the application must reregister after each notification, but
29if DN_MULTISHOT is or'ed with the event mask, then the registration will
30remain until explicitly removed (by registering for no events).
31
32By default, SIGIO will be delivered to the process and no other useful
33information.  However, if the F_SETSIG fcntl(2) call is used to let the
34kernel know which signal to deliver, a siginfo structure will be passed to
35the signal handler and the si_fd member of that structure will contain the
36file descriptor associated with the directory in which the event occurred.
37
38Preferably the application will choose one of the real time signals
39(SIGRTMIN + <n>) so that the notifications may be queued.  This is
40especially important if DN_MULTISHOT is specified.  Note that SIGRTMIN
41is often blocked, so it is better to use (at least) SIGRTMIN + 1.
42
43Implementation expectations (features and bugs :-))
44---------------------------------------------------
45
46The notification should work for any local access to files even if the
47actual file system is on a remote server.  This implies that remote
48access to files served by local user mode servers should be notified.
49Also, remote accesses to files served by a local kernel NFS server should
50be notified.
51
52In order to make the impact on the file system code as small as possible,
53the problem of hard links to files has been ignored.  So if a file (x)
54exists in two directories (a and b) then a change to the file using the
55name "a/x" should be notified to a program expecting notifications on
56directory "a", but will not be notified to one expecting notifications on
57directory "b".
58
59Also, files that are unlinked, will still cause notifications in the
60last directory that they were linked to.
61
62Configuration
63-------------
64
65Dnotify is controlled via the CONFIG_DNOTIFY configuration option.  When
66disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
67
68Example
69-------
70See tools/testing/selftests/filesystems/dnotify_test.c for an example.
71
72NOTE
73----
74Beginning with Linux 2.6.13, dnotify has been replaced by inotify.
75See Documentation/filesystems/inotify.rst for more information on it.
76