diff options
-rw-r--r-- | Documentation/filesystems/inotify.txt | 130 |
1 files changed, 124 insertions, 6 deletions
diff --git a/Documentation/filesystems/inotify.txt b/Documentation/filesystems/inotify.txt index 6d501903f68e..59a919f16144 100644 --- a/Documentation/filesystems/inotify.txt +++ b/Documentation/filesystems/inotify.txt | |||
@@ -69,17 +69,135 @@ Prototypes: | |||
69 | int inotify_rm_watch (int fd, __u32 mask); | 69 | int inotify_rm_watch (int fd, __u32 mask); |
70 | 70 | ||
71 | 71 | ||
72 | (iii) Internal Kernel Implementation | 72 | (iii) Kernel Interface |
73 | 73 | ||
74 | Each inotify instance is associated with an inotify_device structure. | 74 | Inotify's kernel API consists a set of functions for managing watches and an |
75 | event callback. | ||
76 | |||
77 | To use the kernel API, you must first initialize an inotify instance with a set | ||
78 | of inotify_operations. You are given an opaque inotify_handle, which you use | ||
79 | for any further calls to inotify. | ||
80 | |||
81 | struct inotify_handle *ih = inotify_init(my_event_handler); | ||
82 | |||
83 | You must provide a function for processing events and a function for destroying | ||
84 | the inotify watch. | ||
85 | |||
86 | void handle_event(struct inotify_watch *watch, u32 wd, u32 mask, | ||
87 | u32 cookie, const char *name, struct inode *inode) | ||
88 | |||
89 | watch - the pointer to the inotify_watch that triggered this call | ||
90 | wd - the watch descriptor | ||
91 | mask - describes the event that occurred | ||
92 | cookie - an identifier for synchronizing events | ||
93 | name - the dentry name for affected files in a directory-based event | ||
94 | inode - the affected inode in a directory-based event | ||
95 | |||
96 | void destroy_watch(struct inotify_watch *watch) | ||
97 | |||
98 | You may add watches by providing a pre-allocated and initialized inotify_watch | ||
99 | structure and specifying the inode to watch along with an inotify event mask. | ||
100 | You must pin the inode during the call. You will likely wish to embed the | ||
101 | inotify_watch structure in a structure of your own which contains other | ||
102 | information about the watch. Once you add an inotify watch, it is immediately | ||
103 | subject to removal depending on filesystem events. You must grab a reference if | ||
104 | you depend on the watch hanging around after the call. | ||
105 | |||
106 | inotify_init_watch(&my_watch->iwatch); | ||
107 | inotify_get_watch(&my_watch->iwatch); // optional | ||
108 | s32 wd = inotify_add_watch(ih, &my_watch->iwatch, inode, mask); | ||
109 | inotify_put_watch(&my_watch->iwatch); // optional | ||
110 | |||
111 | You may use the watch descriptor (wd) or the address of the inotify_watch for | ||
112 | other inotify operations. You must not directly read or manipulate data in the | ||
113 | inotify_watch. Additionally, you must not call inotify_add_watch() more than | ||
114 | once for a given inotify_watch structure, unless you have first called either | ||
115 | inotify_rm_watch() or inotify_rm_wd(). | ||
116 | |||
117 | To determine if you have already registered a watch for a given inode, you may | ||
118 | call inotify_find_watch(), which gives you both the wd and the watch pointer for | ||
119 | the inotify_watch, or an error if the watch does not exist. | ||
120 | |||
121 | wd = inotify_find_watch(ih, inode, &watchp); | ||
122 | |||
123 | You may use container_of() on the watch pointer to access your own data | ||
124 | associated with a given watch. When an existing watch is found, | ||
125 | inotify_find_watch() bumps the refcount before releasing its locks. You must | ||
126 | put that reference with: | ||
127 | |||
128 | put_inotify_watch(watchp); | ||
129 | |||
130 | Call inotify_find_update_watch() to update the event mask for an existing watch. | ||
131 | inotify_find_update_watch() returns the wd of the updated watch, or an error if | ||
132 | the watch does not exist. | ||
133 | |||
134 | wd = inotify_find_update_watch(ih, inode, mask); | ||
135 | |||
136 | An existing watch may be removed by calling either inotify_rm_watch() or | ||
137 | inotify_rm_wd(). | ||
138 | |||
139 | int ret = inotify_rm_watch(ih, &my_watch->iwatch); | ||
140 | int ret = inotify_rm_wd(ih, wd); | ||
141 | |||
142 | A watch may be removed while executing your event handler with the following: | ||
143 | |||
144 | inotify_remove_watch_locked(ih, iwatch); | ||
145 | |||
146 | Call inotify_destroy() to remove all watches from your inotify instance and | ||
147 | release it. If there are no outstanding references, inotify_destroy() will call | ||
148 | your destroy_watch op for each watch. | ||
149 | |||
150 | inotify_destroy(ih); | ||
151 | |||
152 | When inotify removes a watch, it sends an IN_IGNORED event to your callback. | ||
153 | You may use this event as an indication to free the watch memory. Note that | ||
154 | inotify may remove a watch due to filesystem events, as well as by your request. | ||
155 | If you use IN_ONESHOT, inotify will remove the watch after the first event, at | ||
156 | which point you may call the final inotify_put_watch. | ||
157 | |||
158 | (iv) Kernel Interface Prototypes | ||
159 | |||
160 | struct inotify_handle *inotify_init(struct inotify_operations *ops); | ||
161 | |||
162 | inotify_init_watch(struct inotify_watch *watch); | ||
163 | |||
164 | s32 inotify_add_watch(struct inotify_handle *ih, | ||
165 | struct inotify_watch *watch, | ||
166 | struct inode *inode, u32 mask); | ||
167 | |||
168 | s32 inotify_find_watch(struct inotify_handle *ih, struct inode *inode, | ||
169 | struct inotify_watch **watchp); | ||
170 | |||
171 | s32 inotify_find_update_watch(struct inotify_handle *ih, | ||
172 | struct inode *inode, u32 mask); | ||
173 | |||
174 | int inotify_rm_wd(struct inotify_handle *ih, u32 wd); | ||
175 | |||
176 | int inotify_rm_watch(struct inotify_handle *ih, | ||
177 | struct inotify_watch *watch); | ||
178 | |||
179 | void inotify_remove_watch_locked(struct inotify_handle *ih, | ||
180 | struct inotify_watch *watch); | ||
181 | |||
182 | void inotify_destroy(struct inotify_handle *ih); | ||
183 | |||
184 | void get_inotify_watch(struct inotify_watch *watch); | ||
185 | void put_inotify_watch(struct inotify_watch *watch); | ||
186 | |||
187 | |||
188 | (v) Internal Kernel Implementation | ||
189 | |||
190 | Each inotify instance is represented by an inotify_handle structure. | ||
191 | Inotify's userspace consumers also have an inotify_device which is | ||
192 | associated with the inotify_handle, and on which events are queued. | ||
75 | 193 | ||
76 | Each watch is associated with an inotify_watch structure. Watches are chained | 194 | Each watch is associated with an inotify_watch structure. Watches are chained |
77 | off of each associated device and each associated inode. | 195 | off of each associated inotify_handle and each associated inode. |
78 | 196 | ||
79 | See fs/inotify.c for the locking and lifetime rules. | 197 | See fs/inotify.c and fs/inotify_user.c for the locking and lifetime rules. |
80 | 198 | ||
81 | 199 | ||
82 | (iv) Rationale | 200 | (vi) Rationale |
83 | 201 | ||
84 | Q: What is the design decision behind not tying the watch to the open fd of | 202 | Q: What is the design decision behind not tying the watch to the open fd of |
85 | the watched object? | 203 | the watched object? |
@@ -145,7 +263,7 @@ A: The poor user-space interface is the second biggest problem with dnotify. | |||
145 | file descriptor-based one that allows basic file I/O and poll/select. | 263 | file descriptor-based one that allows basic file I/O and poll/select. |
146 | Obtaining the fd and managing the watches could have been done either via a | 264 | Obtaining the fd and managing the watches could have been done either via a |
147 | device file or a family of new system calls. We decided to implement a | 265 | device file or a family of new system calls. We decided to implement a |
148 | family of system calls because that is the preffered approach for new kernel | 266 | family of system calls because that is the preferred approach for new kernel |
149 | interfaces. The only real difference was whether we wanted to use open(2) | 267 | interfaces. The only real difference was whether we wanted to use open(2) |
150 | and ioctl(2) or a couple of new system calls. System calls beat ioctls. | 268 | and ioctl(2) or a couple of new system calls. System calls beat ioctls. |
151 | 269 | ||