aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/filesystems
diff options
context:
space:
mode:
authorRobert Love <rml@novell.com>2005-07-15 06:56:33 -0400
committerLinus Torvalds <torvalds@g5.osdl.org>2005-07-15 12:54:51 -0400
commit6f97933d0fd13920d7d53b6e0107bb674b3a1f0b (patch)
treef6e5a75915e10747b8e472b9452db5a767c3340a /Documentation/filesystems
parent35e422c967d3208f188e3096c9f603ac7333fb1b (diff)
[PATCH] inotify: documentation update
Clean up and expand some of the inotify documentation. Signed-off-by: Robert Love <rml@novell.com> Signed-off-by: Andrew Morton <akpm@osdl.org> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
Diffstat (limited to 'Documentation/filesystems')
-rw-r--r--Documentation/filesystems/inotify.txt77
1 files changed, 45 insertions, 32 deletions
diff --git a/Documentation/filesystems/inotify.txt b/Documentation/filesystems/inotify.txt
index 2c716041f578..6d501903f68e 100644
--- a/Documentation/filesystems/inotify.txt
+++ b/Documentation/filesystems/inotify.txt
@@ -1,18 +1,22 @@
1 inotify 1 inotify
2 a powerful yet simple file change notification system 2 a powerful yet simple file change notification system
3 3
4 4
5 5
6Document started 15 Mar 2005 by Robert Love <rml@novell.com> 6Document started 15 Mar 2005 by Robert Love <rml@novell.com>
7 7
8
8(i) User Interface 9(i) User Interface
9 10
10Inotify is controlled by a set of three sys calls 11Inotify is controlled by a set of three system calls and normal file I/O on a
12returned file descriptor.
11 13
12First step in using inotify is to initialise an inotify instance 14First step in using inotify is to initialise an inotify instance:
13 15
14 int fd = inotify_init (); 16 int fd = inotify_init ();
15 17
18Each instance is associated with a unique, ordered queue.
19
16Change events are managed by "watches". A watch is an (object,mask) pair where 20Change events are managed by "watches". A watch is an (object,mask) pair where
17the object is a file or directory and the mask is a bit mask of one or more 21the object is a file or directory and the mask is a bit mask of one or more
18inotify events that the application wishes to receive. See <linux/inotify.h> 22inotify events that the application wishes to receive. See <linux/inotify.h>
@@ -22,43 +26,52 @@ Watches are added via a path to the file.
22 26
23Watches on a directory will return events on any files inside of the directory. 27Watches on a directory will return events on any files inside of the directory.
24 28
25Adding a watch is simple, 29Adding a watch is simple:
26 30
27 int wd = inotify_add_watch (fd, path, mask); 31 int wd = inotify_add_watch (fd, path, mask);
28 32
29You can add a large number of files via something like 33Where "fd" is the return value from inotify_init(), path is the path to the
30 34object to watch, and mask is the watch mask (see <linux/inotify.h>).
31 for each file to watch {
32 int wd = inotify_add_watch (fd, file, mask);
33 }
34 35
35You can update an existing watch in the same manner, by passing in a new mask. 36You can update an existing watch in the same manner, by passing in a new mask.
36 37
37An existing watch is removed via the INOTIFY_IGNORE ioctl, for example 38An existing watch is removed via
38 39
39 inotify_rm_watch (fd, wd); 40 int ret = inotify_rm_watch (fd, wd);
40 41
41Events are provided in the form of an inotify_event structure that is read(2) 42Events are provided in the form of an inotify_event structure that is read(2)
42from a inotify instance fd. The filename is of dynamic length and follows the 43from a given inotify instance. The filename is of dynamic length and follows
43struct. It is of size len. The filename is padded with null bytes to ensure 44the struct. It is of size len. The filename is padded with null bytes to
44proper alignment. This padding is reflected in len. 45ensure proper alignment. This padding is reflected in len.
45 46
46You can slurp multiple events by passing a large buffer, for example 47You can slurp multiple events by passing a large buffer, for example
47 48
48 size_t len = read (fd, buf, BUF_LEN); 49 size_t len = read (fd, buf, BUF_LEN);
49 50
50Will return as many events as are available and fit in BUF_LEN. 51Where "buf" is a pointer to an array of "inotify_event" structures at least
52BUF_LEN bytes in size. The above example will return as many events as are
53available and fit in BUF_LEN.
51 54
52each inotify instance fd is also select()- and poll()-able. 55Each inotify instance fd is also select()- and poll()-able.
53 56
54You can find the size of the current event queue via the FIONREAD ioctl. 57You can find the size of the current event queue via the standard FIONREAD
58ioctl on the fd returned by inotify_init().
55 59
56All watches are destroyed and cleaned up on close. 60All watches are destroyed and cleaned up on close.
57 61
58 62
59(ii) Internal Kernel Implementation 63(ii)
64
65Prototypes:
66
67 int inotify_init (void);
68 int inotify_add_watch (int fd, const char *path, __u32 mask);
69 int inotify_rm_watch (int fd, __u32 mask);
70
60 71
61Each open inotify instance is associated with an inotify_device structure. 72(iii) Internal Kernel Implementation
73
74Each inotify instance is associated with an inotify_device structure.
62 75
63Each watch is associated with an inotify_watch structure. Watches are chained 76Each watch is associated with an inotify_watch structure. Watches are chained
64off of each associated device and each associated inode. 77off of each associated device and each associated inode.
@@ -66,7 +79,7 @@ off of each associated device and each associated inode.
66See fs/inotify.c for the locking and lifetime rules. 79See fs/inotify.c for the locking and lifetime rules.
67 80
68 81
69(iii) Rationale 82(iv) Rationale
70 83
71Q: What is the design decision behind not tying the watch to the open fd of 84Q: What is the design decision behind not tying the watch to the open fd of
72 the watched object? 85 the watched object?
@@ -75,9 +88,9 @@ A: Watches are associated with an open inotify device, not an open file.
75 This solves the primary problem with dnotify: keeping the file open pins 88 This solves the primary problem with dnotify: keeping the file open pins
76 the file and thus, worse, pins the mount. Dnotify is therefore infeasible 89 the file and thus, worse, pins the mount. Dnotify is therefore infeasible
77 for use on a desktop system with removable media as the media cannot be 90 for use on a desktop system with removable media as the media cannot be
78 unmounted. 91 unmounted. Watching a file should not require that it be open.
79 92
80Q: What is the design decision behind using an-fd-per-device as opposed to 93Q: What is the design decision behind using an-fd-per-instance as opposed to
81 an fd-per-watch? 94 an fd-per-watch?
82 95
83A: An fd-per-watch quickly consumes more file descriptors than are allowed, 96A: An fd-per-watch quickly consumes more file descriptors than are allowed,
@@ -86,8 +99,8 @@ A: An fd-per-watch quickly consumes more file descriptors than are allowed,
86 can use epoll, but requiring both is a silly and extraneous requirement. 99 can use epoll, but requiring both is a silly and extraneous requirement.
87 A watch consumes less memory than an open file, separating the number 100 A watch consumes less memory than an open file, separating the number
88 spaces is thus sensible. The current design is what user-space developers 101 spaces is thus sensible. The current design is what user-space developers
89 want: Users initialize inotify, once, and add n watches, requiring but one fd 102 want: Users initialize inotify, once, and add n watches, requiring but one
90 and no twiddling with fd limits. Initializing an inotify instance two 103 fd and no twiddling with fd limits. Initializing an inotify instance two
91 thousand times is silly. If we can implement user-space's preferences 104 thousand times is silly. If we can implement user-space's preferences
92 cleanly--and we can, the idr layer makes stuff like this trivial--then we 105 cleanly--and we can, the idr layer makes stuff like this trivial--then we
93 should. 106 should.
@@ -111,9 +124,6 @@ A: An fd-per-watch quickly consumes more file descriptors than are allowed,
111 example, love it. Trust me, I asked. It is not a surprise: Who'd want 124 example, love it. Trust me, I asked. It is not a surprise: Who'd want
112 to manage and block on 1000 fd's via select? 125 to manage and block on 1000 fd's via select?
113 126
114 - You'd have to manage the fd's, as an example: Call close() when you
115 received a delete event.
116
117 - No way to get out of band data. 127 - No way to get out of band data.
118 128
119 - 1024 is still too low. ;-) 129 - 1024 is still too low. ;-)
@@ -122,6 +132,11 @@ A: An fd-per-watch quickly consumes more file descriptors than are allowed,
122 scales to 1000s of directories, juggling 1000s of fd's just does not seem 132 scales to 1000s of directories, juggling 1000s of fd's just does not seem
123 the right interface. It is too heavy. 133 the right interface. It is too heavy.
124 134
135 Additionally, it _is_ possible to more than one instance and
136 juggle more than one queue and thus more than one associated fd. There
137 need not be a one-fd-per-process mapping; it is one-fd-per-queue and a
138 process can easily want more than one queue.
139
125Q: Why the system call approach? 140Q: Why the system call approach?
126 141
127A: The poor user-space interface is the second biggest problem with dnotify. 142A: The poor user-space interface is the second biggest problem with dnotify.
@@ -131,8 +146,6 @@ A: The poor user-space interface is the second biggest problem with dnotify.
131 Obtaining the fd and managing the watches could have been done either via a 146 Obtaining the fd and managing the watches could have been done either via a
132 device file or a family of new system calls. We decided to implement a 147 device file or a family of new system calls. We decided to implement a
133 family of system calls because that is the preffered approach for new kernel 148 family of system calls because that is the preffered approach for new kernel
134 features and it means our user interface requirements. 149 interfaces. The only real difference was whether we wanted to use open(2)
135 150 and ioctl(2) or a couple of new system calls. System calls beat ioctls.
136 Additionally, it _is_ possible to more than one instance and
137 juggle more than one queue and thus more than one associated fd.
138 151