5 The text below describes the locking rules for VFS-related methods.
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).
13 Thing currently missing here: socket operations. Alexey?
20 int (*d_revalidate)(struct dentry *, unsigned int);
21 int (*d_weak_revalidate)(struct dentry *, unsigned int);
22 int (*d_hash)(const struct dentry *, struct qstr *);
23 int (*d_compare)(const struct dentry *,
24 unsigned int, const char *, const struct qstr *);
25 int (*d_delete)(struct dentry *);
26 int (*d_init)(struct dentry *);
27 void (*d_release)(struct dentry *);
28 void (*d_iput)(struct dentry *, struct inode *);
29 char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
30 struct vfsmount *(*d_automount)(struct path *path);
31 int (*d_manage)(const struct path *, bool);
32 struct dentry *(*d_real)(struct dentry *, const struct inode *);
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
42 d_compare: yes no no maybe
43 d_delete: no yes no no
45 d_release: no no yes no
49 d_automount: no no yes no
50 d_manage: no no yes (ref-walk) maybe
52 ================== =========== ======== ============== ========
59 int (*create) (struct inode *,struct dentry *,umode_t, bool);
60 struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
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 *);
64 int (*mkdir) (struct inode *,struct dentry *,umode_t);
65 int (*rmdir) (struct inode *,struct dentry *);
66 int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
67 int (*rename) (struct inode *, struct dentry *,
68 struct inode *, struct dentry *, unsigned int);
69 int (*readlink) (struct dentry *, char __user *,int);
70 const char *(*get_link) (struct dentry *, struct inode *, struct delayed_call *);
71 void (*truncate) (struct inode *);
72 int (*permission) (struct inode *, int, unsigned int);
73 struct posix_acl * (*get_acl)(struct inode *, int, bool);
74 int (*setattr) (struct dentry *, struct iattr *);
75 int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
76 ssize_t (*listxattr) (struct dentry *, char *, size_t);
77 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
78 void (*update_time)(struct inode *, struct timespec *, int);
79 int (*atomic_open)(struct inode *, struct dentry *,
80 struct file *, unsigned open_flag,
82 int (*tmpfile) (struct inode *, struct dentry *, umode_t);
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);
90 ============= =============================================
92 ============= =============================================
95 link: exclusive (both)
99 unlink: exclusive (both)
100 rmdir: exclusive (both)(see below)
101 rename: exclusive (all) (see below)
105 permission: no (may not block if called in rcu-walk mode)
111 atomic_open: shared (exclusive if O_CREAT is set in open flags)
113 fileattr_get: no or exclusive
114 fileattr_set: exclusive
115 ============= =============================================
118 Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_rwsem
120 cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
122 See Documentation/filesystems/directory-locking.rst for more detailed discussion
123 of the locking scheme for directory operations.
125 xattr_handler operations
126 ========================
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,
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);
155 struct inode *(*alloc_inode)(struct super_block *sb);
156 void (*free_inode)(struct inode *);
157 void (*destroy_inode)(struct inode *);
158 void (*dirty_inode) (struct inode *, int flags);
159 int (*write_inode) (struct inode *, struct writeback_control *wbc);
160 int (*drop_inode) (struct inode *);
161 void (*evict_inode) (struct inode *);
162 void (*put_super) (struct super_block *);
163 int (*sync_fs)(struct super_block *sb, int wait);
164 int (*freeze_fs) (struct super_block *);
165 int (*unfreeze_fs) (struct super_block *);
166 int (*statfs) (struct dentry *, struct kstatfs *);
167 int (*remount_fs) (struct super_block *, int *, char *);
168 void (*umount_begin) (struct super_block *);
169 int (*show_options)(struct seq_file *, struct dentry *);
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);
174 All may block [not true, see below]
176 ====================== ============ ========================
178 ====================== ============ ========================
180 free_inode: called from RCU callback
184 drop_inode: !!!inode->i_lock!!!
190 statfs: maybe(read) (see below)
193 show_options: no (namespace_sem)
194 quota_read: no (see below)
195 quota_write: no (see below)
196 ====================== ============ ========================
198 ->statfs() has s_umount (shared) when called by ustat(2) (native or
199 compat), but that's an accident of bad API; s_umount is used to pin
200 the superblock down when we only have dev_t given us by userland to
201 identify the superblock. Everything else (statfs(), fstatfs(), etc.)
202 doesn't hold it when calling ->statfs() - superblock is pinned down
203 by resolving the pathname passed to syscall.
205 ->quota_read() and ->quota_write() functions are both guaranteed to
206 be the only ones operating on the quota file by the quota code (via
207 dqio_sem) (unless an admin really wants to screw up something and
208 writes to quota files with quotas on). For other details about locking
209 see also dquot_operations section.
216 struct dentry *(*mount) (struct file_system_type *, int,
217 const char *, void *);
218 void (*kill_sb) (struct super_block *);
229 ->mount() returns ERR_PTR or the root dentry; its superblock should be locked
232 ->kill_sb() takes a write-locked superblock, does all shutdown work on it,
233 unlocks and drops the reference.
235 address_space_operations
236 ========================
239 int (*writepage)(struct page *page, struct writeback_control *wbc);
240 int (*read_folio)(struct file *, struct folio *);
241 int (*writepages)(struct address_space *, struct writeback_control *);
242 bool (*dirty_folio)(struct address_space *, struct folio *folio);
243 void (*readahead)(struct readahead_control *);
244 int (*write_begin)(struct file *, struct address_space *mapping,
245 loff_t pos, unsigned len,
246 struct page **pagep, void **fsdata);
247 int (*write_end)(struct file *, struct address_space *mapping,
248 loff_t pos, unsigned len, unsigned copied,
249 struct page *page, void *fsdata);
250 sector_t (*bmap)(struct address_space *, sector_t);
251 void (*invalidate_folio) (struct folio *, size_t start, size_t len);
252 bool (*release_folio)(struct folio *, gfp_t);
253 void (*free_folio)(struct folio *);
254 int (*direct_IO)(struct kiocb *, struct iov_iter *iter);
255 bool (*isolate_page) (struct page *, isolate_mode_t);
256 int (*migratepage)(struct address_space *, struct page *, struct page *);
257 void (*putback_page) (struct page *);
258 int (*launder_folio)(struct folio *);
259 bool (*is_partially_uptodate)(struct folio *, size_t from, size_t count);
260 int (*error_remove_page)(struct address_space *, struct page *);
261 int (*swap_activate)(struct file *);
262 int (*swap_deactivate)(struct file *);
265 All except dirty_folio and free_folio may block
267 ====================== ======================== ========= ===============
268 ops folio locked i_rwsem invalidate_lock
269 ====================== ======================== ========= ===============
270 writepage: yes, unlocks (see below)
271 read_folio: yes, unlocks shared
274 readahead: yes, unlocks shared
275 write_begin: locks the page exclusive
276 write_end: yes, unlocks exclusive
278 invalidate_folio: yes exclusive
283 migratepage: yes (both)
286 is_partially_uptodate: yes
287 error_remove_page: yes
290 ====================== ======================== ========= ===============
292 ->write_begin(), ->write_end() and ->read_folio() may be called from
293 the request handler (/dev/loop).
295 ->read_folio() unlocks the folio, either synchronously or via I/O
298 ->readahead() unlocks the folios that I/O is attempted on like ->read_folio().
300 ->writepage() is used for two purposes: for "memory cleansing" and for
301 "sync". These are quite different operations and the behaviour may differ
302 depending upon the mode.
304 If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
305 it *must* start I/O against the page, even if that would involve
306 blocking on in-progress I/O.
308 If writepage is called for memory cleansing (sync_mode ==
309 WBC_SYNC_NONE) then its role is to get as much writeout underway as
310 possible. So writepage should try to avoid blocking against
311 currently-in-progress I/O.
313 If the filesystem is not called for "sync" and it determines that it
314 would need to block against in-progress I/O to be able to start new I/O
315 against the page the filesystem should redirty the page with
316 redirty_page_for_writepage(), then unlock the page and return zero.
317 This may also be done to avoid internal deadlocks, but rarely.
319 If the filesystem is called for sync then it must wait on any
320 in-progress I/O and then start new I/O.
322 The filesystem should unlock the page synchronously, before returning to the
323 caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
324 value. WRITEPAGE_ACTIVATE means that page cannot really be written out
325 currently, and VM should stop calling ->writepage() on this page for some
326 time. VM does this by moving page to the head of the active list, hence the
329 Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
330 and return zero, writepage *must* run set_page_writeback() against the page,
331 followed by unlocking it. Once set_page_writeback() has been run against the
332 page, write I/O can be submitted and the write I/O completion handler must run
333 end_page_writeback() once the I/O is complete. If no I/O is submitted, the
334 filesystem must run end_page_writeback() against the page before returning from
337 That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
338 if the filesystem needs the page to be locked during writeout, that is ok, too,
339 the page is allowed to be unlocked at any point in time between the calls to
340 set_page_writeback() and end_page_writeback().
342 Note, failure to run either redirty_page_for_writepage() or the combination of
343 set_page_writeback()/end_page_writeback() on a page submitted to writepage
344 will leave the page itself marked clean but it will be tagged as dirty in the
345 radix tree. This incoherency can lead to all sorts of hard-to-debug problems
346 in the filesystem like having dirty inodes at umount and losing written data.
348 ->writepages() is used for periodic writeback and for syscall-initiated
349 sync operations. The address_space should start I/O against at least
350 ``*nr_to_write`` pages. ``*nr_to_write`` must be decremented for each page
351 which is written. The address_space implementation may write more (or less)
352 pages than ``*nr_to_write`` asks for, but it should try to be reasonably close.
353 If nr_to_write is NULL, all dirty pages must be written.
355 writepages should _only_ write pages which are present on
358 ->dirty_folio() is called from various places in the kernel when
359 the target folio is marked as needing writeback. The folio cannot be
360 truncated because either the caller holds the folio lock, or the caller
361 has found the folio while holding the page table lock which will block
364 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
365 filesystems and by the swapper. The latter will eventually go away. Please,
366 keep it that way and don't breed new callers.
368 ->invalidate_folio() is called when the filesystem must attempt to drop
369 some or all of the buffers from the page when it is being truncated. It
370 returns zero on success. The filesystem must exclusively acquire
371 invalidate_lock before invalidating page cache in truncate / hole punch
372 path (and thus calling into ->invalidate_folio) to block races between page
373 cache invalidation and page cache filling functions (fault, read, ...).
375 ->release_folio() is called when the kernel is about to try to drop the
376 buffers from the folio in preparation for freeing it. It returns false to
377 indicate that the buffers are (or may be) freeable. If ->release_folio is
378 NULL, the kernel assumes that the fs has no private interest in the buffers.
380 ->free_folio() is called when the kernel has dropped the folio
383 ->launder_folio() may be called prior to releasing a folio if
384 it is still found to be dirty. It returns zero if the folio was successfully
385 cleaned, or an error value if not. Note that in order to prevent the folio
386 getting mapped back in and redirtied, it needs to be kept locked
387 across the entire operation.
389 ->swap_activate will be called with a non-zero argument on
390 files backing (non block device backed) swapfiles. A return value
391 of zero indicates success, in which case this file can be used for
392 backing swapspace. The swapspace operations will be proxied to the
393 address space operations.
395 ->swap_deactivate() will be called in the sys_swapoff()
396 path after ->swap_activate() returned success.
403 void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
404 void (*fl_release_private)(struct file_lock *);
409 =================== ============= =========
410 ops inode->i_lock may block
411 =================== ============= =========
413 fl_release_private: maybe maybe[1]_
414 =================== ============= =========
417 ->fl_release_private for flock or POSIX locks is currently allowed
418 to block. Leases however can still be freed while the i_lock is held and
419 so fl_release_private called on a lease should not block.
421 lock_manager_operations
422 =======================
426 void (*lm_notify)(struct file_lock *); /* unblock callback */
427 int (*lm_grant)(struct file_lock *, struct file_lock *, int);
428 void (*lm_break)(struct file_lock *); /* break_lease callback */
429 int (*lm_change)(struct file_lock **, int);
430 bool (*lm_breaker_owns_lease)(struct file_lock *);
434 ====================== ============= ================= =========
435 ops flc_lock blocked_lock_lock may block
436 ====================== ============= ================= =========
441 lm_breaker_owns_lease: yes no no
442 ====================== ============= ================= =========
449 void (*b_end_io)(struct buffer_head *bh, int uptodate);
453 called from interrupts. In other words, extreme care is needed here.
454 bh is locked, but that's all warranties we have here. Currently only RAID1,
455 highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
456 call this method upon the IO completion.
458 block_device_operations
459 =======================
462 int (*open) (struct block_device *, fmode_t);
463 int (*release) (struct gendisk *, fmode_t);
464 int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
465 int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
466 int (*direct_access) (struct block_device *, sector_t, void **,
468 void (*unlock_native_capacity) (struct gendisk *);
469 int (*getgeo)(struct block_device *, struct hd_geometry *);
470 void (*swap_slot_free_notify) (struct block_device *, unsigned long);
474 ======================= ===================
476 ======================= ===================
482 unlock_native_capacity: no
484 swap_slot_free_notify: no (see below)
485 ======================= ===================
487 swap_slot_free_notify is called with swap_lock and sometimes the page lock
496 loff_t (*llseek) (struct file *, loff_t, int);
497 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
498 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
499 ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);
500 ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);
501 int (*iopoll) (struct kiocb *kiocb, bool spin);
502 int (*iterate) (struct file *, struct dir_context *);
503 int (*iterate_shared) (struct file *, struct dir_context *);
504 __poll_t (*poll) (struct file *, struct poll_table_struct *);
505 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
506 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
507 int (*mmap) (struct file *, struct vm_area_struct *);
508 int (*open) (struct inode *, struct file *);
509 int (*flush) (struct file *);
510 int (*release) (struct inode *, struct file *);
511 int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
512 int (*fasync) (int, struct file *, int);
513 int (*lock) (struct file *, int, struct file_lock *);
514 ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
516 unsigned long (*get_unmapped_area)(struct file *, unsigned long,
517 unsigned long, unsigned long, unsigned long);
518 int (*check_flags)(int);
519 int (*flock) (struct file *, int, struct file_lock *);
520 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
521 size_t, unsigned int);
522 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
523 size_t, unsigned int);
524 int (*setlease)(struct file *, long, struct file_lock **, void **);
525 long (*fallocate)(struct file *, int, loff_t, loff_t);
526 void (*show_fdinfo)(struct seq_file *m, struct file *f);
527 unsigned (*mmap_capabilities)(struct file *);
528 ssize_t (*copy_file_range)(struct file *, loff_t, struct file *,
529 loff_t, size_t, unsigned int);
530 loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,
531 struct file *file_out, loff_t pos_out,
532 loff_t len, unsigned int remap_flags);
533 int (*fadvise)(struct file *, loff_t, loff_t, int);
538 ->llseek() locking has moved from llseek to the individual llseek
539 implementations. If your fs is not using generic_file_llseek, you
540 need to acquire and release the appropriate locks in your ->llseek().
541 For many filesystems, it is probably safe to acquire the inode
542 mutex or just to use i_size_read() instead.
543 Note: this does not protect the file->f_pos against concurrent modifications
544 since this is something the userspace has to take care about.
546 ->iterate() is called with i_rwsem exclusive.
548 ->iterate_shared() is called with i_rwsem at least shared.
550 ->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
551 Most instances call fasync_helper(), which does that maintenance, so it's
552 not normally something one needs to worry about. Return values > 0 will be
553 mapped to zero in the VFS layer.
555 ->readdir() and ->ioctl() on directories must be changed. Ideally we would
556 move ->readdir() to inode_operations and use a separate method for directory
557 ->ioctl() or kill the latter completely. One of the problems is that for
558 anything that resembles union-mount we won't have a struct file for all
559 components. And there are other reasons why the current interface is a mess...
561 ->read on directories probably must go away - we should just enforce -EISDIR
562 in sys_read() and friends.
564 ->setlease operations should call generic_setlease() before or after setting
565 the lease within the individual filesystem to record the result of the
568 ->fallocate implementation must be really careful to maintain page cache
569 consistency when punching holes or performing other operations that invalidate
570 page cache contents. Usually the filesystem needs to call
571 truncate_inode_pages_range() to invalidate relevant range of the page cache.
572 However the filesystem usually also needs to update its internal (and on disk)
573 view of file offset -> disk block mapping. Until this update is finished, the
574 filesystem needs to block page faults and reads from reloading now-stale page
575 cache contents from the disk. Since VFS acquires mapping->invalidate_lock in
576 shared mode when loading pages from disk (filemap_fault(), filemap_read(),
577 readahead paths), the fallocate implementation must take the invalidate_lock to
580 ->copy_file_range and ->remap_file_range implementations need to serialize
581 against modifications of file data while the operation is running. For
582 blocking changes through write(2) and similar operations inode->i_rwsem can be
583 used. To block changes to file contents via a memory mapping during the
584 operation, the filesystem must take mapping->invalidate_lock to coordinate
592 int (*write_dquot) (struct dquot *);
593 int (*acquire_dquot) (struct dquot *);
594 int (*release_dquot) (struct dquot *);
595 int (*mark_dirty) (struct dquot *);
596 int (*write_info) (struct super_block *, int);
598 These operations are intended to be more or less wrapping functions that ensure
599 a proper locking wrt the filesystem and call the generic quota operations.
601 What filesystem should expect from the generic quota functions:
603 ============== ============ =========================
604 ops FS recursion Held locks when called
605 ============== ============ =========================
606 write_dquot: yes dqonoff_sem or dqptr_sem
607 acquire_dquot: yes dqonoff_sem or dqptr_sem
608 release_dquot: yes dqonoff_sem or dqptr_sem
610 write_info: yes dqonoff_sem
611 ============== ============ =========================
613 FS recursion means calling ->quota_read() and ->quota_write() from superblock
616 More details about quota locking can be found in fs/dquot.c.
623 void (*open)(struct vm_area_struct*);
624 void (*close)(struct vm_area_struct*);
625 vm_fault_t (*fault)(struct vm_area_struct*, struct vm_fault *);
626 vm_fault_t (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
627 vm_fault_t (*pfn_mkwrite)(struct vm_area_struct *, struct vm_fault *);
628 int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
632 ============= ========= ===========================
633 ops mmap_lock PageLocked(page)
634 ============= ========= ===========================
637 fault: yes can return with page locked
639 page_mkwrite: yes can return with page locked
642 ============= ========= ===========================
644 ->fault() is called when a previously not present pte is about to be faulted
645 in. The filesystem must find and return the page associated with the passed in
646 "pgoff" in the vm_fault structure. If it is possible that the page may be
647 truncated and/or invalidated, then the filesystem must lock invalidate_lock,
648 then ensure the page is not already truncated (invalidate_lock will block
649 subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
650 locked. The VM will unlock the page.
652 ->map_pages() is called when VM asks to map easy accessible pages.
653 Filesystem should find and map pages associated with offsets from "start_pgoff"
654 till "end_pgoff". ->map_pages() is called with page table locked and must
655 not block. If it's not possible to reach a page without blocking,
656 filesystem should skip it. Filesystem should use do_set_pte() to setup
657 page table entry. Pointer to entry associated with the page is passed in
658 "pte" field in vm_fault structure. Pointers to entries for other offsets
659 should be calculated relative to "pte".
661 ->page_mkwrite() is called when a previously read-only pte is about to become
662 writeable. The filesystem again must ensure that there are no
663 truncate/invalidate races or races with operations such as ->remap_file_range
664 or ->copy_file_range, and then return with the page locked. Usually
665 mapping->invalidate_lock is suitable for proper serialization. If the page has
666 been truncated, the filesystem should not look up a new page like the ->fault()
667 handler, but simply return with VM_FAULT_NOPAGE, which will cause the VM to
670 ->pfn_mkwrite() is the same as page_mkwrite but when the pte is
671 VM_PFNMAP or VM_MIXEDMAP with a page-less entry. Expected return is
672 VM_FAULT_NOPAGE. Or one of the VM_FAULT_ERROR types. The default behavior
673 after this call is to make the pte read-write, unless pfn_mkwrite returns
676 ->access() is called when get_user_pages() fails in
677 access_process_vm(), typically used to debug a process through
678 /proc/pid/mem or ptrace. This function is needed only for
679 VM_IO | VM_PFNMAP VMAs.
681 --------------------------------------------------------------------------------
685 (if you break something or notice that it is broken and do not fix it yourself
686 - at least put it here)