linux-old/Documentation/dnotify.txt
<<
>>
Prefs
   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.
  36
  37Implementation expectations (features and bugs :-))
  38---------------------------
  39
  40The notification should work for any local access to files even if the
  41actual file system is on a remote server.  This implies that remote
  42access to files served by local user mode servers should be notified.
  43Also, remote accesses to files served by a local kernel NFS server should
  44be notified.
  45
  46In order to make the impact on the file system code as small as possible,
  47the problem of hard links to files has been ignored.  So if a file (x)
  48exists in two directories (a and b) then a change to the file using the
  49name "a/x" should be notified to a program expecting notifications on
  50directory "a", but will not be notified to one expecting notifications on
  51directory "b".
  52
  53Also, files that are unlinked, will still cause notifications in the
  54last directory that they were linked to.
  55
  56Example
  57-------
  58
  59        #define _GNU_SOURCE     /* needed to get the defines */
  60        #include <fcntl.h>      /* in glibc 2.2 this has the needed
  61                                           values defined */
  62        #include <signal.h>
  63        #include <stdio.h>
  64        #include <unistd.h>
  65        
  66        static volatile int event_fd;
  67        
  68        static void handler(int sig, siginfo_t *si, void *data)
  69        {
  70                event_fd = si->si_fd;
  71        }
  72        
  73        int main(void)
  74        {
  75                struct sigaction act;
  76                int fd;
  77                
  78                act.sa_sigaction = handler;
  79                sigemptyset(&act.sa_mask);
  80                act.sa_flags = SA_SIGINFO;
  81                sigaction(SIGRTMIN, &act, NULL);
  82                
  83                fd = open(".", O_RDONLY);
  84                fcntl(fd, F_SETSIG, SIGRTMIN);
  85                fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT);
  86                /* we will now be notified if any of the files
  87                   in "." is modified or new files are created */
  88                while (1) {
  89                        pause();
  90                        printf("Got event on fd=%d\n", event_fd);
  91                }
  92        }
  93
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.