1542 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3=========================================4Overview of the Linux Virtual File System5=========================================6 7Original author: Richard Gooch <rgooch@atnf.csiro.au>8 9- Copyright (C) 1999 Richard Gooch10- Copyright (C) 2005 Pekka Enberg11 12 13Introduction14============15 16The Virtual File System (also known as the Virtual Filesystem Switch) is17the software layer in the kernel that provides the filesystem interface18to userspace programs. It also provides an abstraction within the19kernel which allows different filesystem implementations to coexist.20 21VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on22are called from a process context. Filesystem locking is described in23the document Documentation/filesystems/locking.rst.24 25 26Directory Entry Cache (dcache)27------------------------------28 29The VFS implements the open(2), stat(2), chmod(2), and similar system30calls. The pathname argument that is passed to them is used by the VFS31to search through the directory entry cache (also known as the dentry32cache or dcache). This provides a very fast look-up mechanism to33translate a pathname (filename) into a specific dentry. Dentries live34in RAM and are never saved to disc: they exist only for performance.35 36The dentry cache is meant to be a view into your entire filespace. As37most computers cannot fit all dentries in the RAM at the same time, some38bits of the cache are missing. In order to resolve your pathname into a39dentry, the VFS may have to resort to creating dentries along the way,40and then loading the inode. This is done by looking up the inode.41 42 43The Inode Object44----------------45 46An individual dentry usually has a pointer to an inode. Inodes are47filesystem objects such as regular files, directories, FIFOs and other48beasts. They live either on the disc (for block device filesystems) or49in the memory (for pseudo filesystems). Inodes that live on the disc50are copied into the memory when required and changes to the inode are51written back to disc. A single inode can be pointed to by multiple52dentries (hard links, for example, do this).53 54To look up an inode requires that the VFS calls the lookup() method of55the parent directory inode. This method is installed by the specific56filesystem implementation that the inode lives in. Once the VFS has the57required dentry (and hence the inode), we can do all those boring things58like open(2) the file, or stat(2) it to peek at the inode data. The59stat(2) operation is fairly simple: once the VFS has the dentry, it60peeks at the inode data and passes some of it back to userspace.61 62 63The File Object64---------------65 66Opening a file requires another operation: allocation of a file67structure (this is the kernel-side implementation of file descriptors).68The freshly allocated file structure is initialized with a pointer to69the dentry and a set of file operation member functions. These are70taken from the inode data. The open() file method is then called so the71specific filesystem implementation can do its work. You can see that72this is another switch performed by the VFS. The file structure is73placed into the file descriptor table for the process.74 75Reading, writing and closing files (and other assorted VFS operations)76is done by using the userspace file descriptor to grab the appropriate77file structure, and then calling the required file structure method to78do whatever is required. For as long as the file is open, it keeps the79dentry in use, which in turn means that the VFS inode is still in use.80 81 82Registering and Mounting a Filesystem83=====================================84 85To register and unregister a filesystem, use the following API86functions:87 88.. code-block:: c89 90 #include <linux/fs.h>91 92 extern int register_filesystem(struct file_system_type *);93 extern int unregister_filesystem(struct file_system_type *);94 95The passed struct file_system_type describes your filesystem. When a96request is made to mount a filesystem onto a directory in your97namespace, the VFS will call the appropriate mount() method for the98specific filesystem. New vfsmount referring to the tree returned by99->mount() will be attached to the mountpoint, so that when pathname100resolution reaches the mountpoint it will jump into the root of that101vfsmount.102 103You can see all filesystems that are registered to the kernel in the104file /proc/filesystems.105 106 107struct file_system_type108-----------------------109 110This describes the filesystem. The following111members are defined:112 113.. code-block:: c114 115 struct file_system_type {116 const char *name;117 int fs_flags;118 int (*init_fs_context)(struct fs_context *);119 const struct fs_parameter_spec *parameters;120 struct dentry *(*mount) (struct file_system_type *, int,121 const char *, void *);122 void (*kill_sb) (struct super_block *);123 struct module *owner;124 struct file_system_type * next;125 struct hlist_head fs_supers;126 127 struct lock_class_key s_lock_key;128 struct lock_class_key s_umount_key;129 struct lock_class_key s_vfs_rename_key;130 struct lock_class_key s_writers_key[SB_FREEZE_LEVELS];131 132 struct lock_class_key i_lock_key;133 struct lock_class_key i_mutex_key;134 struct lock_class_key invalidate_lock_key;135 struct lock_class_key i_mutex_dir_key;136 };137 138``name``139 the name of the filesystem type, such as "ext2", "iso9660",140 "msdos" and so on141 142``fs_flags``143 various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.)144 145``init_fs_context``146 Initializes 'struct fs_context' ->ops and ->fs_private fields with147 filesystem-specific data.148 149``parameters``150 Pointer to the array of filesystem parameters descriptors151 'struct fs_parameter_spec'.152 More info in Documentation/filesystems/mount_api.rst.153 154``mount``155 the method to call when a new instance of this filesystem should156 be mounted157 158``kill_sb``159 the method to call when an instance of this filesystem should be160 shut down161 162 163``owner``164 for internal VFS use: you should initialize this to THIS_MODULE165 in most cases.166 167``next``168 for internal VFS use: you should initialize this to NULL169 170``fs_supers``171 for internal VFS use: hlist of filesystem instances (superblocks)172 173 s_lock_key, s_umount_key, s_vfs_rename_key, s_writers_key,174 i_lock_key, i_mutex_key, invalidate_lock_key, i_mutex_dir_key: lockdep-specific175 176The mount() method has the following arguments:177 178``struct file_system_type *fs_type``179 describes the filesystem, partly initialized by the specific180 filesystem code181 182``int flags``183 mount flags184 185``const char *dev_name``186 the device name we are mounting.187 188``void *data``189 arbitrary mount options, usually comes as an ASCII string (see190 "Mount Options" section)191 192The mount() method must return the root dentry of the tree requested by193caller. An active reference to its superblock must be grabbed and the194superblock must be locked. On failure it should return ERR_PTR(error).195 196The arguments match those of mount(2) and their interpretation depends197on filesystem type. E.g. for block filesystems, dev_name is interpreted198as block device name, that device is opened and if it contains a199suitable filesystem image the method creates and initializes struct200super_block accordingly, returning its root dentry to caller.201 202->mount() may choose to return a subtree of existing filesystem - it203doesn't have to create a new one. The main result from the caller's204point of view is a reference to dentry at the root of (sub)tree to be205attached; creation of new superblock is a common side effect.206 207The most interesting member of the superblock structure that the mount()208method fills in is the "s_op" field. This is a pointer to a "struct209super_operations" which describes the next level of the filesystem210implementation.211 212Usually, a filesystem uses one of the generic mount() implementations213and provides a fill_super() callback instead. The generic variants are:214 215``mount_bdev``216 mount a filesystem residing on a block device217 218``mount_nodev``219 mount a filesystem that is not backed by a device220 221``mount_single``222 mount a filesystem which shares the instance between all mounts223 224A fill_super() callback implementation has the following arguments:225 226``struct super_block *sb``227 the superblock structure. The callback must initialize this228 properly.229 230``void *data``231 arbitrary mount options, usually comes as an ASCII string (see232 "Mount Options" section)233 234``int silent``235 whether or not to be silent on error236 237 238The Superblock Object239=====================240 241A superblock object represents a mounted filesystem.242 243 244struct super_operations245-----------------------246 247This describes how the VFS can manipulate the superblock of your248filesystem. The following members are defined:249 250.. code-block:: c251 252 struct super_operations {253 struct inode *(*alloc_inode)(struct super_block *sb);254 void (*destroy_inode)(struct inode *);255 void (*free_inode)(struct inode *);256 257 void (*dirty_inode) (struct inode *, int flags);258 int (*write_inode) (struct inode *, struct writeback_control *wbc);259 int (*drop_inode) (struct inode *);260 void (*evict_inode) (struct inode *);261 void (*put_super) (struct super_block *);262 int (*sync_fs)(struct super_block *sb, int wait);263 int (*freeze_super) (struct super_block *sb,264 enum freeze_holder who);265 int (*freeze_fs) (struct super_block *);266 int (*thaw_super) (struct super_block *sb,267 enum freeze_wholder who);268 int (*unfreeze_fs) (struct super_block *);269 int (*statfs) (struct dentry *, struct kstatfs *);270 int (*remount_fs) (struct super_block *, int *, char *);271 void (*umount_begin) (struct super_block *);272 273 int (*show_options)(struct seq_file *, struct dentry *);274 int (*show_devname)(struct seq_file *, struct dentry *);275 int (*show_path)(struct seq_file *, struct dentry *);276 int (*show_stats)(struct seq_file *, struct dentry *);277 278 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);279 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);280 struct dquot **(*get_dquots)(struct inode *);281 282 long (*nr_cached_objects)(struct super_block *,283 struct shrink_control *);284 long (*free_cached_objects)(struct super_block *,285 struct shrink_control *);286 };287 288All methods are called without any locks being held, unless otherwise289noted. This means that most methods can block safely. All methods are290only called from a process context (i.e. not from an interrupt handler291or bottom half).292 293``alloc_inode``294 this method is called by alloc_inode() to allocate memory for295 struct inode and initialize it. If this function is not296 defined, a simple 'struct inode' is allocated. Normally297 alloc_inode will be used to allocate a larger structure which298 contains a 'struct inode' embedded within it.299 300``destroy_inode``301 this method is called by destroy_inode() to release resources302 allocated for struct inode. It is only required if303 ->alloc_inode was defined and simply undoes anything done by304 ->alloc_inode.305 306``free_inode``307 this method is called from RCU callback. If you use call_rcu()308 in ->destroy_inode to free 'struct inode' memory, then it's309 better to release memory in this method.310 311``dirty_inode``312 this method is called by the VFS when an inode is marked dirty.313 This is specifically for the inode itself being marked dirty,314 not its data. If the update needs to be persisted by fdatasync(),315 then I_DIRTY_DATASYNC will be set in the flags argument.316 I_DIRTY_TIME will be set in the flags in case lazytime is enabled317 and struct inode has times updated since the last ->dirty_inode318 call.319 320``write_inode``321 this method is called when the VFS needs to write an inode to322 disc. The second parameter indicates whether the write should323 be synchronous or not, not all filesystems check this flag.324 325``drop_inode``326 called when the last access to the inode is dropped, with the327 inode->i_lock spinlock held.328 329 This method should be either NULL (normal UNIX filesystem330 semantics) or "generic_delete_inode" (for filesystems that do331 not want to cache inodes - causing "delete_inode" to always be332 called regardless of the value of i_nlink)333 334 The "generic_delete_inode()" behavior is equivalent to the old335 practice of using "force_delete" in the put_inode() case, but336 does not have the races that the "force_delete()" approach had.337 338``evict_inode``339 called when the VFS wants to evict an inode. Caller does340 *not* evict the pagecache or inode-associated metadata buffers;341 the method has to use truncate_inode_pages_final() to get rid342 of those. Caller makes sure async writeback cannot be running for343 the inode while (or after) ->evict_inode() is called. Optional.344 345``put_super``346 called when the VFS wishes to free the superblock347 (i.e. unmount). This is called with the superblock lock held348 349``sync_fs``350 called when VFS is writing out all dirty data associated with a351 superblock. The second parameter indicates whether the method352 should wait until the write out has been completed. Optional.353 354``freeze_super``355 Called instead of ->freeze_fs callback if provided.356 Main difference is that ->freeze_super is called without taking357 down_write(&sb->s_umount). If filesystem implements it and wants358 ->freeze_fs to be called too, then it has to call ->freeze_fs359 explicitly from this callback. Optional.360 361``freeze_fs``362 called when VFS is locking a filesystem and forcing it into a363 consistent state. This method is currently used by the Logical364 Volume Manager (LVM) and ioctl(FIFREEZE). Optional.365 366``thaw_super``367 called when VFS is unlocking a filesystem and making it writable368 again after ->freeze_super. Optional.369 370``unfreeze_fs``371 called when VFS is unlocking a filesystem and making it writable372 again after ->freeze_fs. Optional.373 374``statfs``375 called when the VFS needs to get filesystem statistics.376 377``remount_fs``378 called when the filesystem is remounted. This is called with379 the kernel lock held380 381``umount_begin``382 called when the VFS is unmounting a filesystem.383 384``show_options``385 called by the VFS to show mount options for /proc/<pid>/mounts386 and /proc/<pid>/mountinfo.387 (see "Mount Options" section)388 389``show_devname``390 Optional. Called by the VFS to show device name for391 /proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then392 '(struct mount).mnt_devname' will be used.393 394``show_path``395 Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show396 the mount root dentry path relative to the filesystem root.397 398``show_stats``399 Optional. Called by the VFS (for /proc/<pid>/mountstats) to show400 filesystem-specific mount statistics.401 402``quota_read``403 called by the VFS to read from filesystem quota file.404 405``quota_write``406 called by the VFS to write to filesystem quota file.407 408``get_dquots``409 called by quota to get 'struct dquot' array for a particular inode.410 Optional.411 412``nr_cached_objects``413 called by the sb cache shrinking function for the filesystem to414 return the number of freeable cached objects it contains.415 Optional.416 417``free_cache_objects``418 called by the sb cache shrinking function for the filesystem to419 scan the number of objects indicated to try to free them.420 Optional, but any filesystem implementing this method needs to421 also implement ->nr_cached_objects for it to be called422 correctly.423 424 We can't do anything with any errors that the filesystem might425 encountered, hence the void return type. This will never be426 called if the VM is trying to reclaim under GFP_NOFS conditions,427 hence this method does not need to handle that situation itself.428 429 Implementations must include conditional reschedule calls inside430 any scanning loop that is done. This allows the VFS to431 determine appropriate scan batch sizes without having to worry432 about whether implementations will cause holdoff problems due to433 large scan batch sizes.434 435Whoever sets up the inode is responsible for filling in the "i_op"436field. This is a pointer to a "struct inode_operations" which describes437the methods that can be performed on individual inodes.438 439 440struct xattr_handler441---------------------442 443On filesystems that support extended attributes (xattrs), the s_xattr444superblock field points to a NULL-terminated array of xattr handlers.445Extended attributes are name:value pairs.446 447``name``448 Indicates that the handler matches attributes with the specified449 name (such as "system.posix_acl_access"); the prefix field must450 be NULL.451 452``prefix``453 Indicates that the handler matches all attributes with the454 specified name prefix (such as "user."); the name field must be455 NULL.456 457``list``458 Determine if attributes matching this xattr handler should be459 listed for a particular dentry. Used by some listxattr460 implementations like generic_listxattr.461 462``get``463 Called by the VFS to get the value of a particular extended464 attribute. This method is called by the getxattr(2) system465 call.466 467``set``468 Called by the VFS to set the value of a particular extended469 attribute. When the new value is NULL, called to remove a470 particular extended attribute. This method is called by the471 setxattr(2) and removexattr(2) system calls.472 473When none of the xattr handlers of a filesystem match the specified474attribute name or when a filesystem doesn't support extended attributes,475the various ``*xattr(2)`` system calls return -EOPNOTSUPP.476 477 478The Inode Object479================480 481An inode object represents an object within the filesystem.482 483 484struct inode_operations485-----------------------486 487This describes how the VFS can manipulate an inode in your filesystem.488As of kernel 2.6.22, the following members are defined:489 490.. code-block:: c491 492 struct inode_operations {493 int (*create) (struct mnt_idmap *, struct inode *,struct dentry *, umode_t, bool);494 struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);495 int (*link) (struct dentry *,struct inode *,struct dentry *);496 int (*unlink) (struct inode *,struct dentry *);497 int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *);498 int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t);499 int (*rmdir) (struct inode *,struct dentry *);500 int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t);501 int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *,502 struct inode *, struct dentry *, unsigned int);503 int (*readlink) (struct dentry *, char __user *,int);504 const char *(*get_link) (struct dentry *, struct inode *,505 struct delayed_call *);506 int (*permission) (struct mnt_idmap *, struct inode *, int);507 struct posix_acl * (*get_inode_acl)(struct inode *, int, bool);508 int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *);509 int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int);510 ssize_t (*listxattr) (struct dentry *, char *, size_t);511 void (*update_time)(struct inode *, struct timespec *, int);512 int (*atomic_open)(struct inode *, struct dentry *, struct file *,513 unsigned open_flag, umode_t create_mode);514 int (*tmpfile) (struct mnt_idmap *, struct inode *, struct file *, umode_t);515 struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int);516 int (*set_acl)(struct mnt_idmap *, struct dentry *, struct posix_acl *, int);517 int (*fileattr_set)(struct mnt_idmap *idmap,518 struct dentry *dentry, struct fileattr *fa);519 int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa);520 struct offset_ctx *(*get_offset_ctx)(struct inode *inode);521 };522 523Again, all methods are called without any locks being held, unless524otherwise noted.525 526``create``527 called by the open(2) and creat(2) system calls. Only required528 if you want to support regular files. The dentry you get should529 not have an inode (i.e. it should be a negative dentry). Here530 you will probably call d_instantiate() with the dentry and the531 newly created inode532 533``lookup``534 called when the VFS needs to look up an inode in a parent535 directory. The name to look for is found in the dentry. This536 method must call d_add() to insert the found inode into the537 dentry. The "i_count" field in the inode structure should be538 incremented. If the named inode does not exist a NULL inode539 should be inserted into the dentry (this is called a negative540 dentry). Returning an error code from this routine must only be541 done on a real error, otherwise creating inodes with system542 calls like create(2), mknod(2), mkdir(2) and so on will fail.543 If you wish to overload the dentry methods then you should544 initialise the "d_dop" field in the dentry; this is a pointer to545 a struct "dentry_operations". This method is called with the546 directory inode semaphore held547 548``link``549 called by the link(2) system call. Only required if you want to550 support hard links. You will probably need to call551 d_instantiate() just as you would in the create() method552 553``unlink``554 called by the unlink(2) system call. Only required if you want555 to support deleting inodes556 557``symlink``558 called by the symlink(2) system call. Only required if you want559 to support symlinks. You will probably need to call560 d_instantiate() just as you would in the create() method561 562``mkdir``563 called by the mkdir(2) system call. Only required if you want564 to support creating subdirectories. You will probably need to565 call d_instantiate() just as you would in the create() method566 567``rmdir``568 called by the rmdir(2) system call. Only required if you want569 to support deleting subdirectories570 571``mknod``572 called by the mknod(2) system call to create a device (char,573 block) inode or a named pipe (FIFO) or socket. Only required if574 you want to support creating these types of inodes. You will575 probably need to call d_instantiate() just as you would in the576 create() method577 578``rename``579 called by the rename(2) system call to rename the object to have580 the parent and name given by the second inode and dentry.581 582 The filesystem must return -EINVAL for any unsupported or583 unknown flags. Currently the following flags are implemented:584 (1) RENAME_NOREPLACE: this flag indicates that if the target of585 the rename exists the rename should fail with -EEXIST instead of586 replacing the target. The VFS already checks for existence, so587 for local filesystems the RENAME_NOREPLACE implementation is588 equivalent to plain rename.589 (2) RENAME_EXCHANGE: exchange source and target. Both must590 exist; this is checked by the VFS. Unlike plain rename, source591 and target may be of different type.592 593``get_link``594 called by the VFS to follow a symbolic link to the inode it595 points to. Only required if you want to support symbolic links.596 This method returns the symlink body to traverse (and possibly597 resets the current position with nd_jump_link()). If the body598 won't go away until the inode is gone, nothing else is needed;599 if it needs to be otherwise pinned, arrange for its release by600 having get_link(..., ..., done) do set_delayed_call(done,601 destructor, argument). In that case destructor(argument) will602 be called once VFS is done with the body you've returned. May603 be called in RCU mode; that is indicated by NULL dentry604 argument. If request can't be handled without leaving RCU mode,605 have it return ERR_PTR(-ECHILD).606 607 If the filesystem stores the symlink target in ->i_link, the608 VFS may use it directly without calling ->get_link(); however,609 ->get_link() must still be provided. ->i_link must not be610 freed until after an RCU grace period. Writing to ->i_link611 post-iget() time requires a 'release' memory barrier.612 613``readlink``614 this is now just an override for use by readlink(2) for the615 cases when ->get_link uses nd_jump_link() or object is not in616 fact a symlink. Normally filesystems should only implement617 ->get_link for symlinks and readlink(2) will automatically use618 that.619 620``permission``621 called by the VFS to check for access rights on a POSIX-like622 filesystem.623 624 May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in625 rcu-walk mode, the filesystem must check the permission without626 blocking or storing to the inode.627 628 If a situation is encountered that rcu-walk cannot handle,629 return630 -ECHILD and it will be called again in ref-walk mode.631 632``setattr``633 called by the VFS to set attributes for a file. This method is634 called by chmod(2) and related system calls.635 636``getattr``637 called by the VFS to get attributes of a file. This method is638 called by stat(2) and related system calls.639 640``listxattr``641 called by the VFS to list all extended attributes for a given642 file. This method is called by the listxattr(2) system call.643 644``update_time``645 called by the VFS to update a specific time or the i_version of646 an inode. If this is not defined the VFS will update the inode647 itself and call mark_inode_dirty_sync.648 649``atomic_open``650 called on the last component of an open. Using this optional651 method the filesystem can look up, possibly create and open the652 file in one atomic operation. If it wants to leave actual653 opening to the caller (e.g. if the file turned out to be a654 symlink, device, or just something filesystem won't do atomic655 open for), it may signal this by returning finish_no_open(file,656 dentry). This method is only called if the last component is657 negative or needs lookup. Cached positive dentries are still658 handled by f_op->open(). If the file was created, FMODE_CREATED659 flag should be set in file->f_mode. In case of O_EXCL the660 method must only succeed if the file didn't exist and hence661 FMODE_CREATED shall always be set on success.662 663``tmpfile``664 called in the end of O_TMPFILE open(). Optional, equivalent to665 atomically creating, opening and unlinking a file in given666 directory. On success needs to return with the file already667 open; this can be done by calling finish_open_simple() right at668 the end.669 670``fileattr_get``671 called on ioctl(FS_IOC_GETFLAGS) and ioctl(FS_IOC_FSGETXATTR) to672 retrieve miscellaneous file flags and attributes. Also called673 before the relevant SET operation to check what is being changed674 (in this case with i_rwsem locked exclusive). If unset, then675 fall back to f_op->ioctl().676 677``fileattr_set``678 called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to679 change miscellaneous file flags and attributes. Callers hold680 i_rwsem exclusive. If unset, then fall back to f_op->ioctl().681``get_offset_ctx``682 called to get the offset context for a directory inode. A683 filesystem must define this operation to use684 simple_offset_dir_operations.685 686The Address Space Object687========================688 689The address space object is used to group and manage pages in the page690cache. It can be used to keep track of the pages in a file (or anything691else) and also track the mapping of sections of the file into process692address spaces.693 694There are a number of distinct yet related services that an695address-space can provide. These include communicating memory pressure,696page lookup by address, and keeping track of pages tagged as Dirty or697Writeback.698 699The first can be used independently to the others. The VM can try to700either write dirty pages in order to clean them, or release clean pages701in order to reuse them. To do this it can call the ->writepage method702on dirty pages, and ->release_folio on clean folios with the private703flag set. Clean pages without PagePrivate and with no external references704will be released without notice being given to the address_space.705 706To achieve this functionality, pages need to be placed on an LRU with707lru_cache_add and mark_page_active needs to be called whenever the page708is used.709 710Pages are normally kept in a radix tree index by ->index. This tree711maintains information about the PG_Dirty and PG_Writeback status of each712page, so that pages with either of these flags can be found quickly.713 714The Dirty tag is primarily used by mpage_writepages - the default715->writepages method. It uses the tag to find dirty pages to call716->writepage on. If mpage_writepages is not used (i.e. the address717provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is almost718unused. write_inode_now and sync_inode do use it (through719__sync_single_inode) to check if ->writepages has been successful in720writing out the whole address_space.721 722The Writeback tag is used by filemap*wait* and sync_page* functions, via723filemap_fdatawait_range, to wait for all writeback to complete.724 725An address_space handler may attach extra information to a page,726typically using the 'private' field in the 'struct page'. If such727information is attached, the PG_Private flag should be set. This will728cause various VM routines to make extra calls into the address_space729handler to deal with that data.730 731An address space acts as an intermediate between storage and732application. Data is read into the address space a whole page at a733time, and provided to the application either by copying of the page, or734by memory-mapping the page. Data is written into the address space by735the application, and then written-back to storage typically in whole736pages, however the address_space has finer control of write sizes.737 738The read process essentially only requires 'read_folio'. The write739process is more complicated and uses write_begin/write_end or740dirty_folio to write data into the address_space, and writepage and741writepages to writeback data to storage.742 743Adding and removing pages to/from an address_space is protected by the744inode's i_mutex.745 746When data is written to a page, the PG_Dirty flag should be set. It747typically remains set until writepage asks for it to be written. This748should clear PG_Dirty and set PG_Writeback. It can be actually written749at any point after PG_Dirty is clear. Once it is known to be safe,750PG_Writeback is cleared.751 752Writeback makes use of a writeback_control structure to direct the753operations. This gives the writepage and writepages operations some754information about the nature of and reason for the writeback request,755and the constraints under which it is being done. It is also used to756return information back to the caller about the result of a writepage or757writepages request.758 759 760Handling errors during writeback761--------------------------------762 763Most applications that do buffered I/O will periodically call a file764synchronization call (fsync, fdatasync, msync or sync_file_range) to765ensure that data written has made it to the backing store. When there766is an error during writeback, they expect that error to be reported when767a file sync request is made. After an error has been reported on one768request, subsequent requests on the same file descriptor should return7690, unless further writeback errors have occurred since the previous file770synchronization.771 772Ideally, the kernel would report errors only on file descriptions on773which writes were done that subsequently failed to be written back. The774generic pagecache infrastructure does not track the file descriptions775that have dirtied each individual page however, so determining which776file descriptors should get back an error is not possible.777 778Instead, the generic writeback error tracking infrastructure in the779kernel settles for reporting errors to fsync on all file descriptions780that were open at the time that the error occurred. In a situation with781multiple writers, all of them will get back an error on a subsequent782fsync, even if all of the writes done through that particular file783descriptor succeeded (or even if there were no writes on that file784descriptor at all).785 786Filesystems that wish to use this infrastructure should call787mapping_set_error to record the error in the address_space when it788occurs. Then, after writing back data from the pagecache in their789file->fsync operation, they should call file_check_and_advance_wb_err to790ensure that the struct file's error cursor has advanced to the correct791point in the stream of errors emitted by the backing device(s).792 793 794struct address_space_operations795-------------------------------796 797This describes how the VFS can manipulate mapping of a file to page798cache in your filesystem. The following members are defined:799 800.. code-block:: c801 802 struct address_space_operations {803 int (*writepage)(struct page *page, struct writeback_control *wbc);804 int (*read_folio)(struct file *, struct folio *);805 int (*writepages)(struct address_space *, struct writeback_control *);806 bool (*dirty_folio)(struct address_space *, struct folio *);807 void (*readahead)(struct readahead_control *);808 int (*write_begin)(struct file *, struct address_space *mapping,809 loff_t pos, unsigned len,810 struct page **pagep, void **fsdata);811 int (*write_end)(struct file *, struct address_space *mapping,812 loff_t pos, unsigned len, unsigned copied,813 struct folio *folio, void *fsdata);814 sector_t (*bmap)(struct address_space *, sector_t);815 void (*invalidate_folio) (struct folio *, size_t start, size_t len);816 bool (*release_folio)(struct folio *, gfp_t);817 void (*free_folio)(struct folio *);818 ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter);819 int (*migrate_folio)(struct mapping *, struct folio *dst,820 struct folio *src, enum migrate_mode);821 int (*launder_folio) (struct folio *);822 823 bool (*is_partially_uptodate) (struct folio *, size_t from,824 size_t count);825 void (*is_dirty_writeback)(struct folio *, bool *, bool *);826 int (*error_remove_folio)(struct mapping *mapping, struct folio *);827 int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span)828 int (*swap_deactivate)(struct file *);829 int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter);830 };831 832``writepage``833 called by the VM to write a dirty page to backing store. This834 may happen for data integrity reasons (i.e. 'sync'), or to free835 up memory (flush). The difference can be seen in836 wbc->sync_mode. The PG_Dirty flag has been cleared and837 PageLocked is true. writepage should start writeout, should set838 PG_Writeback, and should make sure the page is unlocked, either839 synchronously or asynchronously when the write operation840 completes.841 842 If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to843 try too hard if there are problems, and may choose to write out844 other pages from the mapping if that is easier (e.g. due to845 internal dependencies). If it chooses not to start writeout, it846 should return AOP_WRITEPAGE_ACTIVATE so that the VM will not847 keep calling ->writepage on that page.848 849 See the file "Locking" for more details.850 851``read_folio``852 Called by the page cache to read a folio from the backing store.853 The 'file' argument supplies authentication information to network854 filesystems, and is generally not used by block based filesystems.855 It may be NULL if the caller does not have an open file (eg if856 the kernel is performing a read for itself rather than on behalf857 of a userspace process with an open file).858 859 If the mapping does not support large folios, the folio will860 contain a single page. The folio will be locked when read_folio861 is called. If the read completes successfully, the folio should862 be marked uptodate. The filesystem should unlock the folio863 once the read has completed, whether it was successful or not.864 The filesystem does not need to modify the refcount on the folio;865 the page cache holds a reference count and that will not be866 released until the folio is unlocked.867 868 Filesystems may implement ->read_folio() synchronously.869 In normal operation, folios are read through the ->readahead()870 method. Only if this fails, or if the caller needs to wait for871 the read to complete will the page cache call ->read_folio().872 Filesystems should not attempt to perform their own readahead873 in the ->read_folio() operation.874 875 If the filesystem cannot perform the read at this time, it can876 unlock the folio, do whatever action it needs to ensure that the877 read will succeed in the future and return AOP_TRUNCATED_PAGE.878 In this case, the caller should look up the folio, lock it,879 and call ->read_folio again.880 881 Callers may invoke the ->read_folio() method directly, but using882 read_mapping_folio() will take care of locking, waiting for the883 read to complete and handle cases such as AOP_TRUNCATED_PAGE.884 885``writepages``886 called by the VM to write out pages associated with the887 address_space object. If wbc->sync_mode is WB_SYNC_ALL, then888 the writeback_control will specify a range of pages that must be889 written out. If it is WB_SYNC_NONE, then a nr_to_write is890 given and that many pages should be written if possible. If no891 ->writepages is given, then mpage_writepages is used instead.892 This will choose pages from the address space that are tagged as893 DIRTY and will pass them to ->writepage.894 895``dirty_folio``896 called by the VM to mark a folio as dirty. This is particularly897 needed if an address space attaches private data to a folio, and898 that data needs to be updated when a folio is dirtied. This is899 called, for example, when a memory mapped page gets modified.900 If defined, it should set the folio dirty flag, and the901 PAGECACHE_TAG_DIRTY search mark in i_pages.902 903``readahead``904 Called by the VM to read pages associated with the address_space905 object. The pages are consecutive in the page cache and are906 locked. The implementation should decrement the page refcount907 after starting I/O on each page. Usually the page will be908 unlocked by the I/O completion handler. The set of pages are909 divided into some sync pages followed by some async pages,910 rac->ra->async_size gives the number of async pages. The911 filesystem should attempt to read all sync pages but may decide912 to stop once it reaches the async pages. If it does decide to913 stop attempting I/O, it can simply return. The caller will914 remove the remaining pages from the address space, unlock them915 and decrement the page refcount. Set PageUptodate if the I/O916 completes successfully.917 918``write_begin``919 Called by the generic buffered write code to ask the filesystem920 to prepare to write len bytes at the given offset in the file.921 The address_space should check that the write will be able to922 complete, by allocating space if necessary and doing any other923 internal housekeeping. If the write will update parts of any924 basic-blocks on storage, then those blocks should be pre-read925 (if they haven't been read already) so that the updated blocks926 can be written out properly.927 928 The filesystem must return the locked pagecache folio for the929 specified offset, in ``*foliop``, for the caller to write into.930 931 It must be able to cope with short writes (where the length932 passed to write_begin is greater than the number of bytes copied933 into the folio).934 935 A void * may be returned in fsdata, which then gets passed into936 write_end.937 938 Returns 0 on success; < 0 on failure (which is the error code),939 in which case write_end is not called.940 941``write_end``942 After a successful write_begin, and data copy, write_end must be943 called. len is the original len passed to write_begin, and944 copied is the amount that was able to be copied.945 946 The filesystem must take care of unlocking the folio,947 decrementing its refcount, and updating i_size.948 949 Returns < 0 on failure, otherwise the number of bytes (<=950 'copied') that were able to be copied into pagecache.951 952``bmap``953 called by the VFS to map a logical block offset within object to954 physical block number. This method is used by the FIBMAP ioctl955 and for working with swap-files. To be able to swap to a file,956 the file must have a stable mapping to a block device. The swap957 system does not go through the filesystem but instead uses bmap958 to find out where the blocks in the file are and uses those959 addresses directly.960 961``invalidate_folio``962 If a folio has private data, then invalidate_folio will be963 called when part or all of the folio is to be removed from the964 address space. This generally corresponds to either a965 truncation, punch hole or a complete invalidation of the address966 space (in the latter case 'offset' will always be 0 and 'length'967 will be folio_size()). Any private data associated with the folio968 should be updated to reflect this truncation. If offset is 0969 and length is folio_size(), then the private data should be970 released, because the folio must be able to be completely971 discarded. This may be done by calling the ->release_folio972 function, but in this case the release MUST succeed.973 974``release_folio``975 release_folio is called on folios with private data to tell the976 filesystem that the folio is about to be freed. ->release_folio977 should remove any private data from the folio and clear the978 private flag. If release_folio() fails, it should return false.979 release_folio() is used in two distinct though related cases.980 The first is when the VM wants to free a clean folio with no981 active users. If ->release_folio succeeds, the folio will be982 removed from the address_space and be freed.983 984 The second case is when a request has been made to invalidate985 some or all folios in an address_space. This can happen986 through the fadvise(POSIX_FADV_DONTNEED) system call or by the987 filesystem explicitly requesting it as nfs and 9p do (when they988 believe the cache may be out of date with storage) by calling989 invalidate_inode_pages2(). If the filesystem makes such a call,990 and needs to be certain that all folios are invalidated, then991 its release_folio will need to ensure this. Possibly it can992 clear the uptodate flag if it cannot free private data yet.993 994``free_folio``995 free_folio is called once the folio is no longer visible in the996 page cache in order to allow the cleanup of any private data.997 Since it may be called by the memory reclaimer, it should not998 assume that the original address_space mapping still exists, and999 it should not block.1000 1001``direct_IO``1002 called by the generic read/write routines to perform direct_IO -1003 that is IO requests which bypass the page cache and transfer1004 data directly between the storage and the application's address1005 space.1006 1007``migrate_folio``1008 This is used to compact the physical memory usage. If the VM1009 wants to relocate a folio (maybe from a memory device that is1010 signalling imminent failure) it will pass a new folio and an old1011 folio to this function. migrate_folio should transfer any private1012 data across and update any references that it has to the folio.1013 1014``launder_folio``1015 Called before freeing a folio - it writes back the dirty folio.1016 To prevent redirtying the folio, it is kept locked during the1017 whole operation.1018 1019``is_partially_uptodate``1020 Called by the VM when reading a file through the pagecache when1021 the underlying blocksize is smaller than the size of the folio.1022 If the required block is up to date then the read can complete1023 without needing I/O to bring the whole page up to date.1024 1025``is_dirty_writeback``1026 Called by the VM when attempting to reclaim a folio. The VM uses1027 dirty and writeback information to determine if it needs to1028 stall to allow flushers a chance to complete some IO.1029 Ordinarily it can use folio_test_dirty and folio_test_writeback but1030 some filesystems have more complex state (unstable folios in NFS1031 prevent reclaim) or do not set those flags due to locking1032 problems. This callback allows a filesystem to indicate to the1033 VM if a folio should be treated as dirty or writeback for the1034 purposes of stalling.1035 1036``error_remove_folio``1037 normally set to generic_error_remove_folio if truncation is ok1038 for this address space. Used for memory failure handling.1039 Setting this implies you deal with pages going away under you,1040 unless you have them locked or reference counts increased.1041 1042``swap_activate``1043 1044 Called to prepare the given file for swap. It should perform1045 any validation and preparation necessary to ensure that writes1046 can be performed with minimal memory allocation. It should call1047 add_swap_extent(), or the helper iomap_swapfile_activate(), and1048 return the number of extents added. If IO should be submitted1049 through ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will1050 be submitted directly to the block device ``sis->bdev``.1051 1052``swap_deactivate``1053 Called during swapoff on files where swap_activate was1054 successful.1055 1056``swap_rw``1057 Called to read or write swap pages when SWP_FS_OPS is set.1058 1059The File Object1060===============1061 1062A file object represents a file opened by a process. This is also known1063as an "open file description" in POSIX parlance.1064 1065 1066struct file_operations1067----------------------1068 1069This describes how the VFS can manipulate an open file. As of kernel10704.18, the following members are defined:1071 1072.. code-block:: c1073 1074 struct file_operations {1075 struct module *owner;1076 loff_t (*llseek) (struct file *, loff_t, int);1077 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);1078 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);1079 ssize_t (*read_iter) (struct kiocb *, struct iov_iter *);1080 ssize_t (*write_iter) (struct kiocb *, struct iov_iter *);1081 int (*iopoll)(struct kiocb *kiocb, bool spin);1082 int (*iterate_shared) (struct file *, struct dir_context *);1083 __poll_t (*poll) (struct file *, struct poll_table_struct *);1084 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);1085 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);1086 int (*mmap) (struct file *, struct vm_area_struct *);1087 int (*open) (struct inode *, struct file *);1088 int (*flush) (struct file *, fl_owner_t id);1089 int (*release) (struct inode *, struct file *);1090 int (*fsync) (struct file *, loff_t, loff_t, int datasync);1091 int (*fasync) (int, struct file *, int);1092 int (*lock) (struct file *, int, struct file_lock *);1093 unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);1094 int (*check_flags)(int);1095 int (*flock) (struct file *, int, struct file_lock *);1096 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int);1097 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int);1098 int (*setlease)(struct file *, long, struct file_lock **, void **);1099 long (*fallocate)(struct file *file, int mode, loff_t offset,1100 loff_t len);1101 void (*show_fdinfo)(struct seq_file *m, struct file *f);1102 #ifndef CONFIG_MMU1103 unsigned (*mmap_capabilities)(struct file *);1104 #endif1105 ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t, size_t, unsigned int);1106 loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in,1107 struct file *file_out, loff_t pos_out,1108 loff_t len, unsigned int remap_flags);1109 int (*fadvise)(struct file *, loff_t, loff_t, int);1110 };1111 1112Again, all methods are called without any locks being held, unless1113otherwise noted.1114 1115``llseek``1116 called when the VFS needs to move the file position index1117 1118``read``1119 called by read(2) and related system calls1120 1121``read_iter``1122 possibly asynchronous read with iov_iter as destination1123 1124``write``1125 called by write(2) and related system calls1126 1127``write_iter``1128 possibly asynchronous write with iov_iter as source1129 1130``iopoll``1131 called when aio wants to poll for completions on HIPRI iocbs1132 1133``iterate_shared``1134 called when the VFS needs to read the directory contents1135 1136``poll``1137 called by the VFS when a process wants to check if there is1138 activity on this file and (optionally) go to sleep until there1139 is activity. Called by the select(2) and poll(2) system calls1140 1141``unlocked_ioctl``1142 called by the ioctl(2) system call.1143 1144``compat_ioctl``1145 called by the ioctl(2) system call when 32 bit system calls are1146 used on 64 bit kernels.1147 1148``mmap``1149 called by the mmap(2) system call1150 1151``open``1152 called by the VFS when an inode should be opened. When the VFS1153 opens a file, it creates a new "struct file". It then calls the1154 open method for the newly allocated file structure. You might1155 think that the open method really belongs in "struct1156 inode_operations", and you may be right. I think it's done the1157 way it is because it makes filesystems simpler to implement.1158 The open() method is a good place to initialize the1159 "private_data" member in the file structure if you want to point1160 to a device structure1161 1162``flush``1163 called by the close(2) system call to flush a file1164 1165``release``1166 called when the last reference to an open file is closed1167 1168``fsync``1169 called by the fsync(2) system call. Also see the section above1170 entitled "Handling errors during writeback".1171 1172``fasync``1173 called by the fcntl(2) system call when asynchronous1174 (non-blocking) mode is enabled for a file1175 1176``lock``1177 called by the fcntl(2) system call for F_GETLK, F_SETLK, and1178 F_SETLKW commands1179 1180``get_unmapped_area``1181 called by the mmap(2) system call1182 1183``check_flags``1184 called by the fcntl(2) system call for F_SETFL command1185 1186``flock``1187 called by the flock(2) system call1188 1189``splice_write``1190 called by the VFS to splice data from a pipe to a file. This1191 method is used by the splice(2) system call1192 1193``splice_read``1194 called by the VFS to splice data from file to a pipe. This1195 method is used by the splice(2) system call1196 1197``setlease``1198 called by the VFS to set or release a file lock lease. setlease1199 implementations should call generic_setlease to record or remove1200 the lease in the inode after setting it.1201 1202``fallocate``1203 called by the VFS to preallocate blocks or punch a hole.1204 1205``copy_file_range``1206 called by the copy_file_range(2) system call.1207 1208``remap_file_range``1209 called by the ioctl(2) system call for FICLONERANGE and FICLONE1210 and FIDEDUPERANGE commands to remap file ranges. An1211 implementation should remap len bytes at pos_in of the source1212 file into the dest file at pos_out. Implementations must handle1213 callers passing in len == 0; this means "remap to the end of the1214 source file". The return value should the number of bytes1215 remapped, or the usual negative error code if errors occurred1216 before any bytes were remapped. The remap_flags parameter1217 accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the1218 implementation must only remap if the requested file ranges have1219 identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is1220 ok with the implementation shortening the request length to1221 satisfy alignment or EOF requirements (or any other reason).1222 1223``fadvise``1224 possibly called by the fadvise64() system call.1225 1226Note that the file operations are implemented by the specific1227filesystem in which the inode resides. When opening a device node1228(character or block special) most filesystems will call special1229support routines in the VFS which will locate the required device1230driver information. These support routines replace the filesystem file1231operations with those for the device driver, and then proceed to call1232the new open() method for the file. This is how opening a device file1233in the filesystem eventually ends up calling the device driver open()1234method.1235 1236 1237Directory Entry Cache (dcache)1238==============================1239 1240 1241struct dentry_operations1242------------------------1243 1244This describes how a filesystem can overload the standard dentry1245operations. Dentries and the dcache are the domain of the VFS and the1246individual filesystem implementations. Device drivers have no business1247here. These methods may be set to NULL, as they are either optional or1248the VFS uses a default. As of kernel 2.6.22, the following members are1249defined:1250 1251.. code-block:: c1252 1253 struct dentry_operations {1254 int (*d_revalidate)(struct dentry *, unsigned int);1255 int (*d_weak_revalidate)(struct dentry *, unsigned int);1256 int (*d_hash)(const struct dentry *, struct qstr *);1257 int (*d_compare)(const struct dentry *,1258 unsigned int, const char *, const struct qstr *);1259 int (*d_delete)(const struct dentry *);1260 int (*d_init)(struct dentry *);1261 void (*d_release)(struct dentry *);1262 void (*d_iput)(struct dentry *, struct inode *);1263 char *(*d_dname)(struct dentry *, char *, int);1264 struct vfsmount *(*d_automount)(struct path *);1265 int (*d_manage)(const struct path *, bool);1266 struct dentry *(*d_real)(struct dentry *, enum d_real_type type);1267 };1268 1269``d_revalidate``1270 called when the VFS needs to revalidate a dentry. This is1271 called whenever a name look-up finds a dentry in the dcache.1272 Most local filesystems leave this as NULL, because all their1273 dentries in the dcache are valid. Network filesystems are1274 different since things can change on the server without the1275 client necessarily being aware of it.1276 1277 This function should return a positive value if the dentry is1278 still valid, and zero or a negative error code if it isn't.1279 1280 d_revalidate may be called in rcu-walk mode (flags &1281 LOOKUP_RCU). If in rcu-walk mode, the filesystem must1282 revalidate the dentry without blocking or storing to the dentry,1283 d_parent and d_inode should not be used without care (because1284 they can change and, in d_inode case, even become NULL under1285 us).1286 1287 If a situation is encountered that rcu-walk cannot handle,1288 return1289 -ECHILD and it will be called again in ref-walk mode.1290 1291``d_weak_revalidate``1292 called when the VFS needs to revalidate a "jumped" dentry. This1293 is called when a path-walk ends at dentry that was not acquired1294 by doing a lookup in the parent directory. This includes "/",1295 "." and "..", as well as procfs-style symlinks and mountpoint1296 traversal.1297 1298 In this case, we are less concerned with whether the dentry is1299 still fully correct, but rather that the inode is still valid.1300 As with d_revalidate, most local filesystems will set this to1301 NULL since their dcache entries are always valid.1302 1303 This function has the same return code semantics as1304 d_revalidate.1305 1306 d_weak_revalidate is only called after leaving rcu-walk mode.1307 1308``d_hash``1309 called when the VFS adds a dentry to the hash table. The first1310 dentry passed to d_hash is the parent directory that the name is1311 to be hashed into.1312 1313 Same locking and synchronisation rules as d_compare regarding1314 what is safe to dereference etc.1315 1316``d_compare``1317 called to compare a dentry name with a given name. The first1318 dentry is the parent of the dentry to be compared, the second is1319 the child dentry. len and name string are properties of the1320 dentry to be compared. qstr is the name to compare it with.1321 1322 Must be constant and idempotent, and should not take locks if1323 possible, and should not or store into the dentry. Should not1324 dereference pointers outside the dentry without lots of care1325 (eg. d_parent, d_inode, d_name should not be used).1326 1327 However, our vfsmount is pinned, and RCU held, so the dentries1328 and inodes won't disappear, neither will our sb or filesystem1329 module. ->d_sb may be used.1330 1331 It is a tricky calling convention because it needs to be called1332 under "rcu-walk", ie. without any locks or references on things.1333 1334``d_delete``1335 called when the last reference to a dentry is dropped and the1336 dcache is deciding whether or not to cache it. Return 1 to1337 delete immediately, or 0 to cache the dentry. Default is NULL1338 which means to always cache a reachable dentry. d_delete must1339 be constant and idempotent.1340 1341``d_init``1342 called when a dentry is allocated1343 1344``d_release``1345 called when a dentry is really deallocated1346 1347``d_iput``1348 called when a dentry loses its inode (just prior to its being1349 deallocated). The default when this is NULL is that the VFS1350 calls iput(). If you define this method, you must call iput()1351 yourself1352 1353``d_dname``1354 called when the pathname of a dentry should be generated.1355 Useful for some pseudo filesystems (sockfs, pipefs, ...) to1356 delay pathname generation. (Instead of doing it when dentry is1357 created, it's done only when the path is needed.). Real1358 filesystems probably dont want to use it, because their dentries1359 are present in global dcache hash, so their hash should be an1360 invariant. As no lock is held, d_dname() should not try to1361 modify the dentry itself, unless appropriate SMP safety is used.1362 CAUTION : d_path() logic is quite tricky. The correct way to1363 return for example "Hello" is to put it at the end of the1364 buffer, and returns a pointer to the first char.1365 dynamic_dname() helper function is provided to take care of1366 this.1367 1368 Example :1369 1370.. code-block:: c1371 1372 static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)1373 {1374 return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",1375 dentry->d_inode->i_ino);1376 }1377 1378``d_automount``1379 called when an automount dentry is to be traversed (optional).1380 This should create a new VFS mount record and return the record1381 to the caller. The caller is supplied with a path parameter1382 giving the automount directory to describe the automount target1383 and the parent VFS mount record to provide inheritable mount1384 parameters. NULL should be returned if someone else managed to1385 make the automount first. If the vfsmount creation failed, then1386 an error code should be returned. If -EISDIR is returned, then1387 the directory will be treated as an ordinary directory and1388 returned to pathwalk to continue walking.1389 1390 If a vfsmount is returned, the caller will attempt to mount it1391 on the mountpoint and will remove the vfsmount from its1392 expiration list in the case of failure. The vfsmount should be1393 returned with 2 refs on it to prevent automatic expiration - the1394 caller will clean up the additional ref.1395 1396 This function is only used if DCACHE_NEED_AUTOMOUNT is set on1397 the dentry. This is set by __d_instantiate() if S_AUTOMOUNT is1398 set on the inode being added.1399 1400``d_manage``1401 called to allow the filesystem to manage the transition from a1402 dentry (optional). This allows autofs, for example, to hold up1403 clients waiting to explore behind a 'mountpoint' while letting1404 the daemon go past and construct the subtree there. 0 should be1405 returned to let the calling process continue. -EISDIR can be1406 returned to tell pathwalk to use this directory as an ordinary1407 directory and to ignore anything mounted on it and not to check1408 the automount flag. Any other error code will abort pathwalk1409 completely.1410 1411 If the 'rcu_walk' parameter is true, then the caller is doing a1412 pathwalk in RCU-walk mode. Sleeping is not permitted in this1413 mode, and the caller can be asked to leave it and call again by1414 returning -ECHILD. -EISDIR may also be returned to tell1415 pathwalk to ignore d_automount or any mounts.1416 1417 This function is only used if DCACHE_MANAGE_TRANSIT is set on1418 the dentry being transited from.1419 1420``d_real``1421 overlay/union type filesystems implement this method to return one1422 of the underlying dentries of a regular file hidden by the overlay.1423 1424 The 'type' argument takes the values D_REAL_DATA or D_REAL_METADATA1425 for returning the real underlying dentry that refers to the inode1426 hosting the file's data or metadata respectively.1427 1428 For non-regular files, the 'dentry' argument is returned.1429 1430Each dentry has a pointer to its parent dentry, as well as a hash list1431of child dentries. Child dentries are basically like files in a1432directory.1433 1434 1435Directory Entry Cache API1436--------------------------1437 1438There are a number of functions defined which permit a filesystem to1439manipulate dentries:1440 1441``dget``1442 open a new handle for an existing dentry (this just increments1443 the usage count)1444 1445``dput``1446 close a handle for a dentry (decrements the usage count). If1447 the usage count drops to 0, and the dentry is still in its1448 parent's hash, the "d_delete" method is called to check whether1449 it should be cached. If it should not be cached, or if the1450 dentry is not hashed, it is deleted. Otherwise cached dentries1451 are put into an LRU list to be reclaimed on memory shortage.1452 1453``d_drop``1454 this unhashes a dentry from its parents hash list. A subsequent1455 call to dput() will deallocate the dentry if its usage count1456 drops to 01457 1458``d_delete``1459 delete a dentry. If there are no other open references to the1460 dentry then the dentry is turned into a negative dentry (the1461 d_iput() method is called). If there are other references, then1462 d_drop() is called instead1463 1464``d_add``1465 add a dentry to its parents hash list and then calls1466 d_instantiate()1467 1468``d_instantiate``1469 add a dentry to the alias hash list for the inode and updates1470 the "d_inode" member. The "i_count" member in the inode1471 structure should be set/incremented. If the inode pointer is1472 NULL, the dentry is called a "negative dentry". This function1473 is commonly called when an inode is created for an existing1474 negative dentry1475 1476``d_lookup``1477 look up a dentry given its parent and path name component It1478 looks up the child of that given name from the dcache hash1479 table. If it is found, the reference count is incremented and1480 the dentry is returned. The caller must use dput() to free the1481 dentry when it finishes using it.1482 1483 1484Mount Options1485=============1486 1487 1488Parsing options1489---------------1490 1491On mount and remount the filesystem is passed a string containing a1492comma separated list of mount options. The options can have either of1493these forms:1494 1495 option1496 option=value1497 1498The <linux/parser.h> header defines an API that helps parse these1499options. There are plenty of examples on how to use it in existing1500filesystems.1501 1502 1503Showing options1504---------------1505 1506If a filesystem accepts mount options, it must define show_options() to1507show all the currently active options. The rules are:1508 1509 - options MUST be shown which are not default or their values differ1510 from the default1511 1512 - options MAY be shown which are enabled by default or have their1513 default value1514 1515Options used only internally between a mount helper and the kernel (such1516as file descriptors), or which only have an effect during the mounting1517(such as ones controlling the creation of a journal) are exempt from the1518above rules.1519 1520The underlying reason for the above rules is to make sure, that a mount1521can be accurately replicated (e.g. umounting and mounting again) based1522on the information found in /proc/mounts.1523 1524 1525Resources1526=========1527 1528(Note some of these resources are not up-to-date with the latest kernel1529 version.)1530 1531Creating Linux virtual filesystems. 20021532 <https://lwn.net/Articles/13325/>1533 1534The Linux Virtual File-system Layer by Neil Brown. 19991535 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>1536 1537A tour of the Linux VFS by Michael K. Johnson. 19961538 <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>1539 1540A small trail through the Linux kernel by Andries Brouwer. 20011541 <https://www.win.tue.nl/~aeb/linux/vfs/trail.html>1542