blob: d5a269a51a9efe1909c51b78c7e8207af2af3dc3 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 The text below describes the locking rules for VFS-related methods.
2It is (believed to be) up-to-date. *Please*, if you change anything in
3prototypes or locking protocols - update this file. And update the relevant
4instances in the tree, don't leave that to maintainers of filesystems/devices/
5etc. At the very least, put the list of dubious cases in the end of this file.
6Don't turn it into log - maintainers of out-of-the-tree code are supposed to
7be able to use diff(1).
8 Thing currently missing here: socket operations. Alexey?
9
10--------------------------- dentry_operations --------------------------
11prototypes:
Nick Piggin34286d62011-01-07 17:49:57 +110012 int (*d_revalidate)(struct dentry *, struct nameidata *);
Nick Pigginb1e6a012011-01-07 17:49:28 +110013 int (*d_hash)(const struct dentry *, const struct inode *,
14 struct qstr *);
Nick Piggin621e1552011-01-07 17:49:27 +110015 int (*d_compare)(const struct dentry *, const struct inode *,
16 const struct dentry *, const struct inode *,
17 unsigned int, const char *, const struct qstr *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070018 int (*d_delete)(struct dentry *);
19 void (*d_release)(struct dentry *);
20 void (*d_iput)(struct dentry *, struct inode *);
Eric Dumazetc23fbb62007-05-08 00:26:18 -070021 char *(*d_dname)((struct dentry *dentry, char *buffer, int buflen);
David Howells9875cf82011-01-14 18:45:21 +000022 struct vfsmount *(*d_automount)(struct path *path);
David Howellscc53ce52011-01-14 18:45:26 +000023 int (*d_manage)(struct dentry *, bool);
Linus Torvalds1da177e2005-04-16 15:20:36 -070024
25locking rules:
Nick Piggin34286d62011-01-07 17:49:57 +110026 rename_lock ->d_lock may block rcu-walk
27d_revalidate: no no yes (ref-walk) maybe
28d_hash no no no maybe
29d_compare: yes no no maybe
30d_delete: no yes no no
31d_release: no no yes no
Sage Weilf0023bc2011-10-28 10:02:42 -070032d_prune: no yes no no
Nick Piggin34286d62011-01-07 17:49:57 +110033d_iput: no no yes no
34d_dname: no no no no
David Howells9875cf82011-01-14 18:45:21 +000035d_automount: no no yes no
David Howellsab909112011-01-14 18:46:51 +000036d_manage: no no yes (ref-walk) maybe
Linus Torvalds1da177e2005-04-16 15:20:36 -070037
38--------------------------- inode_operations ---------------------------
39prototypes:
Al Viro4acdaf22011-07-26 01:42:34 -040040 int (*create) (struct inode *,struct dentry *,umode_t, struct nameidata *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070041 struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameid
42ata *);
43 int (*link) (struct dentry *,struct inode *,struct dentry *);
44 int (*unlink) (struct inode *,struct dentry *);
45 int (*symlink) (struct inode *,struct dentry *,const char *);
Al Viro18bb1db2011-07-26 01:41:39 -040046 int (*mkdir) (struct inode *,struct dentry *,umode_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -070047 int (*rmdir) (struct inode *,struct dentry *);
Al Viro1a67aaf2011-07-26 01:52:52 -040048 int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -070049 int (*rename) (struct inode *, struct dentry *,
50 struct inode *, struct dentry *);
51 int (*readlink) (struct dentry *, char __user *,int);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010052 void * (*follow_link) (struct dentry *, struct nameidata *);
53 void (*put_link) (struct dentry *, struct nameidata *, void *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070054 void (*truncate) (struct inode *);
Nick Pigginb74c79e2011-01-07 17:49:58 +110055 int (*permission) (struct inode *, int, unsigned int);
Christoph Hellwig4e34e712011-07-23 17:37:31 +020056 int (*get_acl)(struct inode *, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -070057 int (*setattr) (struct dentry *, struct iattr *);
58 int (*getattr) (struct vfsmount *, struct dentry *, struct kstat *);
59 int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
60 ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
61 ssize_t (*listxattr) (struct dentry *, char *, size_t);
62 int (*removexattr) (struct dentry *, const char *);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010063 void (*truncate_range)(struct inode *, loff_t, loff_t);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010064 int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
Josef Bacikc3b2da32012-03-26 09:59:21 -040065 void (*update_time)(struct inode *, struct timespec *, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
67locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010068 all may block
Artem Bityutskiya7bc02f2007-05-09 07:53:16 +020069 i_mutex(inode)
Linus Torvalds1da177e2005-04-16 15:20:36 -070070lookup: yes
71create: yes
72link: yes (both)
73mknod: yes
74symlink: yes
75mkdir: yes
76unlink: yes (both)
77rmdir: yes (both) (see below)
78rename: yes (all) (see below)
79readlink: no
80follow_link: no
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010081put_link: no
Linus Torvalds1da177e2005-04-16 15:20:36 -070082truncate: yes (see below)
83setattr: yes
Nick Pigginb74c79e2011-01-07 17:49:58 +110084permission: no (may not block if called in rcu-walk mode)
Christoph Hellwig4e34e712011-07-23 17:37:31 +020085get_acl: no
Linus Torvalds1da177e2005-04-16 15:20:36 -070086getattr: no
87setxattr: yes
88getxattr: no
89listxattr: no
90removexattr: yes
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010091truncate_range: yes
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010092fiemap: no
Josef Bacikc3b2da32012-03-26 09:59:21 -040093update_time: no
94
Artem Bityutskiya7bc02f2007-05-09 07:53:16 +020095 Additionally, ->rmdir(), ->unlink() and ->rename() have ->i_mutex on
Linus Torvalds1da177e2005-04-16 15:20:36 -070096victim.
97 cross-directory ->rename() has (per-superblock) ->s_vfs_rename_sem.
98 ->truncate() is never called directly - it's a callback, not a
Christoph Hellwigb83be6f2010-12-16 12:04:54 +010099method. It's called by vmtruncate() - deprecated library function used by
Linus Torvalds1da177e2005-04-16 15:20:36 -0700100->setattr(). Locking information above applies to that call (i.e. is
101inherited from ->setattr() - vmtruncate() is used when ATTR_SIZE had been
102passed).
103
104See Documentation/filesystems/directory-locking for more detailed discussion
105of the locking scheme for directory operations.
106
107--------------------------- super_operations ---------------------------
108prototypes:
109 struct inode *(*alloc_inode)(struct super_block *sb);
110 void (*destroy_inode)(struct inode *);
Christoph Hellwigaa385722011-05-27 06:53:02 -0400111 void (*dirty_inode) (struct inode *, int flags);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100112 int (*write_inode) (struct inode *, struct writeback_control *wbc);
Al Viro336fb3b2010-06-08 00:37:12 -0400113 int (*drop_inode) (struct inode *);
114 void (*evict_inode) (struct inode *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115 void (*put_super) (struct super_block *);
116 void (*write_super) (struct super_block *);
117 int (*sync_fs)(struct super_block *sb, int wait);
Takashi Satoc4be0c12009-01-09 16:40:58 -0800118 int (*freeze_fs) (struct super_block *);
119 int (*unfreeze_fs) (struct super_block *);
David Howells726c3342006-06-23 02:02:58 -0700120 int (*statfs) (struct dentry *, struct kstatfs *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700121 int (*remount_fs) (struct super_block *, int *, char *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700122 void (*umount_begin) (struct super_block *);
Al Viro34c80b12011-12-08 21:32:45 -0500123 int (*show_options)(struct seq_file *, struct dentry *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700124 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
125 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100126 int (*bdev_try_to_free_page)(struct super_block*, struct page*, gfp_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700127
128locking rules:
Al Viro336fb3b2010-06-08 00:37:12 -0400129 All may block [not true, see below]
Christoph Hellwig7e325d32009-06-19 20:22:37 +0200130 s_umount
131alloc_inode:
132destroy_inode:
Christoph Hellwigaa385722011-05-27 06:53:02 -0400133dirty_inode:
Christoph Hellwig7e325d32009-06-19 20:22:37 +0200134write_inode:
Dave Chinnerf283c862011-03-22 22:23:39 +1100135drop_inode: !!!inode->i_lock!!!
Al Viro336fb3b2010-06-08 00:37:12 -0400136evict_inode:
Christoph Hellwig7e325d32009-06-19 20:22:37 +0200137put_super: write
138write_super: read
139sync_fs: read
140freeze_fs: read
141unfreeze_fs: read
Al Viro336fb3b2010-06-08 00:37:12 -0400142statfs: maybe(read) (see below)
143remount_fs: write
Christoph Hellwig7e325d32009-06-19 20:22:37 +0200144umount_begin: no
145show_options: no (namespace_sem)
146quota_read: no (see below)
147quota_write: no (see below)
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100148bdev_try_to_free_page: no (see below)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700149
Al Viro336fb3b2010-06-08 00:37:12 -0400150->statfs() has s_umount (shared) when called by ustat(2) (native or
151compat), but that's an accident of bad API; s_umount is used to pin
152the superblock down when we only have dev_t given us by userland to
153identify the superblock. Everything else (statfs(), fstatfs(), etc.)
154doesn't hold it when calling ->statfs() - superblock is pinned down
155by resolving the pathname passed to syscall.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700156->quota_read() and ->quota_write() functions are both guaranteed to
157be the only ones operating on the quota file by the quota code (via
158dqio_sem) (unless an admin really wants to screw up something and
159writes to quota files with quotas on). For other details about locking
160see also dquot_operations section.
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100161->bdev_try_to_free_page is called from the ->releasepage handler of
162the block device inode. See there for more details.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700163
164--------------------------- file_system_type ---------------------------
165prototypes:
Jonathan Corbet5d8b2eb2006-07-10 04:44:07 -0700166 int (*get_sb) (struct file_system_type *, int,
167 const char *, void *, struct vfsmount *);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100168 struct dentry *(*mount) (struct file_system_type *, int,
169 const char *, void *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170 void (*kill_sb) (struct super_block *);
171locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100172 may block
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100173mount yes
174kill_sb yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700175
Al Viro1a102ff2011-03-16 09:07:58 -0400176->mount() returns ERR_PTR or the root dentry; its superblock should be locked
177on return.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700178->kill_sb() takes a write-locked superblock, does all shutdown work on it,
179unlocks and drops the reference.
180
181--------------------------- address_space_operations --------------------------
182prototypes:
183 int (*writepage)(struct page *page, struct writeback_control *wbc);
184 int (*readpage)(struct file *, struct page *);
185 int (*sync_page)(struct page *);
186 int (*writepages)(struct address_space *, struct writeback_control *);
187 int (*set_page_dirty)(struct page *page);
188 int (*readpages)(struct file *filp, struct address_space *mapping,
189 struct list_head *pages, unsigned nr_pages);
Nick Piggin4e02ed42008-10-29 14:00:55 -0700190 int (*write_begin)(struct file *, struct address_space *mapping,
191 loff_t pos, unsigned len, unsigned flags,
192 struct page **pagep, void **fsdata);
193 int (*write_end)(struct file *, struct address_space *mapping,
194 loff_t pos, unsigned len, unsigned copied,
195 struct page *page, void *fsdata);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700196 sector_t (*bmap)(struct address_space *, sector_t);
197 int (*invalidatepage) (struct page *, unsigned long);
198 int (*releasepage) (struct page *, int);
Linus Torvalds6072d132010-12-01 13:35:19 -0500199 void (*freepage)(struct page *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700200 int (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
201 loff_t offset, unsigned long nr_segs);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100202 int (*get_xip_mem)(struct address_space *, pgoff_t, int, void **,
203 unsigned long *);
204 int (*migratepage)(struct address_space *, struct page *, struct page *);
205 int (*launder_page)(struct page *);
206 int (*is_partially_uptodate)(struct page *, read_descriptor_t *, unsigned long);
207 int (*error_remove_page)(struct address_space *, struct page *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700208
209locking rules:
Linus Torvalds6072d132010-12-01 13:35:19 -0500210 All except set_page_dirty and freepage may block
Linus Torvalds1da177e2005-04-16 15:20:36 -0700211
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100212 PageLocked(page) i_mutex
213writepage: yes, unlocks (see below)
214readpage: yes, unlocks
215sync_page: maybe
216writepages:
217set_page_dirty no
218readpages:
219write_begin: locks the page yes
220write_end: yes, unlocks yes
221bmap:
222invalidatepage: yes
223releasepage: yes
224freepage: yes
225direct_IO:
226get_xip_mem: maybe
227migratepage: yes (both)
228launder_page: yes
229is_partially_uptodate: yes
230error_remove_page: yes
Linus Torvalds1da177e2005-04-16 15:20:36 -0700231
Nick Piggin4e02ed42008-10-29 14:00:55 -0700232 ->write_begin(), ->write_end(), ->sync_page() and ->readpage()
Linus Torvalds1da177e2005-04-16 15:20:36 -0700233may be called from the request handler (/dev/loop).
234
235 ->readpage() unlocks the page, either synchronously or via I/O
236completion.
237
238 ->readpages() populates the pagecache with the passed pages and starts
239I/O against them. They come unlocked upon I/O completion.
240
241 ->writepage() is used for two purposes: for "memory cleansing" and for
242"sync". These are quite different operations and the behaviour may differ
243depending upon the mode.
244
245If writepage is called for sync (wbc->sync_mode != WBC_SYNC_NONE) then
246it *must* start I/O against the page, even if that would involve
247blocking on in-progress I/O.
248
249If writepage is called for memory cleansing (sync_mode ==
250WBC_SYNC_NONE) then its role is to get as much writeout underway as
251possible. So writepage should try to avoid blocking against
252currently-in-progress I/O.
253
254If the filesystem is not called for "sync" and it determines that it
255would need to block against in-progress I/O to be able to start new I/O
256against the page the filesystem should redirty the page with
257redirty_page_for_writepage(), then unlock the page and return zero.
258This may also be done to avoid internal deadlocks, but rarely.
259
Robert P. J. Day3a4fa0a2007-10-19 23:10:43 +0200260If the filesystem is called for sync then it must wait on any
Linus Torvalds1da177e2005-04-16 15:20:36 -0700261in-progress I/O and then start new I/O.
262
Nikita Danilov20546062005-05-01 08:58:37 -0700263The filesystem should unlock the page synchronously, before returning to the
264caller, unless ->writepage() returns special WRITEPAGE_ACTIVATE
265value. WRITEPAGE_ACTIVATE means that page cannot really be written out
266currently, and VM should stop calling ->writepage() on this page for some
267time. VM does this by moving page to the head of the active list, hence the
268name.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269
270Unless the filesystem is going to redirty_page_for_writepage(), unlock the page
271and return zero, writepage *must* run set_page_writeback() against the page,
272followed by unlocking it. Once set_page_writeback() has been run against the
273page, write I/O can be submitted and the write I/O completion handler must run
274end_page_writeback() once the I/O is complete. If no I/O is submitted, the
275filesystem must run end_page_writeback() against the page before returning from
276writepage.
277
278That is: after 2.5.12, pages which are under writeout are *not* locked. Note,
279if the filesystem needs the page to be locked during writeout, that is ok, too,
280the page is allowed to be unlocked at any point in time between the calls to
281set_page_writeback() and end_page_writeback().
282
283Note, failure to run either redirty_page_for_writepage() or the combination of
284set_page_writeback()/end_page_writeback() on a page submitted to writepage
285will leave the page itself marked clean but it will be tagged as dirty in the
286radix tree. This incoherency can lead to all sorts of hard-to-debug problems
287in the filesystem like having dirty inodes at umount and losing written data.
288
289 ->sync_page() locking rules are not well-defined - usually it is called
290with lock on page, but that is not guaranteed. Considering the currently
291existing instances of this method ->sync_page() itself doesn't look
292well-defined...
293
294 ->writepages() is used for periodic writeback and for syscall-initiated
295sync operations. The address_space should start I/O against at least
296*nr_to_write pages. *nr_to_write must be decremented for each page which is
297written. The address_space implementation may write more (or less) pages
298than *nr_to_write asks for, but it should try to be reasonably close. If
299nr_to_write is NULL, all dirty pages must be written.
300
301writepages should _only_ write pages which are present on
302mapping->io_pages.
303
304 ->set_page_dirty() is called from various places in the kernel
305when the target page is marked as needing writeback. It may be called
306under spinlock (it cannot block) and is sometimes called with the page
307not locked.
308
309 ->bmap() is currently used by legacy ioctl() (FIBMAP) provided by some
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100310filesystems and by the swapper. The latter will eventually go away. Please,
311keep it that way and don't breed new callers.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700312
313 ->invalidatepage() is called when the filesystem must attempt to drop
314some or all of the buffers from the page when it is being truncated. It
315returns zero on success. If ->invalidatepage is zero, the kernel uses
316block_invalidatepage() instead.
317
318 ->releasepage() is called when the kernel is about to try to drop the
319buffers from the page in preparation for freeing it. It returns zero to
320indicate that the buffers are (or may be) freeable. If ->releasepage is zero,
321the kernel assumes that the fs has no private interest in the buffers.
322
Linus Torvalds6072d132010-12-01 13:35:19 -0500323 ->freepage() is called when the kernel is done dropping the page
324from the page cache.
325
Trond Myklebuste3db7692007-01-10 23:15:39 -0800326 ->launder_page() may be called prior to releasing a page if
327it is still found to be dirty. It returns zero if the page was successfully
328cleaned, or an error value if not. Note that in order to prevent the page
329getting mapped back in and redirtied, it needs to be kept locked
330across the entire operation.
331
Linus Torvalds1da177e2005-04-16 15:20:36 -0700332----------------------- file_lock_operations ------------------------------
333prototypes:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700334 void (*fl_copy_lock)(struct file_lock *, struct file_lock *);
335 void (*fl_release_private)(struct file_lock *);
336
337
338locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100339 file_lock_lock may block
340fl_copy_lock: yes no
341fl_release_private: maybe no
Linus Torvalds1da177e2005-04-16 15:20:36 -0700342
343----------------------- lock_manager_operations ---------------------------
344prototypes:
J. Bruce Fields8fb47a42011-07-20 20:21:59 -0400345 int (*lm_compare_owner)(struct file_lock *, struct file_lock *);
346 void (*lm_notify)(struct file_lock *); /* unblock callback */
347 int (*lm_grant)(struct file_lock *, struct file_lock *, int);
348 void (*lm_release_private)(struct file_lock *);
349 void (*lm_break)(struct file_lock *); /* break_lease callback */
350 int (*lm_change)(struct file_lock **, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700351
352locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100353 file_lock_lock may block
J. Bruce Fields8fb47a42011-07-20 20:21:59 -0400354lm_compare_owner: yes no
355lm_notify: yes no
356lm_grant: no no
357lm_release_private: maybe no
358lm_break: yes no
359lm_change yes no
Linus Torvalds1da177e2005-04-16 15:20:36 -0700360
Linus Torvalds1da177e2005-04-16 15:20:36 -0700361--------------------------- buffer_head -----------------------------------
362prototypes:
363 void (*b_end_io)(struct buffer_head *bh, int uptodate);
364
365locking rules:
366 called from interrupts. In other words, extreme care is needed here.
367bh is locked, but that's all warranties we have here. Currently only RAID1,
368highmem, fs/buffer.c, and fs/ntfs/aops.c are providing these. Block devices
369call this method upon the IO completion.
370
371--------------------------- block_device_operations -----------------------
372prototypes:
Christoph Hellwige1455d12010-10-06 10:46:53 +0200373 int (*open) (struct block_device *, fmode_t);
374 int (*release) (struct gendisk *, fmode_t);
375 int (*ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
376 int (*compat_ioctl) (struct block_device *, fmode_t, unsigned, unsigned long);
377 int (*direct_access) (struct block_device *, sector_t, void **, unsigned long *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700378 int (*media_changed) (struct gendisk *);
Christoph Hellwige1455d12010-10-06 10:46:53 +0200379 void (*unlock_native_capacity) (struct gendisk *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700380 int (*revalidate_disk) (struct gendisk *);
Christoph Hellwige1455d12010-10-06 10:46:53 +0200381 int (*getgeo)(struct block_device *, struct hd_geometry *);
382 void (*swap_slot_free_notify) (struct block_device *, unsigned long);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700383
384locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100385 bd_mutex
386open: yes
387release: yes
388ioctl: no
389compat_ioctl: no
390direct_access: no
391media_changed: no
392unlock_native_capacity: no
393revalidate_disk: no
394getgeo: no
395swap_slot_free_notify: no (see below)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700396
Christoph Hellwige1455d12010-10-06 10:46:53 +0200397media_changed, unlock_native_capacity and revalidate_disk are called only from
398check_disk_change().
399
400swap_slot_free_notify is called with swap_lock and sometimes the page lock
401held.
402
Linus Torvalds1da177e2005-04-16 15:20:36 -0700403
404--------------------------- file_operations -------------------------------
405prototypes:
406 loff_t (*llseek) (struct file *, loff_t, int);
407 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700408 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
Badari Pulavarty027445c2006-09-30 23:28:46 -0700409 ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
410 ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700411 int (*readdir) (struct file *, void *, filldir_t);
412 unsigned int (*poll) (struct file *, struct poll_table_struct *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700413 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
414 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
415 int (*mmap) (struct file *, struct vm_area_struct *);
416 int (*open) (struct inode *, struct file *);
417 int (*flush) (struct file *);
418 int (*release) (struct inode *, struct file *);
Josef Bacik02c24a82011-07-16 20:44:56 -0400419 int (*fsync) (struct file *, loff_t start, loff_t end, int datasync);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700420 int (*aio_fsync) (struct kiocb *, int datasync);
421 int (*fasync) (int, struct file *, int);
422 int (*lock) (struct file *, int, struct file_lock *);
423 ssize_t (*readv) (struct file *, const struct iovec *, unsigned long,
424 loff_t *);
425 ssize_t (*writev) (struct file *, const struct iovec *, unsigned long,
426 loff_t *);
427 ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t,
428 void __user *);
429 ssize_t (*sendpage) (struct file *, struct page *, int, size_t,
430 loff_t *, int);
431 unsigned long (*get_unmapped_area)(struct file *, unsigned long,
432 unsigned long, unsigned long, unsigned long);
433 int (*check_flags)(int);
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100434 int (*flock) (struct file *, int, struct file_lock *);
435 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *,
436 size_t, unsigned int);
437 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *,
438 size_t, unsigned int);
439 int (*setlease)(struct file *, long, struct file_lock **);
Christoph Hellwig2fe17c12011-01-14 13:07:43 +0100440 long (*fallocate)(struct file *, int, loff_t, loff_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700441};
442
443locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100444 All may block except for ->setlease.
Josef Bacik02c24a82011-07-16 20:44:56 -0400445 No VFS locks held on entry except for ->setlease.
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100446
447->setlease has the file_list_lock held and must not sleep.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700448
449->llseek() locking has moved from llseek to the individual llseek
450implementations. If your fs is not using generic_file_llseek, you
451need to acquire and release the appropriate locks in your ->llseek().
452For many filesystems, it is probably safe to acquire the inode
Jan Blunck866707f2010-05-26 14:44:54 -0700453mutex or just to use i_size_read() instead.
454Note: this does not protect the file->f_pos against concurrent modifications
455since this is something the userspace has to take care about.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700456
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100457->fasync() is responsible for maintaining the FASYNC bit in filp->f_flags.
458Most instances call fasync_helper(), which does that maintenance, so it's
459not normally something one needs to worry about. Return values > 0 will be
460mapped to zero in the VFS layer.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700461
462->readdir() and ->ioctl() on directories must be changed. Ideally we would
463move ->readdir() to inode_operations and use a separate method for directory
464->ioctl() or kill the latter completely. One of the problems is that for
465anything that resembles union-mount we won't have a struct file for all
466components. And there are other reasons why the current interface is a mess...
467
Linus Torvalds1da177e2005-04-16 15:20:36 -0700468->read on directories probably must go away - we should just enforce -EISDIR
469in sys_read() and friends.
470
Linus Torvalds1da177e2005-04-16 15:20:36 -0700471--------------------------- dquot_operations -------------------------------
472prototypes:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700473 int (*write_dquot) (struct dquot *);
474 int (*acquire_dquot) (struct dquot *);
475 int (*release_dquot) (struct dquot *);
476 int (*mark_dirty) (struct dquot *);
477 int (*write_info) (struct super_block *, int);
478
479These operations are intended to be more or less wrapping functions that ensure
480a proper locking wrt the filesystem and call the generic quota operations.
481
482What filesystem should expect from the generic quota functions:
483
484 FS recursion Held locks when called
Linus Torvalds1da177e2005-04-16 15:20:36 -0700485write_dquot: yes dqonoff_sem or dqptr_sem
486acquire_dquot: yes dqonoff_sem or dqptr_sem
487release_dquot: yes dqonoff_sem or dqptr_sem
488mark_dirty: no -
489write_info: yes dqonoff_sem
490
491FS recursion means calling ->quota_read() and ->quota_write() from superblock
492operations.
493
Linus Torvalds1da177e2005-04-16 15:20:36 -0700494More details about quota locking can be found in fs/dquot.c.
495
496--------------------------- vm_operations_struct -----------------------------
497prototypes:
498 void (*open)(struct vm_area_struct*);
499 void (*close)(struct vm_area_struct*);
Nick Piggind0217ac2007-07-19 01:47:03 -0700500 int (*fault)(struct vm_area_struct*, struct vm_fault *);
Nick Pigginc2ec1752009-03-31 15:23:21 -0700501 int (*page_mkwrite)(struct vm_area_struct *, struct vm_fault *);
Rik van Riel28b2ee22008-07-23 21:27:05 -0700502 int (*access)(struct vm_area_struct *, unsigned long, void*, int, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700503
504locking rules:
Christoph Hellwigb83be6f2010-12-16 12:04:54 +0100505 mmap_sem PageLocked(page)
506open: yes
507close: yes
508fault: yes can return with page locked
509page_mkwrite: yes can return with page locked
510access: yes
Mark Fashehed2f2f92007-07-19 01:47:01 -0700511
Nick Pigginb827e492009-04-30 15:08:16 -0700512 ->fault() is called when a previously not present pte is about
513to be faulted in. The filesystem must find and return the page associated
514with the passed in "pgoff" in the vm_fault structure. If it is possible that
515the page may be truncated and/or invalidated, then the filesystem must lock
516the page, then ensure it is not already truncated (the page lock will block
517subsequent truncate), and then return with VM_FAULT_LOCKED, and the page
518locked. The VM will unlock the page.
519
520 ->page_mkwrite() is called when a previously read-only pte is
521about to become writeable. The filesystem again must ensure that there are
522no truncate/invalidate races, and then return with the page locked. If
523the page has been truncated, the filesystem should not look up a new page
524like the ->fault() handler, but simply return with VM_FAULT_NOPAGE, which
525will cause the VM to retry the fault.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700526
Rik van Riel28b2ee22008-07-23 21:27:05 -0700527 ->access() is called when get_user_pages() fails in
528acces_process_vm(), typically used to debug a process through
529/proc/pid/mem or ptrace. This function is needed only for
530VM_IO | VM_PFNMAP VMAs.
531
Linus Torvalds1da177e2005-04-16 15:20:36 -0700532================================================================================
533 Dubious stuff
534
535(if you break something or notice that it is broken and do not fix it yourself
536- at least put it here)