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