|
| 1 | + inotify |
| 2 | + a powerful yet simple file change notification system |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | +Document started 15 Mar 2005 by Robert Love < [email protected]> |
| 7 | + |
| 8 | +(i) User Interface |
| 9 | + |
| 10 | +Inotify is controlled by a set of three sys calls |
| 11 | + |
| 12 | +First step in using inotify is to initialise an inotify instance |
| 13 | + |
| 14 | + int fd = inotify_init (); |
| 15 | + |
| 16 | +Change events are managed by "watches". A watch is an (object,mask) pair where |
| 17 | +the object is a file or directory and the mask is a bit mask of one or more |
| 18 | +inotify events that the application wishes to receive. See <linux/inotify.h> |
| 19 | +for valid events. A watch is referenced by a watch descriptor, or wd. |
| 20 | + |
| 21 | +Watches are added via a path to the file. |
| 22 | + |
| 23 | +Watches on a directory will return events on any files inside of the directory. |
| 24 | + |
| 25 | +Adding a watch is simple, |
| 26 | + |
| 27 | + int wd = inotify_add_watch (fd, path, mask); |
| 28 | + |
| 29 | +You can add a large number of files via something like |
| 30 | + |
| 31 | + for each file to watch { |
| 32 | + int wd = inotify_add_watch (fd, file, mask); |
| 33 | + } |
| 34 | + |
| 35 | +You can update an existing watch in the same manner, by passing in a new mask. |
| 36 | + |
| 37 | +An existing watch is removed via the INOTIFY_IGNORE ioctl, for example |
| 38 | + |
| 39 | + inotify_rm_watch (fd, wd); |
| 40 | + |
| 41 | +Events are provided in the form of an inotify_event structure that is read(2) |
| 42 | +from a inotify instance fd. The filename is of dynamic length and follows the |
| 43 | +struct. It is of size len. The filename is padded with null bytes to ensure |
| 44 | +proper alignment. This padding is reflected in len. |
| 45 | + |
| 46 | +You can slurp multiple events by passing a large buffer, for example |
| 47 | + |
| 48 | + size_t len = read (fd, buf, BUF_LEN); |
| 49 | + |
| 50 | +Will return as many events as are available and fit in BUF_LEN. |
| 51 | + |
| 52 | +each inotify instance fd is also select()- and poll()-able. |
| 53 | + |
| 54 | +You can find the size of the current event queue via the FIONREAD ioctl. |
| 55 | + |
| 56 | +All watches are destroyed and cleaned up on close. |
| 57 | + |
| 58 | + |
| 59 | +(ii) Internal Kernel Implementation |
| 60 | + |
| 61 | +Each open inotify instance is associated with an inotify_device structure. |
| 62 | + |
| 63 | +Each watch is associated with an inotify_watch structure. Watches are chained |
| 64 | +off of each associated device and each associated inode. |
| 65 | + |
| 66 | +See fs/inotify.c for the locking and lifetime rules. |
| 67 | + |
| 68 | + |
| 69 | +(iii) Rationale |
| 70 | + |
| 71 | +Q: What is the design decision behind not tying the watch to the open fd of |
| 72 | + the watched object? |
| 73 | + |
| 74 | +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 |
| 76 | + 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 |
| 78 | + unmounted. |
| 79 | + |
| 80 | +Q: What is the design decision behind using an-fd-per-device as opposed to |
| 81 | + an fd-per-watch? |
| 82 | + |
| 83 | +A: An fd-per-watch quickly consumes more file descriptors than are allowed, |
| 84 | + more fd's than are feasible to manage, and more fd's than are optimally |
| 85 | + select()-able. Yes, root can bump the per-process fd limit and yes, users |
| 86 | + 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 |
| 88 | + 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 |
| 90 | + and no twiddling with fd limits. Initializing an inotify instance two |
| 91 | + 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 |
| 93 | + should. |
| 94 | + |
| 95 | + There are other good arguments. With a single fd, there is a single |
| 96 | + item to block on, which is mapped to a single queue of events. The single |
| 97 | + fd returns all watch events and also any potential out-of-band data. If |
| 98 | + every fd was a separate watch, |
| 99 | + |
| 100 | + - There would be no way to get event ordering. Events on file foo and |
| 101 | + file bar would pop poll() on both fd's, but there would be no way to tell |
| 102 | + which happened first. A single queue trivially gives you ordering. Such |
| 103 | + ordering is crucial to existing applications such as Beagle. Imagine |
| 104 | + "mv a b ; mv b a" events without ordering. |
| 105 | + |
| 106 | + - We'd have to maintain n fd's and n internal queues with state, |
| 107 | + versus just one. It is a lot messier in the kernel. A single, linear |
| 108 | + queue is the data structure that makes sense. |
| 109 | + |
| 110 | + - User-space developers prefer the current API. The Beagle guys, for |
| 111 | + 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? |
| 113 | + |
| 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. |
| 118 | + |
| 119 | + - 1024 is still too low. ;-) |
| 120 | + |
| 121 | + When you talk about designing a file change notification system that |
| 122 | + scales to 1000s of directories, juggling 1000s of fd's just does not seem |
| 123 | + the right interface. It is too heavy. |
| 124 | + |
| 125 | +Q: Why the system call approach? |
| 126 | + |
| 127 | +A: The poor user-space interface is the second biggest problem with dnotify. |
| 128 | + Signals are a terrible, terrible interface for file notification. Or for |
| 129 | + anything, for that matter. The ideal solution, from all perspectives, is a |
| 130 | + file descriptor-based one that allows basic file I/O and poll/select. |
| 131 | + 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 |
| 133 | + family of system calls because that is the preffered approach for new kernel |
| 134 | + features and it means our user interface requirements. |
| 135 | + |
| 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 | + |
0 commit comments