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