Contents of /alx-src/tags/kernel26-2.6.12-alx-r9/Documentation/dnotify.txt
Parent Directory | Revision Log
Revision 630 -
(show annotations)
(download)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 3572 byte(s)
Wed Mar 4 11:03:09 2009 UTC (15 years, 6 months ago) by niro
File MIME type: text/plain
File size: 3572 byte(s)
Tag kernel26-2.6.12-alx-r9
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 | ------- |
65 | |
66 | #define _GNU_SOURCE /* needed to get the defines */ |
67 | #include <fcntl.h> /* in glibc 2.2 this has the needed |
68 | values defined */ |
69 | #include <signal.h> |
70 | #include <stdio.h> |
71 | #include <unistd.h> |
72 | |
73 | static volatile int event_fd; |
74 | |
75 | static void handler(int sig, siginfo_t *si, void *data) |
76 | { |
77 | event_fd = si->si_fd; |
78 | } |
79 | |
80 | int main(void) |
81 | { |
82 | struct sigaction act; |
83 | int fd; |
84 | |
85 | act.sa_sigaction = handler; |
86 | sigemptyset(&act.sa_mask); |
87 | act.sa_flags = SA_SIGINFO; |
88 | sigaction(SIGRTMIN + 1, &act, NULL); |
89 | |
90 | fd = open(".", O_RDONLY); |
91 | fcntl(fd, F_SETSIG, SIGRTMIN + 1); |
92 | fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT); |
93 | /* we will now be notified if any of the files |
94 | in "." is modified or new files are created */ |
95 | while (1) { |
96 | pause(); |
97 | printf("Got event on fd=%d\n", event_fd); |
98 | } |
99 | } |