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