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