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