Commit 592d8072 authored by Alexander Mikhalitsyn's avatar Alexander Mikhalitsyn Committed by Jonathan Corbet
Browse files

docs: filesystems: vfs: actualize struct super_operations description 



Added/updated descriptions for super_operations:
- free_inode method
- evict_inode method
- freeze_super/thaw_super method
- show_{devname,path,stats} procfs-related methods
- get_dquots method

Cc: Eric Biggers <ebiggers@kernel.org>
Cc: Miklos Szeredi <mszeredi@redhat.com>
Cc: Al Viro <viro@zeniv.linux.org.uk>
Cc: Christian Brauner <brauner@kernel.org>
Cc: linux-fsdevel@vger.kernel.org
Cc: linux-doc@vger.kernel.org
Signed-off-by: default avatarAlexander Mikhalitsyn <aleksandr.mikhalitsyn@canonical.com>
Reviewed-by: default avatarChristian Brauner <brauner@kernel.org>
Link: https://lore.kernel.org/r/20230313130718.253708-3-aleksandr.mikhalitsyn@canonical.com


Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 85bf9a0e

Documentation/filesystems/vfs.rst

+59 −15
Original line number Diff line number Diff line
@@ -245,33 +245,42 @@ struct super_operations 
-----------------------



This describes how the VFS can manipulate the superblock of your

filesystem.  As of kernel 2.6.22, the following members are defined:

filesystem.  The following members are defined:



.. code-block:: c



	struct super_operations {

		struct inode *(*alloc_inode)(struct super_block *sb);

		void (*destroy_inode)(struct inode *);

		void (*free_inode)(struct inode *);



		void (*dirty_inode) (struct inode *, int flags);

		int (*write_inode) (struct inode *, int);

		void (*drop_inode) (struct inode *);

		void (*delete_inode) (struct inode *);

		int (*write_inode) (struct inode *, struct writeback_control *wbc);

		int (*drop_inode) (struct inode *);

		void (*evict_inode) (struct inode *);

		void (*put_super) (struct super_block *);

		int (*sync_fs)(struct super_block *sb, int wait);

		int (*freeze_super) (struct super_block *);

		int (*freeze_fs) (struct super_block *);

		int (*thaw_super) (struct super_block *);

		int (*unfreeze_fs) (struct super_block *);

		int (*statfs) (struct dentry *, struct kstatfs *);

		int (*remount_fs) (struct super_block *, int *, char *);

		void (*clear_inode) (struct inode *);

		void (*umount_begin) (struct super_block *);



		int (*show_options)(struct seq_file *, struct dentry *);

		int (*show_devname)(struct seq_file *, struct dentry *);

		int (*show_path)(struct seq_file *, struct dentry *);

		int (*show_stats)(struct seq_file *, struct dentry *);



		ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);

		ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);

		int (*nr_cached_objects)(struct super_block *);

		void (*free_cached_objects)(struct super_block *, int);

		struct dquot **(*get_dquots)(struct inode *);



		long (*nr_cached_objects)(struct super_block *,

					struct shrink_control *);

		long (*free_cached_objects)(struct super_block *,

					struct shrink_control *);

	};



All methods are called without any locks being held, unless otherwise
@@ -292,6 +301,11 @@ or bottom half). 
	->alloc_inode was defined and simply undoes anything done by

	->alloc_inode.



``free_inode``

	this method is called from RCU callback. If you use call_rcu()

	in ->destroy_inode to free 'struct inode' memory, then it's

	better to release memory in this method.



``dirty_inode``

	this method is called by the VFS when an inode is marked dirty.

	This is specifically for the inode itself being marked dirty,
@@ -319,8 +333,12 @@ or bottom half). 
	practice of using "force_delete" in the put_inode() case, but

	does not have the races that the "force_delete()" approach had.



``delete_inode``

	called when the VFS wants to delete an inode

``evict_inode``

	called when the VFS wants to evict an inode. Caller does

	*not* evict the pagecache or inode-associated metadata buffers;

	the method has to use truncate_inode_pages_final() to get rid

	of those. Caller makes sure async writeback cannot be running for

	the inode while (or after) ->evict_inode() is called. Optional.



``put_super``

	called when the VFS wishes to free the superblock
@@ -331,14 +349,25 @@ or bottom half). 
	superblock.  The second parameter indicates whether the method

	should wait until the write out has been completed.  Optional.



``freeze_super``

	Called instead of ->freeze_fs callback if provided.

	Main difference is that ->freeze_super is called without taking

	down_write(&sb->s_umount). If filesystem implements it and wants

	->freeze_fs to be called too, then it has to call ->freeze_fs

	explicitly from this callback. Optional.



``freeze_fs``

	called when VFS is locking a filesystem and forcing it into a

	consistent state.  This method is currently used by the Logical

	Volume Manager (LVM).

	Volume Manager (LVM) and ioctl(FIFREEZE). Optional.



``thaw_super``

	called when VFS is unlocking a filesystem and making it writable

	again after ->freeze_super. Optional.



``unfreeze_fs``

	called when VFS is unlocking a filesystem and making it writable

	again.

	again after ->freeze_fs. Optional.



``statfs``

	called when the VFS needs to get filesystem statistics.
@@ -347,22 +376,37 @@ or bottom half). 
	called when the filesystem is remounted.  This is called with

	the kernel lock held



``clear_inode``

	called then the VFS clears the inode.  Optional



``umount_begin``

	called when the VFS is unmounting a filesystem.



``show_options``

	called by the VFS to show mount options for /proc/<pid>/mounts.

	called by the VFS to show mount options for /proc/<pid>/mounts

	and /proc/<pid>/mountinfo.

	(see "Mount Options" section)



``show_devname``

	Optional. Called by the VFS to show device name for

	/proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then

	'(struct mount).mnt_devname' will be used.



``show_path``

	Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show

	the mount root dentry path relative to the filesystem root.



``show_stats``

	Optional. Called by the VFS (for /proc/<pid>/mountstats) to show

	filesystem-specific mount statistics.



``quota_read``

	called by the VFS to read from filesystem quota file.



``quota_write``

	called by the VFS to write to filesystem quota file.



``get_dquots``

	called by quota to get 'struct dquot' array for a particular inode.

	Optional.



``nr_cached_objects``

	called by the sb cache shrinking function for the filesystem to

	return the number of freeable cached objects it contains.