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