Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | The text below describes the locking rules for VFS-related methods. |
2 | It is (believed to be) up-to-date. *Please*, if you change anything in | |
3 | prototypes or locking protocols - update this file. And update the relevant | |
4 | instances in the tree, don't leave that to maintainers of filesystems/devices/ | |
5 | etc. At the very least, put the list of dubious cases in the end of this file. | |
6 | Don't turn it into log - maintainers of out-of-the-tree code are supposed to | |
7 | be able to use diff(1). | |
8 | Thing currently missing here: socket operations. Alexey? | |
9 | ||
10 | --------------------------- dentry_operations -------------------------- | |
11 | prototypes: | |
0b728e19 | 12 | int (*d_revalidate)(struct dentry *, unsigned int); |
ecf3d1f1 | 13 | int (*d_weak_revalidate)(struct dentry *, unsigned int); |
da53be12 LT |
14 | int (*d_hash)(const struct dentry *, struct qstr *); |
15 | int (*d_compare)(const struct dentry *, const struct dentry *, | |
621e155a | 16 | unsigned int, const char *, const struct qstr *); |
1da177e4 LT |
17 | int (*d_delete)(struct dentry *); |
18 | void (*d_release)(struct dentry *); | |
19 | void (*d_iput)(struct dentry *, struct inode *); | |
c23fbb6b | 20 | char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen); |
9875cf80 | 21 | struct vfsmount *(*d_automount)(struct path *path); |
cc53ce53 | 22 | int (*d_manage)(struct dentry *, bool); |
1da177e4 LT |
23 | |
24 | locking rules: | |
34286d66 NP |
25 | rename_lock ->d_lock may block rcu-walk |
26 | d_revalidate: no no yes (ref-walk) maybe | |
ecf3d1f1 | 27 | d_weak_revalidate:no no yes no |
34286d66 NP |
28 | d_hash no no no maybe |
29 | d_compare: yes no no maybe | |
30 | d_delete: no yes no no | |
31 | d_release: no no yes no | |
f0023bc6 | 32 | d_prune: no yes no no |
34286d66 NP |
33 | d_iput: no no yes no |
34 | d_dname: no no no no | |
9875cf80 | 35 | d_automount: no no yes no |
ab90911f | 36 | d_manage: no no yes (ref-walk) maybe |
1da177e4 LT |
37 | |
38 | --------------------------- inode_operations --------------------------- | |
39 | prototypes: | |
ebfc3b49 | 40 | int (*create) (struct inode *,struct dentry *,umode_t, bool); |
00cd8dd3 | 41 | struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); |
1da177e4 LT |
42 | int (*link) (struct dentry *,struct inode *,struct dentry *); |
43 | int (*unlink) (struct inode *,struct dentry *); | |
44 | int (*symlink) (struct inode *,struct dentry *,const char *); | |
18bb1db3 | 45 | int (*mkdir) (struct inode *,struct dentry *,umode_t); |
1da177e4 | 46 | int (*rmdir) (struct inode *,struct dentry *); |
1a67aafb | 47 | int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); |
1da177e4 LT |
48 | int (*rename) (struct inode *, struct dentry *, |
49 | struct inode *, struct dentry *); | |
520c8b16 MS |
50 | int (*rename2) (struct inode *, struct dentry *, |
51 | struct inode *, struct dentry *, unsigned int); | |
1da177e4 | 52 | int (*readlink) (struct dentry *, char __user *,int); |
b83be6f2 CH |
53 | void * (*follow_link) (struct dentry *, struct nameidata *); |
54 | void (*put_link) (struct dentry *, struct nameidata *, void *); | |
1da177e4 | 55 | void (*truncate) (struct inode *); |
b74c79e9 | 56 | int (*permission) (struct inode *, int, unsigned int); |
4e34e719 | 57 | int (*get_acl)(struct inode *, int); |
1da177e4 LT |
58 | int (*setattr) (struct dentry *, struct iattr *); |
59 | int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *); | |
60 | int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); | |
61 | ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); | |
62 | ssize_t (*listxattr) (struct dentry *, char *, size_t); | |
63 | int (*removexattr) (struct dentry *, const char *); | |
b83be6f2 | 64 | int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len); |
c3b2da31 | 65 | void (*update_time)(struct inode *, struct timespec *, int); |
d9585277 | 66 | int (*atomic_open)(struct inode *, struct dentry *, |
30d90494 | 67 | struct file *, unsigned open_flag, |
47237687 | 68 | umode_t create_mode, int *opened); |
48bde8d3 | 69 | int (*tmpfile) (struct inode *, struct dentry *, umode_t); |
4aa7c634 | 70 | int (*dentry_open)(struct dentry *, struct file *, const struct cred *); |
1da177e4 LT |
71 | |
72 | locking rules: | |
b83be6f2 | 73 | all may block |
a7bc02f4 | 74 | i_mutex(inode) |
1da177e4 LT |
75 | lookup: yes |
76 | create: yes | |
77 | link: yes (both) | |
78 | mknod: yes | |
79 | symlink: yes | |
80 | mkdir: yes | |
81 | unlink: yes (both) | |
82 | rmdir: yes (both) (see below) | |
83 | rename: yes (all) (see below) | |
520c8b16 | 84 | rename2: yes (all) (see below) |
1da177e4 LT |
85 | readlink: no |
86 | follow_link: no | |
b83be6f2 | 87 | put_link: no |
1da177e4 | 88 | setattr: yes |
b74c79e9 | 89 | permission: no (may not block if called in rcu-walk mode) |
4e34e719 | 90 | get_acl: no |
1da177e4 LT |
91 | getattr: no |
92 | setxattr: yes | |
93 | getxattr: no | |
94 | listxattr: no | |
95 | removexattr: yes | |
b83be6f2 | 96 | fiemap: no |
c3b2da31 | 97 | update_time: no |
d18e9008 | 98 | atomic_open: yes |
48bde8d3 | 99 | tmpfile: no |
4aa7c634 | 100 | dentry_open: no |
c3b2da31 | 101 | |
a7bc02f4 | 102 | Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on |
1da177e4 | 103 | victim. |
520c8b16 MS |
104 | cross-directory ->rename() and rename2() has (per-superblock) |
105 | ->s_vfs_rename_sem. | |
1da177e4 LT |
106 | |
107 | See Documentation/filesystems/directory-locking for more detailed discussion | |
108 | of the locking scheme for directory operations. | |
109 | ||
110 | --------------------------- super_operations --------------------------- | |
111 | prototypes: | |
112 | struct inode *(*alloc_inode)(struct super_block *sb); | |
113 | void (*destroy_inode)(struct inode *); | |
aa385729 | 114 | void (*dirty_inode) (struct inode *, int flags); |
b83be6f2 | 115 | int (*write_inode) (struct inode *, struct writeback_control *wbc); |
336fb3b9 AV |
116 | int (*drop_inode) (struct inode *); |
117 | void (*evict_inode) (struct inode *); | |
1da177e4 | 118 | void (*put_super) (struct super_block *); |
1da177e4 | 119 | int (*sync_fs)(struct super_block *sb, int wait); |
c4be0c1d TS |
120 | int (*freeze_fs) (struct super_block *); |
121 | int (*unfreeze_fs) (struct super_block *); | |
726c3342 | 122 | int (*statfs) (struct dentry *, struct kstatfs *); |
1da177e4 | 123 | int (*remount_fs) (struct super_block *, int *, char *); |
1da177e4 | 124 | void (*umount_begin) (struct super_block *); |
34c80b1d | 125 | int (*show_options)(struct seq_file *, struct dentry *); |
1da177e4 LT |
126 | ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); |
127 | ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); | |
b83be6f2 | 128 | int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t); |
1da177e4 LT |
129 | |
130 | locking rules: | |
336fb3b9 | 131 | All may block [not true, see below] |
7e325d3a CH |
132 | s_umount |
133 | alloc_inode: | |
134 | destroy_inode: | |
aa385729 | 135 | dirty_inode: |
7e325d3a | 136 | write_inode: |
f283c86a | 137 | drop_inode: !!!inode->i_lock!!! |
336fb3b9 | 138 | evict_inode: |
7e325d3a | 139 | put_super: write |
7e325d3a | 140 | sync_fs: read |
06fd516c VA |
141 | freeze_fs: write |
142 | unfreeze_fs: write | |
336fb3b9 AV |
143 | statfs: maybe(read) (see below) |
144 | remount_fs: write | |
7e325d3a CH |
145 | umount_begin: no |
146 | show_options: no (namespace_sem) | |
147 | quota_read: no (see below) | |
148 | quota_write: no (see below) | |
b83be6f2 | 149 | bdev_try_to_free_page: no (see below) |
1da177e4 | 150 | |
336fb3b9 AV |
151 | ->statfs() has s_umount (shared) when called by ustat(2) (native or |
152 | compat), but that's an accident of bad API; s_umount is used to pin | |
153 | the superblock down when we only have dev_t given us by userland to | |
154 | identify the superblock. Everything else (statfs(), fstatfs(), etc.) | |
155 | doesn't hold it when calling ->statfs() - superblock is pinned down | |
156 | by resolving the pathname passed to syscall. | |
1da177e4 LT |
157 | ->quota_read() and ->quota_write() functions are both guaranteed to |
158 | be the only ones operating on the quota file by the quota code (via | |
159 | dqio_sem) (unless an admin really wants to screw up something and | |
160 | writes to quota files with quotas on). For other details about locking | |
161 | see also dquot_operations section. | |
b83be6f2 CH |
162 | ->bdev_try_to_free_page is called from the ->releasepage handler of |
163 | the block device inode. See there for more details. | |
1da177e4 LT |
164 | |
165 | --------------------------- file_system_type --------------------------- | |
166 | prototypes: | |
b83be6f2 CH |
167 | struct dentry *(*mount) (struct file_system_type *, int, |
168 | const char *, void *); | |
1da177e4 LT |
169 | void (*kill_sb) (struct super_block *); |
170 | locking rules: | |
b83be6f2 | 171 | may block |
b83be6f2 CH |
172 | mount yes |
173 | kill_sb yes | |
1da177e4 | 174 | |
1a102ff9 AV |
175 | ->mount() returns ERR_PTR or the root dentry; its superblock should be locked |
176 | on return. | |
1da177e4 LT |
177 | ->kill_sb() takes a write-locked superblock, does all shutdown work on it, |
178 | unlocks and drops the reference. | |
179 | ||
180 | --------------------------- address_space_operations -------------------------- | |
181 | prototypes: | |
182 | int (*writepage)(struct page *page, struct writeback_control *wbc); | |
183 | int (*readpage)(struct file *, struct page *); | |
184 | int (*sync_page)(struct page *); | |
185 | int (*writepages)(struct address_space *, struct writeback_control *); | |
186 | int (*set_page_dirty)(struct page *page); | |
187 | int (*readpages)(struct file *filp, struct address_space *mapping, | |
188 | struct list_head *pages, unsigned nr_pages); | |
4e02ed4b NP |
189 | int (*write_begin)(struct file *, struct address_space *mapping, |
190 | loff_t pos, unsigned len, unsigned flags, | |
191 | struct page **pagep, void **fsdata); | |
192 | int (*write_end)(struct file *, struct address_space *mapping, | |
193 | loff_t pos, unsigned len, unsigned copied, | |
194 | struct page *page, void *fsdata); | |
1da177e4 | 195 | sector_t (*bmap)(struct address_space *, sector_t); |
d47992f8 | 196 | void (*invalidatepage) (struct page *, unsigned int, unsigned int); |
1da177e4 | 197 | int (*releasepage) (struct page *, int); |
6072d13c | 198 | void (*freepage)(struct page *); |
d8d3d94b | 199 | int (*direct_IO)(int, struct kiocb *, struct iov_iter *iter, loff_t offset); |
b83be6f2 CH |
200 | int (*migratepage)(struct address_space *, struct page *, struct page *); |
201 | int (*launder_page)(struct page *); | |
c186afb4 | 202 | int (*is_partially_uptodate)(struct page *, unsigned long, unsigned long); |
b83be6f2 | 203 | int (*error_remove_page)(struct address_space *, struct page *); |
62c230bc MG |
204 | int (*swap_activate)(struct file *); |
205 | int (*swap_deactivate)(struct file *); | |
1da177e4 LT |
206 | |
207 | locking rules: | |
6072d13c | 208 | All except set_page_dirty and freepage may block |
1da177e4 | 209 | |
b83be6f2 CH |
210 | PageLocked(page) i_mutex |
211 | writepage: yes, unlocks (see below) | |
212 | readpage: yes, unlocks | |
213 | sync_page: maybe | |
214 | writepages: | |
215 | set_page_dirty no | |
216 | readpages: | |
217 | write_begin: locks the page yes | |
218 | write_end: yes, unlocks yes | |
219 | bmap: | |
220 | invalidatepage: yes | |
221 | releasepage: yes | |
222 | freepage: yes | |
223 | direct_IO: | |
b83be6f2 CH |
224 | migratepage: yes (both) |
225 | launder_page: yes | |
226 | is_partially_uptodate: yes | |
227 | error_remove_page: yes | |
62c230bc MG |
228 | swap_activate: no |
229 | swap_deactivate: no | |
1da177e4 | 230 | |
4e02ed4b | 231 | ->write_begin(), ->write_end(), ->sync_page() and ->readpage() |
1da177e4 LT |
232 | may be called from the request handler (/dev/loop). |
233 | ||
234 | ->readpage() unlocks the page, either synchronously or via I/O | |
235 | completion. | |
236 | ||
237 | ->readpages() populates the pagecache with the passed pages and starts | |
238 | I/O against them. They come unlocked upon I/O completion. | |
239 | ||
240 | ->writepage() is used for two purposes: for "memory cleansing" and for | |
241 | "sync". These are quite different operations and the behaviour may differ | |
242 | depending upon the mode. | |
243 | ||
244 | If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then | |
245 | it *must* start I/O against the page, even if that would involve | |
246 | blocking on in-progress I/O. | |
247 | ||
248 | If writepage is called for memory cleansing (sync_mode == | |
249 | WBC_SYNC_NONE) then its role is to get as much writeout underway as | |
250 | possible. So writepage should try to avoid blocking against | |
251 | currently-in-progress I/O. | |
252 | ||
253 | If the filesystem is not called for "sync" and it determines that it | |
254 | would need to block against in-progress I/O to be able to start new I/O | |
255 | against the page the filesystem should redirty the page with | |
256 | redirty_page_for_writepage(), then unlock the page and return zero. | |
257 | This may also be done to avoid internal deadlocks, but rarely. | |
258 | ||
3a4fa0a2 | 259 | If the filesystem is called for sync then it must wait on any |
1da177e4 LT |
260 | in-progress I/O and then start new I/O. |
261 | ||
2054606a ND |
262 | The filesystem should unlock the page synchronously, before returning to the |
263 | caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE | |
264 | value. WRITEPAGE_ACTIVATE means that page cannot really be written out | |
265 | currently, and VM should stop calling ->writepage() on this page for some | |
266 | time. VM does this by moving page to the head of the active list, hence the | |
267 | name. | |
1da177e4 LT |
268 | |
269 | Unless the filesystem is going to redirty_page_for_writepage(), unlock the page | |
270 | and return zero, writepage *must* run set_page_writeback() against the page, | |
271 | followed by unlocking it. Once set_page_writeback() has been run against the | |
272 | page, write I/O can be submitted and the write I/O completion handler must run | |
273 | end_page_writeback() once the I/O is complete. If no I/O is submitted, the | |
274 | filesystem must run end_page_writeback() against the page before returning from | |
275 | writepage. | |
276 | ||
277 | That is: after 2.5.12, pages which are under writeout are *not* locked. Note, | |
278 | if the filesystem needs the page to be locked during writeout, that is ok, too, | |
279 | the page is allowed to be unlocked at any point in time between the calls to | |
280 | set_page_writeback() and end_page_writeback(). | |
281 | ||
282 | Note, failure to run either redirty_page_for_writepage() or the combination of | |
283 | set_page_writeback()/end_page_writeback() on a page submitted to writepage | |
284 | will leave the page itself marked clean but it will be tagged as dirty in the | |
285 | radix tree. This incoherency can lead to all sorts of hard-to-debug problems | |
286 | in the filesystem like having dirty inodes at umount and losing written data. | |
287 | ||
288 | ->sync_page() locking rules are not well-defined - usually it is called | |
289 | with lock on page, but that is not guaranteed. Considering the currently | |
290 | existing instances of this method ->sync_page() itself doesn't look | |
291 | well-defined... | |
292 | ||
293 | ->writepages() is used for periodic writeback and for syscall-initiated | |
294 | sync operations. The address_space should start I/O against at least | |
295 | *nr_to_write pages. *nr_to_write must be decremented for each page which is | |
296 | written. The address_space implementation may write more (or less) pages | |
297 | than *nr_to_write asks for, but it should try to be reasonably close. If | |
298 | nr_to_write is NULL, all dirty pages must be written. | |
299 | ||
300 | writepages should _only_ write pages which are present on | |
301 | mapping->io_pages. | |
302 | ||
303 | ->set_page_dirty() is called from various places in the kernel | |
304 | when the target page is marked as needing writeback. It may be called | |
305 | under spinlock (it cannot block) and is sometimes called with the page | |
306 | not locked. | |
307 | ||
308 | ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some | |
b83be6f2 CH |
309 | filesystems and by the swapper. The latter will eventually go away. Please, |
310 | keep it that way and don't breed new callers. | |
1da177e4 LT |
311 | |
312 | ->invalidatepage() is called when the filesystem must attempt to drop | |
d47992f8 LC |
313 | some or all of the buffers from the page when it is being truncated. It |
314 | returns zero on success. If ->invalidatepage is zero, the kernel uses | |
1da177e4 LT |
315 | block_invalidatepage() instead. |
316 | ||
317 | ->releasepage() is called when the kernel is about to try to drop the | |
318 | buffers from the page in preparation for freeing it. It returns zero to | |
319 | indicate that the buffers are (or may be) freeable. If ->releasepage is zero, | |
320 | the kernel assumes that the fs has no private interest in the buffers. | |
321 | ||
6072d13c LT |
322 | ->freepage() is called when the kernel is done dropping the page |
323 | from the page cache. | |
324 | ||
e3db7691 TM |
325 | ->launder_page() may be called prior to releasing a page if |
326 | it is still found to be dirty. It returns zero if the page was successfully | |
327 | cleaned, or an error value if not. Note that in order to prevent the page | |
328 | getting mapped back in and redirtied, it needs to be kept locked | |
329 | across the entire operation. | |
330 | ||
62c230bc MG |
331 | ->swap_activate will be called with a non-zero argument on |
332 | files backing (non block device backed) swapfiles. A return value | |
333 | of zero indicates success, in which case this file can be used for | |
334 | backing swapspace. The swapspace operations will be proxied to the | |
335 | address space operations. | |
336 | ||
337 | ->swap_deactivate() will be called in the sys_swapoff() | |
338 | path after ->swap_activate() returned success. | |
339 | ||
1da177e4 LT |
340 | ----------------------- file_lock_operations ------------------------------ |
341 | prototypes: | |
1da177e4 LT |
342 | void (*fl_copy_lock)(struct file_lock *, struct file_lock *); |
343 | void (*fl_release_private)(struct file_lock *); | |
344 | ||
345 | ||
346 | locking rules: | |
1c8c601a | 347 | inode->i_lock may block |
b83be6f2 | 348 | fl_copy_lock: yes no |
2ece173e JL |
349 | fl_release_private: maybe maybe[1] |
350 | ||
351 | [1]: ->fl_release_private for flock or POSIX locks is currently allowed | |
352 | to block. Leases however can still be freed while the i_lock is held and | |
353 | so fl_release_private called on a lease should not block. | |
1da177e4 LT |
354 | |
355 | ----------------------- lock_manager_operations --------------------------- | |
356 | prototypes: | |
8fb47a4f | 357 | int (*lm_compare_owner)(struct file_lock *, struct file_lock *); |
3999e493 | 358 | unsigned long (*lm_owner_key)(struct file_lock *); |
8fb47a4f BF |
359 | void (*lm_notify)(struct file_lock *); /* unblock callback */ |
360 | int (*lm_grant)(struct file_lock *, struct file_lock *, int); | |
8fb47a4f BF |
361 | void (*lm_break)(struct file_lock *); /* break_lease callback */ |
362 | int (*lm_change)(struct file_lock **, int); | |
1da177e4 LT |
363 | |
364 | locking rules: | |
1c8c601a | 365 | |
7b2296af JL |
366 | inode->i_lock blocked_lock_lock may block |
367 | lm_compare_owner: yes[1] maybe no | |
368 | lm_owner_key yes[1] yes no | |
369 | lm_notify: yes yes no | |
370 | lm_grant: no no no | |
371 | lm_break: yes no no | |
372 | lm_change yes no no | |
1c8c601a | 373 | |
3999e493 JL |
374 | [1]: ->lm_compare_owner and ->lm_owner_key are generally called with |
375 | *an* inode->i_lock held. It may not be the i_lock of the inode | |
376 | associated with either file_lock argument! This is the case with deadlock | |
377 | detection, since the code has to chase down the owners of locks that may | |
378 | be entirely unrelated to the one on which the lock is being acquired. | |
7b2296af | 379 | For deadlock detection however, the blocked_lock_lock is also held. The |
3999e493 JL |
380 | fact that these locks are held ensures that the file_locks do not |
381 | disappear out from under you while doing the comparison or generating an | |
382 | owner key. | |
b83be6f2 | 383 | |
1da177e4 LT |
384 | --------------------------- buffer_head ----------------------------------- |
385 | prototypes: | |
386 | void (*b_end_io)(struct buffer_head *bh, int uptodate); | |
387 | ||
388 | locking rules: | |
389 | called from interrupts. In other words, extreme care is needed here. | |
390 | bh is locked, but that's all warranties we have here. Currently only RAID1, | |
391 | highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices | |
392 | call this method upon the IO completion. | |
393 | ||
394 | --------------------------- block_device_operations ----------------------- | |
395 | prototypes: | |
e1455d1b CH |
396 | int (*open) (struct block_device *, fmode_t); |
397 | int (*release) (struct gendisk *, fmode_t); | |
398 | int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); | |
399 | int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long); | |
400 | int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *); | |
1da177e4 | 401 | int (*media_changed) (struct gendisk *); |
e1455d1b | 402 | void (*unlock_native_capacity) (struct gendisk *); |
1da177e4 | 403 | int (*revalidate_disk) (struct gendisk *); |
e1455d1b CH |
404 | int (*getgeo)(struct block_device *, struct hd_geometry *); |
405 | void (*swap_slot_free_notify) (struct block_device *, unsigned long); | |
1da177e4 LT |
406 | |
407 | locking rules: | |
b83be6f2 CH |
408 | bd_mutex |
409 | open: yes | |
410 | release: yes | |
411 | ioctl: no | |
412 | compat_ioctl: no | |
413 | direct_access: no | |
414 | media_changed: no | |
415 | unlock_native_capacity: no | |
416 | revalidate_disk: no | |
417 | getgeo: no | |
418 | swap_slot_free_notify: no (see below) | |
e1455d1b CH |
419 | |
420 | media_changed, unlock_native_capacity and revalidate_disk are called only from | |
421 | check_disk_change(). | |
422 | ||
423 | swap_slot_free_notify is called with swap_lock and sometimes the page lock | |
424 | held. | |
1da177e4 | 425 | |
1da177e4 LT |
426 | |
427 | --------------------------- file_operations ------------------------------- | |
428 | prototypes: | |
429 | loff_t (*llseek) (struct file *, loff_t, int); | |
430 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); | |
1da177e4 | 431 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); |
027445c3 BP |
432 | ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t); |
433 | ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t); | |
293bc982 AV |
434 | ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); |
435 | ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); | |
2233f31a | 436 | int (*iterate) (struct file *, struct dir_context *); |
1da177e4 | 437 | unsigned int (*poll) (struct file *, struct poll_table_struct *); |
1da177e4 LT |
438 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); |
439 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); | |
440 | int (*mmap) (struct file *, struct vm_area_struct *); | |
441 | int (*open) (struct inode *, struct file *); | |
442 | int (*flush) (struct file *); | |
443 | int (*release) (struct inode *, struct file *); | |
02c24a82 | 444 | int (*fsync) (struct file *, loff_t start, loff_t end, int datasync); |
1da177e4 LT |
445 | int (*aio_fsync) (struct kiocb *, int datasync); |
446 | int (*fasync) (int, struct file *, int); | |
447 | int (*lock) (struct file *, int, struct file_lock *); | |
448 | ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, | |
449 | loff_t *); | |
450 | ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, | |
451 | loff_t *); | |
452 | ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, | |
453 | void __user *); | |
454 | ssize_t (*sendpage) (struct file *, struct page *, int, size_t, | |
455 | loff_t *, int); | |
456 | unsigned long (*get_unmapped_area)(struct file *, unsigned long, | |
457 | unsigned long, unsigned long, unsigned long); | |
458 | int (*check_flags)(int); | |
b83be6f2 CH |
459 | int (*flock) (struct file *, int, struct file_lock *); |
460 | ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, | |
461 | size_t, unsigned int); | |
462 | ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, | |
463 | size_t, unsigned int); | |
e6f5c789 | 464 | int (*setlease)(struct file *, long, struct file_lock **, void **); |
2fe17c10 | 465 | long (*fallocate)(struct file *, int, loff_t, loff_t); |
1da177e4 LT |
466 | }; |
467 | ||
468 | locking rules: | |
c45198ed | 469 | All may block. |
b83be6f2 | 470 | |
1da177e4 LT |
471 | ->llseek() locking has moved from llseek to the individual llseek |
472 | implementations. If your fs is not using generic_file_llseek, you | |
473 | need to acquire and release the appropriate locks in your ->llseek(). | |
474 | For many filesystems, it is probably safe to acquire the inode | |
866707fc JB |
475 | mutex or just to use i_size_read() instead. |
476 | Note: this does not protect the file->f_pos against concurrent modifications | |
477 | since this is something the userspace has to take care about. | |
1da177e4 | 478 | |
b83be6f2 CH |
479 | ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags. |
480 | Most instances call fasync_helper(), which does that maintenance, so it's | |
481 | not normally something one needs to worry about. Return values > 0 will be | |
482 | mapped to zero in the VFS layer. | |
1da177e4 LT |
483 | |
484 | ->readdir() and ->ioctl() on directories must be changed. Ideally we would | |
485 | move ->readdir() to inode_operations and use a separate method for directory | |
486 | ->ioctl() or kill the latter completely. One of the problems is that for | |
487 | anything that resembles union-mount we won't have a struct file for all | |
488 | components. And there are other reasons why the current interface is a mess... | |
489 | ||
1da177e4 LT |
490 | ->read on directories probably must go away - we should just enforce -EISDIR |
491 | in sys_read() and friends. | |
492 | ||
f82b4b67 JL |
493 | ->setlease operations should call generic_setlease() before or after setting |
494 | the lease within the individual filesystem to record the result of the | |
495 | operation | |
496 | ||
1da177e4 LT |
497 | --------------------------- dquot_operations ------------------------------- |
498 | prototypes: | |
1da177e4 LT |
499 | int (*write_dquot) (struct dquot *); |
500 | int (*acquire_dquot) (struct dquot *); | |
501 | int (*release_dquot) (struct dquot *); | |
502 | int (*mark_dirty) (struct dquot *); | |
503 | int (*write_info) (struct super_block *, int); | |
504 | ||
505 | These operations are intended to be more or less wrapping functions that ensure | |
506 | a proper locking wrt the filesystem and call the generic quota operations. | |
507 | ||
508 | What filesystem should expect from the generic quota functions: | |
509 | ||
510 | FS recursion Held locks when called | |
1da177e4 LT |
511 | write_dquot: yes dqonoff_sem or dqptr_sem |
512 | acquire_dquot: yes dqonoff_sem or dqptr_sem | |
513 | release_dquot: yes dqonoff_sem or dqptr_sem | |
514 | mark_dirty: no - | |
515 | write_info: yes dqonoff_sem | |
516 | ||
517 | FS recursion means calling ->quota_read() and ->quota_write() from superblock | |
518 | operations. | |
519 | ||
1da177e4 LT |
520 | More details about quota locking can be found in fs/dquot.c. |
521 | ||
522 | --------------------------- vm_operations_struct ----------------------------- | |
523 | prototypes: | |
524 | void (*open)(struct vm_area_struct*); | |
525 | void (*close)(struct vm_area_struct*); | |
d0217ac0 | 526 | int (*fault)(struct vm_area_struct*, struct vm_fault *); |
c2ec175c | 527 | int (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *); |
28b2ee20 | 528 | int (*access)(struct vm_area_struct *, unsigned long, void*, int, int); |
1da177e4 LT |
529 | |
530 | locking rules: | |
b83be6f2 CH |
531 | mmap_sem PageLocked(page) |
532 | open: yes | |
533 | close: yes | |
534 | fault: yes can return with page locked | |
8c6e50b0 | 535 | map_pages: yes |
b83be6f2 CH |
536 | page_mkwrite: yes can return with page locked |
537 | access: yes | |
ed2f2f9b | 538 | |
b827e496 NP |
539 | ->fault() is called when a previously not present pte is about |
540 | to be faulted in. The filesystem must find and return the page associated | |
541 | with the passed in "pgoff" in the vm_fault structure. If it is possible that | |
542 | the page may be truncated and/or invalidated, then the filesystem must lock | |
543 | the page, then ensure it is not already truncated (the page lock will block | |
544 | subsequent truncate), and then return with VM_FAULT_LOCKED, and the page | |
545 | locked. The VM will unlock the page. | |
546 | ||
8c6e50b0 KS |
547 | ->map_pages() is called when VM asks to map easy accessible pages. |
548 | Filesystem should find and map pages associated with offsets from "pgoff" | |
549 | till "max_pgoff". ->map_pages() is called with page table locked and must | |
550 | not block. If it's not possible to reach a page without blocking, | |
551 | filesystem should skip it. Filesystem should use do_set_pte() to setup | |
552 | page table entry. Pointer to entry associated with offset "pgoff" is | |
553 | passed in "pte" field in vm_fault structure. Pointers to entries for other | |
554 | offsets should be calculated relative to "pte". | |
555 | ||
b827e496 NP |
556 | ->page_mkwrite() is called when a previously read-only pte is |
557 | about to become writeable. The filesystem again must ensure that there are | |
558 | no truncate/invalidate races, and then return with the page locked. If | |
559 | the page has been truncated, the filesystem should not look up a new page | |
560 | like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which | |
561 | will cause the VM to retry the fault. | |
1da177e4 | 562 | |
28b2ee20 | 563 | ->access() is called when get_user_pages() fails in |
507da6a1 | 564 | access_process_vm(), typically used to debug a process through |
28b2ee20 RR |
565 | /proc/pid/mem or ptrace. This function is needed only for |
566 | VM_IO | VM_PFNMAP VMAs. | |
567 | ||
1da177e4 LT |
568 | ================================================================================ |
569 | Dubious stuff | |
570 | ||
571 | (if you break something or notice that it is broken and do not fix it yourself | |
572 | - at least put it here) |