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