]>
Commit | Line | Data |
---|---|---|
b31763cf MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ============================ | |
4 | Linux Directory Notification | |
5 | ============================ | |
1da177e4 LT |
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 | ||
b31763cf | 18 | ========= ===================================================== |
1da177e4 LT |
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) | |
b31763cf | 26 | ========= ===================================================== |
1da177e4 LT |
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 :-)) | |
b31763cf | 44 | --------------------------------------------------- |
1da177e4 LT |
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 | ------- | |
718d50ec | 70 | See tools/testing/selftests/filesystems/dnotify_test.c for an example. |
1da177e4 | 71 | |
1e0051ae RD |
72 | NOTE |
73 | ---- | |
74 | Beginning with Linux 2.6.13, dnotify has been replaced by inotify. | |
0c1bc6b8 | 75 | See Documentation/filesystems/inotify.rst for more information on it. |