annotate Documentation/dnotify.txt @ 0:831230e53067

Import 2.6.18 from kernel.org tarball.
author Ian Campbell <ian.campbell@xensource.com>
date Wed Apr 11 14:15:44 2007 +0100 (2007-04-11)
rev   line source
ian@0 1 Linux Directory Notification
ian@0 2 ============================
ian@0 3
ian@0 4 Stephen Rothwell <sfr@canb.auug.org.au>
ian@0 5
ian@0 6 The intention of directory notification is to allow user applications
ian@0 7 to be notified when a directory, or any of the files in it, are changed.
ian@0 8 The basic mechanism involves the application registering for notification
ian@0 9 on a directory using a fcntl(2) call and the notifications themselves
ian@0 10 being delivered using signals.
ian@0 11
ian@0 12 The application decides which "events" it wants to be notified about.
ian@0 13 The currently defined events are:
ian@0 14
ian@0 15 DN_ACCESS A file in the directory was accessed (read)
ian@0 16 DN_MODIFY A file in the directory was modified (write,truncate)
ian@0 17 DN_CREATE A file was created in the directory
ian@0 18 DN_DELETE A file was unlinked from directory
ian@0 19 DN_RENAME A file in the directory was renamed
ian@0 20 DN_ATTRIB A file in the directory had its attributes
ian@0 21 changed (chmod,chown)
ian@0 22
ian@0 23 Usually, the application must reregister after each notification, but
ian@0 24 if DN_MULTISHOT is or'ed with the event mask, then the registration will
ian@0 25 remain until explicitly removed (by registering for no events).
ian@0 26
ian@0 27 By default, SIGIO will be delivered to the process and no other useful
ian@0 28 information. However, if the F_SETSIG fcntl(2) call is used to let the
ian@0 29 kernel know which signal to deliver, a siginfo structure will be passed to
ian@0 30 the signal handler and the si_fd member of that structure will contain the
ian@0 31 file descriptor associated with the directory in which the event occurred.
ian@0 32
ian@0 33 Preferably the application will choose one of the real time signals
ian@0 34 (SIGRTMIN + <n>) so that the notifications may be queued. This is
ian@0 35 especially important if DN_MULTISHOT is specified. Note that SIGRTMIN
ian@0 36 is often blocked, so it is better to use (at least) SIGRTMIN + 1.
ian@0 37
ian@0 38 Implementation expectations (features and bugs :-))
ian@0 39 ---------------------------
ian@0 40
ian@0 41 The notification should work for any local access to files even if the
ian@0 42 actual file system is on a remote server. This implies that remote
ian@0 43 access to files served by local user mode servers should be notified.
ian@0 44 Also, remote accesses to files served by a local kernel NFS server should
ian@0 45 be notified.
ian@0 46
ian@0 47 In order to make the impact on the file system code as small as possible,
ian@0 48 the problem of hard links to files has been ignored. So if a file (x)
ian@0 49 exists in two directories (a and b) then a change to the file using the
ian@0 50 name "a/x" should be notified to a program expecting notifications on
ian@0 51 directory "a", but will not be notified to one expecting notifications on
ian@0 52 directory "b".
ian@0 53
ian@0 54 Also, files that are unlinked, will still cause notifications in the
ian@0 55 last directory that they were linked to.
ian@0 56
ian@0 57 Configuration
ian@0 58 -------------
ian@0 59
ian@0 60 Dnotify is controlled via the CONFIG_DNOTIFY configuration option. When
ian@0 61 disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
ian@0 62
ian@0 63 Example
ian@0 64 -------
ian@0 65
ian@0 66 #define _GNU_SOURCE /* needed to get the defines */
ian@0 67 #include <fcntl.h> /* in glibc 2.2 this has the needed
ian@0 68 values defined */
ian@0 69 #include <signal.h>
ian@0 70 #include <stdio.h>
ian@0 71 #include <unistd.h>
ian@0 72
ian@0 73 static volatile int event_fd;
ian@0 74
ian@0 75 static void handler(int sig, siginfo_t *si, void *data)
ian@0 76 {
ian@0 77 event_fd = si->si_fd;
ian@0 78 }
ian@0 79
ian@0 80 int main(void)
ian@0 81 {
ian@0 82 struct sigaction act;
ian@0 83 int fd;
ian@0 84
ian@0 85 act.sa_sigaction = handler;
ian@0 86 sigemptyset(&act.sa_mask);
ian@0 87 act.sa_flags = SA_SIGINFO;
ian@0 88 sigaction(SIGRTMIN + 1, &act, NULL);
ian@0 89
ian@0 90 fd = open(".", O_RDONLY);
ian@0 91 fcntl(fd, F_SETSIG, SIGRTMIN + 1);
ian@0 93 /* we will now be notified if any of the files
ian@0 94 in "." is modified or new files are created */
ian@0 95 while (1) {
ian@0 96 pause();
ian@0 97 printf("Got event on fd=%d\n", event_fd);
ian@0 98 }
ian@0 99 }