ia64/linux-2.6.18-xen.hg

diff 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)
parents
children
line diff
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/Documentation/dnotify.txt	Wed Apr 11 14:15:44 2007 +0100
     1.3 @@ -0,0 +1,99 @@
     1.4 +		Linux Directory Notification
     1.5 +		============================
     1.6 +
     1.7 +	   Stephen Rothwell <sfr@canb.auug.org.au>
     1.8 +
     1.9 +The intention of directory notification is to allow user applications
    1.10 +to be notified when a directory, or any of the files in it, are changed.
    1.11 +The basic mechanism involves the application registering for notification
    1.12 +on a directory using a fcntl(2) call and the notifications themselves
    1.13 +being delivered using signals.
    1.14 +
    1.15 +The application decides which "events" it wants to be notified about.
    1.16 +The currently defined events are:
    1.17 +
    1.18 +	DN_ACCESS	A file in the directory was accessed (read)
    1.19 +	DN_MODIFY	A file in the directory was modified (write,truncate)
    1.20 +	DN_CREATE	A file was created in the directory
    1.21 +	DN_DELETE	A file was unlinked from directory
    1.22 +	DN_RENAME	A file in the directory was renamed
    1.23 +	DN_ATTRIB	A file in the directory had its attributes
    1.24 +			changed (chmod,chown)
    1.25 +
    1.26 +Usually, the application must reregister after each notification, but
    1.27 +if DN_MULTISHOT is or'ed with the event mask, then the registration will
    1.28 +remain until explicitly removed (by registering for no events).
    1.29 +
    1.30 +By default, SIGIO will be delivered to the process and no other useful
    1.31 +information.  However, if the F_SETSIG fcntl(2) call is used to let the
    1.32 +kernel know which signal to deliver, a siginfo structure will be passed to
    1.33 +the signal handler and the si_fd member of that structure will contain the
    1.34 +file descriptor associated with the directory in which the event occurred.
    1.35 +
    1.36 +Preferably the application will choose one of the real time signals
    1.37 +(SIGRTMIN + <n>) so that the notifications may be queued.  This is
    1.38 +especially important if DN_MULTISHOT is specified.  Note that SIGRTMIN
    1.39 +is often blocked, so it is better to use (at least) SIGRTMIN + 1.
    1.40 +
    1.41 +Implementation expectations (features and bugs :-))
    1.42 +---------------------------
    1.43 +
    1.44 +The notification should work for any local access to files even if the
    1.45 +actual file system is on a remote server.  This implies that remote
    1.46 +access to files served by local user mode servers should be notified.
    1.47 +Also, remote accesses to files served by a local kernel NFS server should
    1.48 +be notified.
    1.49 +
    1.50 +In order to make the impact on the file system code as small as possible,
    1.51 +the problem of hard links to files has been ignored.  So if a file (x)
    1.52 +exists in two directories (a and b) then a change to the file using the
    1.53 +name "a/x" should be notified to a program expecting notifications on
    1.54 +directory "a", but will not be notified to one expecting notifications on
    1.55 +directory "b".
    1.56 +
    1.57 +Also, files that are unlinked, will still cause notifications in the
    1.58 +last directory that they were linked to.
    1.59 +
    1.60 +Configuration
    1.61 +-------------
    1.62 +
    1.63 +Dnotify is controlled via the CONFIG_DNOTIFY configuration option.  When
    1.64 +disabled, fcntl(fd, F_NOTIFY, ...) will return -EINVAL.
    1.65 +
    1.66 +Example
    1.67 +-------
    1.68 +
    1.69 +	#define _GNU_SOURCE	/* needed to get the defines */
    1.70 +	#include <fcntl.h>	/* in glibc 2.2 this has the needed
    1.71 +					   values defined */
    1.72 +	#include <signal.h>
    1.73 +	#include <stdio.h>
    1.74 +	#include <unistd.h>
    1.75 +	
    1.76 +	static volatile int event_fd;
    1.77 +	
    1.78 +	static void handler(int sig, siginfo_t *si, void *data)
    1.79 +	{
    1.80 +		event_fd = si->si_fd;
    1.81 +	}
    1.82 +	
    1.83 +	int main(void)
    1.84 +	{
    1.85 +		struct sigaction act;
    1.86 +		int fd;
    1.87 +		
    1.88 +		act.sa_sigaction = handler;
    1.89 +		sigemptyset(&act.sa_mask);
    1.90 +		act.sa_flags = SA_SIGINFO;
    1.91 +		sigaction(SIGRTMIN + 1, &act, NULL);
    1.92 +		
    1.93 +		fd = open(".", O_RDONLY);
    1.94 +		fcntl(fd, F_SETSIG, SIGRTMIN + 1);
    1.95 +		fcntl(fd, F_NOTIFY, DN_MODIFY|DN_CREATE|DN_MULTISHOT);
    1.96 +		/* we will now be notified if any of the files
    1.97 +		   in "." is modified or new files are created */
    1.98 +		while (1) {
    1.99 +			pause();
   1.100 +			printf("Got event on fd=%d\n", event_fd);
   1.101 +		}
   1.102 +	}