1.. SPDX-License-Identifier: GPL-2.0 2 3========================================= 4Overview of the Linux Virtual File System 5========================================= 6 7Original author: Richard Gooch <rgooch@atnf.csiro.au> 8 9- Copyright (C) 1999 Richard Gooch 10- Copyright (C) 2005 Pekka Enberg 11 12 13Introduction 14============ 15 16The Virtual File System (also known as the Virtual Filesystem Switch) is 17the software layer in the kernel that provides the filesystem interface 18to userspace programs. It also provides an abstraction within the 19kernel which allows different filesystem implementations to coexist. 20 21VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so on 22are called from a process context. Filesystem locking is described in 23the 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 system 30calls. The pathname argument that is passed to them is used by the VFS 31to search through the directory entry cache (also known as the dentry 32cache or dcache). This provides a very fast look-up mechanism to 33translate a pathname (filename) into a specific dentry. Dentries live 34in 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. As 37most computers cannot fit all dentries in the RAM at the same time, some 38bits of the cache are missing. In order to resolve your pathname into a 39dentry, 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 Object 44---------------- 45 46An individual dentry usually has a pointer to an inode. Inodes are 47filesystem objects such as regular files, directories, FIFOs and other 48beasts. They live either on the disc (for block device filesystems) or 49in the memory (for pseudo filesystems). Inodes that live on the disc 50are copied into the memory when required and changes to the inode are 51written back to disc. A single inode can be pointed to by multiple 52dentries (hard links, for example, do this). 53 54To look up an inode requires that the VFS calls the lookup() method of 55the parent directory inode. This method is installed by the specific 56filesystem implementation that the inode lives in. Once the VFS has the 57required dentry (and hence the inode), we can do all those boring things 58like open(2) the file, or stat(2) it to peek at the inode data. The 59stat(2) operation is fairly simple: once the VFS has the dentry, it 60peeks at the inode data and passes some of it back to userspace. 61 62 63The File Object 64--------------- 65 66Opening a file requires another operation: allocation of a file 67structure (this is the kernel-side implementation of file descriptors). 68The freshly allocated file structure is initialized with a pointer to 69the dentry and a set of file operation member functions. These are 70taken from the inode data. The open() file method is then called so the 71specific filesystem implementation can do its work. You can see that 72this is another switch performed by the VFS. The file structure is 73placed 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 appropriate 77file structure, and then calling the required file structure method to 78do whatever is required. For as long as the file is open, it keeps the 79dentry in use, which in turn means that the VFS inode is still in use. 80 81 82Registering and Mounting a Filesystem 83===================================== 84 85To register and unregister a filesystem, use the following API 86functions: 87 88.. code-block:: c 89 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 a 96request is made to mount a filesystem onto a directory in your 97namespace, the VFS will call the appropriate mount() method for the 98specific filesystem. New vfsmount referring to the tree returned by 99->mount() will be attached to the mountpoint, so that when pathname 100resolution reaches the mountpoint it will jump into the root of that 101vfsmount. 102 103You can see all filesystems that are registered to the kernel in the 104file /proc/filesystems. 105 106 107struct file_system_type 108----------------------- 109 110This describes the filesystem. The following 111members are defined: 112 113.. code-block:: c 114 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 on 141 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 with 147 filesystem-specific data. 148 149``parameters`` 150 Pointer to the array of filesystem parameters descriptors 151 '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 should 156 be mounted 157 158``kill_sb`` 159 the method to call when an instance of this filesystem should be 160 shut down 161 162 163``owner`` 164 for internal VFS use: you should initialize this to THIS_MODULE 165 in most cases. 166 167``next`` 168 for internal VFS use: you should initialize this to NULL 169 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-specific 175 176The mount() method has the following arguments: 177 178``struct file_system_type *fs_type`` 179 describes the filesystem, partly initialized by the specific 180 filesystem code 181 182``int flags`` 183 mount flags 184 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 (see 190 "Mount Options" section) 191 192The mount() method must return the root dentry of the tree requested by 193caller. An active reference to its superblock must be grabbed and the 194superblock must be locked. On failure it should return ERR_PTR(error). 195 196The arguments match those of mount(2) and their interpretation depends 197on filesystem type. E.g. for block filesystems, dev_name is interpreted 198as block device name, that device is opened and if it contains a 199suitable filesystem image the method creates and initializes struct 200super_block accordingly, returning its root dentry to caller. 201 202->mount() may choose to return a subtree of existing filesystem - it 203doesn't have to create a new one. The main result from the caller's 204point of view is a reference to dentry at the root of (sub)tree to be 205attached; 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 "struct 209super_operations" which describes the next level of the filesystem 210implementation. 211 212Usually, a filesystem uses one of the generic mount() implementations 213and provides a fill_super() callback instead. The generic variants are: 214 215``mount_bdev`` 216 mount a filesystem residing on a block device 217 218``mount_nodev`` 219 mount a filesystem that is not backed by a device 220 221``mount_single`` 222 mount a filesystem which shares the instance between all mounts 223 224A fill_super() callback implementation has the following arguments: 225 226``struct super_block *sb`` 227 the superblock structure. The callback must initialize this 228 properly. 229 230``void *data`` 231 arbitrary mount options, usually comes as an ASCII string (see 232 "Mount Options" section) 233 234``int silent`` 235 whether or not to be silent on error 236 237 238The Superblock Object 239===================== 240 241A superblock object represents a mounted filesystem. 242 243 244struct super_operations 245----------------------- 246 247This describes how the VFS can manipulate the superblock of your 248filesystem. The following members are defined: 249 250.. code-block:: c 251 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 *); 264 int (*freeze_fs) (struct super_block *); 265 int (*thaw_super) (struct super_block *); 266 int (*unfreeze_fs) (struct super_block *); 267 int (*statfs) (struct dentry *, struct kstatfs *); 268 int (*remount_fs) (struct super_block *, int *, char *); 269 void (*umount_begin) (struct super_block *); 270 271 int (*show_options)(struct seq_file *, struct dentry *); 272 int (*show_devname)(struct seq_file *, struct dentry *); 273 int (*show_path)(struct seq_file *, struct dentry *); 274 int (*show_stats)(struct seq_file *, struct dentry *); 275 276 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); 277 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); 278 struct dquot **(*get_dquots)(struct inode *); 279 280 long (*nr_cached_objects)(struct super_block *, 281 struct shrink_control *); 282 long (*free_cached_objects)(struct super_block *, 283 struct shrink_control *); 284 }; 285 286All methods are called without any locks being held, unless otherwise 287noted. This means that most methods can block safely. All methods are 288only called from a process context (i.e. not from an interrupt handler 289or bottom half). 290 291``alloc_inode`` 292 this method is called by alloc_inode() to allocate memory for 293 struct inode and initialize it. If this function is not 294 defined, a simple 'struct inode' is allocated. Normally 295 alloc_inode will be used to allocate a larger structure which 296 contains a 'struct inode' embedded within it. 297 298``destroy_inode`` 299 this method is called by destroy_inode() to release resources 300 allocated for struct inode. It is only required if 301 ->alloc_inode was defined and simply undoes anything done by 302 ->alloc_inode. 303 304``free_inode`` 305 this method is called from RCU callback. If you use call_rcu() 306 in ->destroy_inode to free 'struct inode' memory, then it's 307 better to release memory in this method. 308 309``dirty_inode`` 310 this method is called by the VFS when an inode is marked dirty. 311 This is specifically for the inode itself being marked dirty, 312 not its data. If the update needs to be persisted by fdatasync(), 313 then I_DIRTY_DATASYNC will be set in the flags argument. 314 I_DIRTY_TIME will be set in the flags in case lazytime is enabled 315 and struct inode has times updated since the last ->dirty_inode 316 call. 317 318``write_inode`` 319 this method is called when the VFS needs to write an inode to 320 disc. The second parameter indicates whether the write should 321 be synchronous or not, not all filesystems check this flag. 322 323``drop_inode`` 324 called when the last access to the inode is dropped, with the 325 inode->i_lock spinlock held. 326 327 This method should be either NULL (normal UNIX filesystem 328 semantics) or "generic_delete_inode" (for filesystems that do 329 not want to cache inodes - causing "delete_inode" to always be 330 called regardless of the value of i_nlink) 331 332 The "generic_delete_inode()" behavior is equivalent to the old 333 practice of using "force_delete" in the put_inode() case, but 334 does not have the races that the "force_delete()" approach had. 335 336``evict_inode`` 337 called when the VFS wants to evict an inode. Caller does 338 *not* evict the pagecache or inode-associated metadata buffers; 339 the method has to use truncate_inode_pages_final() to get rid 340 of those. Caller makes sure async writeback cannot be running for 341 the inode while (or after) ->evict_inode() is called. Optional. 342 343``put_super`` 344 called when the VFS wishes to free the superblock 345 (i.e. unmount). This is called with the superblock lock held 346 347``sync_fs`` 348 called when VFS is writing out all dirty data associated with a 349 superblock. The second parameter indicates whether the method 350 should wait until the write out has been completed. Optional. 351 352``freeze_super`` 353 Called instead of ->freeze_fs callback if provided. 354 Main difference is that ->freeze_super is called without taking 355 down_write(&sb->s_umount). If filesystem implements it and wants 356 ->freeze_fs to be called too, then it has to call ->freeze_fs 357 explicitly from this callback. Optional. 358 359``freeze_fs`` 360 called when VFS is locking a filesystem and forcing it into a 361 consistent state. This method is currently used by the Logical 362 Volume Manager (LVM) and ioctl(FIFREEZE). Optional. 363 364``thaw_super`` 365 called when VFS is unlocking a filesystem and making it writable 366 again after ->freeze_super. Optional. 367 368``unfreeze_fs`` 369 called when VFS is unlocking a filesystem and making it writable 370 again after ->freeze_fs. Optional. 371 372``statfs`` 373 called when the VFS needs to get filesystem statistics. 374 375``remount_fs`` 376 called when the filesystem is remounted. This is called with 377 the kernel lock held 378 379``umount_begin`` 380 called when the VFS is unmounting a filesystem. 381 382``show_options`` 383 called by the VFS to show mount options for /proc/<pid>/mounts 384 and /proc/<pid>/mountinfo. 385 (see "Mount Options" section) 386 387``show_devname`` 388 Optional. Called by the VFS to show device name for 389 /proc/<pid>/{mounts,mountinfo,mountstats}. If not provided then 390 '(struct mount).mnt_devname' will be used. 391 392``show_path`` 393 Optional. Called by the VFS (for /proc/<pid>/mountinfo) to show 394 the mount root dentry path relative to the filesystem root. 395 396``show_stats`` 397 Optional. Called by the VFS (for /proc/<pid>/mountstats) to show 398 filesystem-specific mount statistics. 399 400``quota_read`` 401 called by the VFS to read from filesystem quota file. 402 403``quota_write`` 404 called by the VFS to write to filesystem quota file. 405 406``get_dquots`` 407 called by quota to get 'struct dquot' array for a particular inode. 408 Optional. 409 410``nr_cached_objects`` 411 called by the sb cache shrinking function for the filesystem to 412 return the number of freeable cached objects it contains. 413 Optional. 414 415``free_cache_objects`` 416 called by the sb cache shrinking function for the filesystem to 417 scan the number of objects indicated to try to free them. 418 Optional, but any filesystem implementing this method needs to 419 also implement ->nr_cached_objects for it to be called 420 correctly. 421 422 We can't do anything with any errors that the filesystem might 423 encountered, hence the void return type. This will never be 424 called if the VM is trying to reclaim under GFP_NOFS conditions, 425 hence this method does not need to handle that situation itself. 426 427 Implementations must include conditional reschedule calls inside 428 any scanning loop that is done. This allows the VFS to 429 determine appropriate scan batch sizes without having to worry 430 about whether implementations will cause holdoff problems due to 431 large scan batch sizes. 432 433Whoever sets up the inode is responsible for filling in the "i_op" 434field. This is a pointer to a "struct inode_operations" which describes 435the methods that can be performed on individual inodes. 436 437 438struct xattr_handlers 439--------------------- 440 441On filesystems that support extended attributes (xattrs), the s_xattr 442superblock field points to a NULL-terminated array of xattr handlers. 443Extended attributes are name:value pairs. 444 445``name`` 446 Indicates that the handler matches attributes with the specified 447 name (such as "system.posix_acl_access"); the prefix field must 448 be NULL. 449 450``prefix`` 451 Indicates that the handler matches all attributes with the 452 specified name prefix (such as "user."); the name field must be 453 NULL. 454 455``list`` 456 Determine if attributes matching this xattr handler should be 457 listed for a particular dentry. Used by some listxattr 458 implementations like generic_listxattr. 459 460``get`` 461 Called by the VFS to get the value of a particular extended 462 attribute. This method is called by the getxattr(2) system 463 call. 464 465``set`` 466 Called by the VFS to set the value of a particular extended 467 attribute. When the new value is NULL, called to remove a 468 particular extended attribute. This method is called by the 469 setxattr(2) and removexattr(2) system calls. 470 471When none of the xattr handlers of a filesystem match the specified 472attribute name or when a filesystem doesn't support extended attributes, 473the various ``*xattr(2)`` system calls return -EOPNOTSUPP. 474 475 476The Inode Object 477================ 478 479An inode object represents an object within the filesystem. 480 481 482struct inode_operations 483----------------------- 484 485This describes how the VFS can manipulate an inode in your filesystem. 486As of kernel 2.6.22, the following members are defined: 487 488.. code-block:: c 489 490 struct inode_operations { 491 int (*create) (struct mnt_idmap *, struct inode *,struct dentry *, umode_t, bool); 492 struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int); 493 int (*link) (struct dentry *,struct inode *,struct dentry *); 494 int (*unlink) (struct inode *,struct dentry *); 495 int (*symlink) (struct mnt_idmap *, struct inode *,struct dentry *,const char *); 496 int (*mkdir) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t); 497 int (*rmdir) (struct inode *,struct dentry *); 498 int (*mknod) (struct mnt_idmap *, struct inode *,struct dentry *,umode_t,dev_t); 499 int (*rename) (struct mnt_idmap *, struct inode *, struct dentry *, 500 struct inode *, struct dentry *, unsigned int); 501 int (*readlink) (struct dentry *, char __user *,int); 502 const char *(*get_link) (struct dentry *, struct inode *, 503 struct delayed_call *); 504 int (*permission) (struct mnt_idmap *, struct inode *, int); 505 struct posix_acl * (*get_inode_acl)(struct inode *, int, bool); 506 int (*setattr) (struct mnt_idmap *, struct dentry *, struct iattr *); 507 int (*getattr) (struct mnt_idmap *, const struct path *, struct kstat *, u32, unsigned int); 508 ssize_t (*listxattr) (struct dentry *, char *, size_t); 509 void (*update_time)(struct inode *, struct timespec *, int); 510 int (*atomic_open)(struct inode *, struct dentry *, struct file *, 511 unsigned open_flag, umode_t create_mode); 512 int (*tmpfile) (struct mnt_idmap *, struct inode *, struct file *, umode_t); 513 struct posix_acl * (*get_acl)(struct mnt_idmap *, struct dentry *, int); 514 int (*set_acl)(struct mnt_idmap *, struct dentry *, struct posix_acl *, int); 515 int (*fileattr_set)(struct mnt_idmap *idmap, 516 struct dentry *dentry, struct fileattr *fa); 517 int (*fileattr_get)(struct dentry *dentry, struct fileattr *fa); 518 }; 519 520Again, all methods are called without any locks being held, unless 521otherwise noted. 522 523``create`` 524 called by the open(2) and creat(2) system calls. Only required 525 if you want to support regular files. The dentry you get should 526 not have an inode (i.e. it should be a negative dentry). Here 527 you will probably call d_instantiate() with the dentry and the 528 newly created inode 529 530``lookup`` 531 called when the VFS needs to look up an inode in a parent 532 directory. The name to look for is found in the dentry. This 533 method must call d_add() to insert the found inode into the 534 dentry. The "i_count" field in the inode structure should be 535 incremented. If the named inode does not exist a NULL inode 536 should be inserted into the dentry (this is called a negative 537 dentry). Returning an error code from this routine must only be 538 done on a real error, otherwise creating inodes with system 539 calls like create(2), mknod(2), mkdir(2) and so on will fail. 540 If you wish to overload the dentry methods then you should 541 initialise the "d_dop" field in the dentry; this is a pointer to 542 a struct "dentry_operations". This method is called with the 543 directory inode semaphore held 544 545``link`` 546 called by the link(2) system call. Only required if you want to 547 support hard links. You will probably need to call 548 d_instantiate() just as you would in the create() method 549 550``unlink`` 551 called by the unlink(2) system call. Only required if you want 552 to support deleting inodes 553 554``symlink`` 555 called by the symlink(2) system call. Only required if you want 556 to support symlinks. You will probably need to call 557 d_instantiate() just as you would in the create() method 558 559``mkdir`` 560 called by the mkdir(2) system call. Only required if you want 561 to support creating subdirectories. You will probably need to 562 call d_instantiate() just as you would in the create() method 563 564``rmdir`` 565 called by the rmdir(2) system call. Only required if you want 566 to support deleting subdirectories 567 568``mknod`` 569 called by the mknod(2) system call to create a device (char, 570 block) inode or a named pipe (FIFO) or socket. Only required if 571 you want to support creating these types of inodes. You will 572 probably need to call d_instantiate() just as you would in the 573 create() method 574 575``rename`` 576 called by the rename(2) system call to rename the object to have 577 the parent and name given by the second inode and dentry. 578 579 The filesystem must return -EINVAL for any unsupported or 580 unknown flags. Currently the following flags are implemented: 581 (1) RENAME_NOREPLACE: this flag indicates that if the target of 582 the rename exists the rename should fail with -EEXIST instead of 583 replacing the target. The VFS already checks for existence, so 584 for local filesystems the RENAME_NOREPLACE implementation is 585 equivalent to plain rename. 586 (2) RENAME_EXCHANGE: exchange source and target. Both must 587 exist; this is checked by the VFS. Unlike plain rename, source 588 and target may be of different type. 589 590``get_link`` 591 called by the VFS to follow a symbolic link to the inode it 592 points to. Only required if you want to support symbolic links. 593 This method returns the symlink body to traverse (and possibly 594 resets the current position with nd_jump_link()). If the body 595 won't go away until the inode is gone, nothing else is needed; 596 if it needs to be otherwise pinned, arrange for its release by 597 having get_link(..., ..., done) do set_delayed_call(done, 598 destructor, argument). In that case destructor(argument) will 599 be called once VFS is done with the body you've returned. May 600 be called in RCU mode; that is indicated by NULL dentry 601 argument. If request can't be handled without leaving RCU mode, 602 have it return ERR_PTR(-ECHILD). 603 604 If the filesystem stores the symlink target in ->i_link, the 605 VFS may use it directly without calling ->get_link(); however, 606 ->get_link() must still be provided. ->i_link must not be 607 freed until after an RCU grace period. Writing to ->i_link 608 post-iget() time requires a 'release' memory barrier. 609 610``readlink`` 611 this is now just an override for use by readlink(2) for the 612 cases when ->get_link uses nd_jump_link() or object is not in 613 fact a symlink. Normally filesystems should only implement 614 ->get_link for symlinks and readlink(2) will automatically use 615 that. 616 617``permission`` 618 called by the VFS to check for access rights on a POSIX-like 619 filesystem. 620 621 May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in 622 rcu-walk mode, the filesystem must check the permission without 623 blocking or storing to the inode. 624 625 If a situation is encountered that rcu-walk cannot handle, 626 return 627 -ECHILD and it will be called again in ref-walk mode. 628 629``setattr`` 630 called by the VFS to set attributes for a file. This method is 631 called by chmod(2) and related system calls. 632 633``getattr`` 634 called by the VFS to get attributes of a file. This method is 635 called by stat(2) and related system calls. 636 637``listxattr`` 638 called by the VFS to list all extended attributes for a given 639 file. This method is called by the listxattr(2) system call. 640 641``update_time`` 642 called by the VFS to update a specific time or the i_version of 643 an inode. If this is not defined the VFS will update the inode 644 itself and call mark_inode_dirty_sync. 645 646``atomic_open`` 647 called on the last component of an open. Using this optional 648 method the filesystem can look up, possibly create and open the 649 file in one atomic operation. If it wants to leave actual 650 opening to the caller (e.g. if the file turned out to be a 651 symlink, device, or just something filesystem won't do atomic 652 open for), it may signal this by returning finish_no_open(file, 653 dentry). This method is only called if the last component is 654 negative or needs lookup. Cached positive dentries are still 655 handled by f_op->open(). If the file was created, FMODE_CREATED 656 flag should be set in file->f_mode. In case of O_EXCL the 657 method must only succeed if the file didn't exist and hence 658 FMODE_CREATED shall always be set on success. 659 660``tmpfile`` 661 called in the end of O_TMPFILE open(). Optional, equivalent to 662 atomically creating, opening and unlinking a file in given 663 directory. On success needs to return with the file already 664 open; this can be done by calling finish_open_simple() right at 665 the end. 666 667``fileattr_get`` 668 called on ioctl(FS_IOC_GETFLAGS) and ioctl(FS_IOC_FSGETXATTR) to 669 retrieve miscellaneous file flags and attributes. Also called 670 before the relevant SET operation to check what is being changed 671 (in this case with i_rwsem locked exclusive). If unset, then 672 fall back to f_op->ioctl(). 673 674``fileattr_set`` 675 called on ioctl(FS_IOC_SETFLAGS) and ioctl(FS_IOC_FSSETXATTR) to 676 change miscellaneous file flags and attributes. Callers hold 677 i_rwsem exclusive. If unset, then fall back to f_op->ioctl(). 678 679 680The Address Space Object 681======================== 682 683The address space object is used to group and manage pages in the page 684cache. It can be used to keep track of the pages in a file (or anything 685else) and also track the mapping of sections of the file into process 686address spaces. 687 688There are a number of distinct yet related services that an 689address-space can provide. These include communicating memory pressure, 690page lookup by address, and keeping track of pages tagged as Dirty or 691Writeback. 692 693The first can be used independently to the others. The VM can try to 694either write dirty pages in order to clean them, or release clean pages 695in order to reuse them. To do this it can call the ->writepage method 696on dirty pages, and ->release_folio on clean folios with the private 697flag set. Clean pages without PagePrivate and with no external references 698will be released without notice being given to the address_space. 699 700To achieve this functionality, pages need to be placed on an LRU with 701lru_cache_add and mark_page_active needs to be called whenever the page 702is used. 703 704Pages are normally kept in a radix tree index by ->index. This tree 705maintains information about the PG_Dirty and PG_Writeback status of each 706page, so that pages with either of these flags can be found quickly. 707 708The Dirty tag is primarily used by mpage_writepages - the default 709->writepages method. It uses the tag to find dirty pages to call 710->writepage on. If mpage_writepages is not used (i.e. the address 711provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is almost 712unused. write_inode_now and sync_inode do use it (through 713__sync_single_inode) to check if ->writepages has been successful in 714writing out the whole address_space. 715 716The Writeback tag is used by filemap*wait* and sync_page* functions, via 717filemap_fdatawait_range, to wait for all writeback to complete. 718 719An address_space handler may attach extra information to a page, 720typically using the 'private' field in the 'struct page'. If such 721information is attached, the PG_Private flag should be set. This will 722cause various VM routines to make extra calls into the address_space 723handler to deal with that data. 724 725An address space acts as an intermediate between storage and 726application. Data is read into the address space a whole page at a 727time, and provided to the application either by copying of the page, or 728by memory-mapping the page. Data is written into the address space by 729the application, and then written-back to storage typically in whole 730pages, however the address_space has finer control of write sizes. 731 732The read process essentially only requires 'read_folio'. The write 733process is more complicated and uses write_begin/write_end or 734dirty_folio to write data into the address_space, and writepage and 735writepages to writeback data to storage. 736 737Adding and removing pages to/from an address_space is protected by the 738inode's i_mutex. 739 740When data is written to a page, the PG_Dirty flag should be set. It 741typically remains set until writepage asks for it to be written. This 742should clear PG_Dirty and set PG_Writeback. It can be actually written 743at any point after PG_Dirty is clear. Once it is known to be safe, 744PG_Writeback is cleared. 745 746Writeback makes use of a writeback_control structure to direct the 747operations. This gives the writepage and writepages operations some 748information about the nature of and reason for the writeback request, 749and the constraints under which it is being done. It is also used to 750return information back to the caller about the result of a writepage or 751writepages request. 752 753 754Handling errors during writeback 755-------------------------------- 756 757Most applications that do buffered I/O will periodically call a file 758synchronization call (fsync, fdatasync, msync or sync_file_range) to 759ensure that data written has made it to the backing store. When there 760is an error during writeback, they expect that error to be reported when 761a file sync request is made. After an error has been reported on one 762request, subsequent requests on the same file descriptor should return 7630, unless further writeback errors have occurred since the previous file 764syncronization. 765 766Ideally, the kernel would report errors only on file descriptions on 767which writes were done that subsequently failed to be written back. The 768generic pagecache infrastructure does not track the file descriptions 769that have dirtied each individual page however, so determining which 770file descriptors should get back an error is not possible. 771 772Instead, the generic writeback error tracking infrastructure in the 773kernel settles for reporting errors to fsync on all file descriptions 774that were open at the time that the error occurred. In a situation with 775multiple writers, all of them will get back an error on a subsequent 776fsync, even if all of the writes done through that particular file 777descriptor succeeded (or even if there were no writes on that file 778descriptor at all). 779 780Filesystems that wish to use this infrastructure should call 781mapping_set_error to record the error in the address_space when it 782occurs. Then, after writing back data from the pagecache in their 783file->fsync operation, they should call file_check_and_advance_wb_err to 784ensure that the struct file's error cursor has advanced to the correct 785point in the stream of errors emitted by the backing device(s). 786 787 788struct address_space_operations 789------------------------------- 790 791This describes how the VFS can manipulate mapping of a file to page 792cache in your filesystem. The following members are defined: 793 794.. code-block:: c 795 796 struct address_space_operations { 797 int (*writepage)(struct page *page, struct writeback_control *wbc); 798 int (*read_folio)(struct file *, struct folio *); 799 int (*writepages)(struct address_space *, struct writeback_control *); 800 bool (*dirty_folio)(struct address_space *, struct folio *); 801 void (*readahead)(struct readahead_control *); 802 int (*write_begin)(struct file *, struct address_space *mapping, 803 loff_t pos, unsigned len, 804 struct page **pagep, void **fsdata); 805 int (*write_end)(struct file *, struct address_space *mapping, 806 loff_t pos, unsigned len, unsigned copied, 807 struct page *page, void *fsdata); 808 sector_t (*bmap)(struct address_space *, sector_t); 809 void (*invalidate_folio) (struct folio *, size_t start, size_t len); 810 bool (*release_folio)(struct folio *, gfp_t); 811 void (*free_folio)(struct folio *); 812 ssize_t (*direct_IO)(struct kiocb *, struct iov_iter *iter); 813 int (*migrate_folio)(struct mapping *, struct folio *dst, 814 struct folio *src, enum migrate_mode); 815 int (*launder_folio) (struct folio *); 816 817 bool (*is_partially_uptodate) (struct folio *, size_t from, 818 size_t count); 819 void (*is_dirty_writeback)(struct folio *, bool *, bool *); 820 int (*error_remove_page) (struct mapping *mapping, struct page *page); 821 int (*swap_activate)(struct swap_info_struct *sis, struct file *f, sector_t *span) 822 int (*swap_deactivate)(struct file *); 823 int (*swap_rw)(struct kiocb *iocb, struct iov_iter *iter); 824 }; 825 826``writepage`` 827 called by the VM to write a dirty page to backing store. This 828 may happen for data integrity reasons (i.e. 'sync'), or to free 829 up memory (flush). The difference can be seen in 830 wbc->sync_mode. The PG_Dirty flag has been cleared and 831 PageLocked is true. writepage should start writeout, should set 832 PG_Writeback, and should make sure the page is unlocked, either 833 synchronously or asynchronously when the write operation 834 completes. 835 836 If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to 837 try too hard if there are problems, and may choose to write out 838 other pages from the mapping if that is easier (e.g. due to 839 internal dependencies). If it chooses not to start writeout, it 840 should return AOP_WRITEPAGE_ACTIVATE so that the VM will not 841 keep calling ->writepage on that page. 842 843 See the file "Locking" for more details. 844 845``read_folio`` 846 Called by the page cache to read a folio from the backing store. 847 The 'file' argument supplies authentication information to network 848 filesystems, and is generally not used by block based filesystems. 849 It may be NULL if the caller does not have an open file (eg if 850 the kernel is performing a read for itself rather than on behalf 851 of a userspace process with an open file). 852 853 If the mapping does not support large folios, the folio will 854 contain a single page. The folio will be locked when read_folio 855 is called. If the read completes successfully, the folio should 856 be marked uptodate. The filesystem should unlock the folio 857 once the read has completed, whether it was successful or not. 858 The filesystem does not need to modify the refcount on the folio; 859 the page cache holds a reference count and that will not be 860 released until the folio is unlocked. 861 862 Filesystems may implement ->read_folio() synchronously. 863 In normal operation, folios are read through the ->readahead() 864 method. Only if this fails, or if the caller needs to wait for 865 the read to complete will the page cache call ->read_folio(). 866 Filesystems should not attempt to perform their own readahead 867 in the ->read_folio() operation. 868 869 If the filesystem cannot perform the read at this time, it can 870 unlock the folio, do whatever action it needs to ensure that the 871 read will succeed in the future and return AOP_TRUNCATED_PAGE. 872 In this case, the caller should look up the folio, lock it, 873 and call ->read_folio again. 874 875 Callers may invoke the ->read_folio() method directly, but using 876 read_mapping_folio() will take care of locking, waiting for the 877 read to complete and handle cases such as AOP_TRUNCATED_PAGE. 878 879``writepages`` 880 called by the VM to write out pages associated with the 881 address_space object. If wbc->sync_mode is WB_SYNC_ALL, then 882 the writeback_control will specify a range of pages that must be 883 written out. If it is WB_SYNC_NONE, then a nr_to_write is 884 given and that many pages should be written if possible. If no 885 ->writepages is given, then mpage_writepages is used instead. 886 This will choose pages from the address space that are tagged as 887 DIRTY and will pass them to ->writepage. 888 889``dirty_folio`` 890 called by the VM to mark a folio as dirty. This is particularly 891 needed if an address space attaches private data to a folio, and 892 that data needs to be updated when a folio is dirtied. This is 893 called, for example, when a memory mapped page gets modified. 894 If defined, it should set the folio dirty flag, and the 895 PAGECACHE_TAG_DIRTY search mark in i_pages. 896 897``readahead`` 898 Called by the VM to read pages associated with the address_space 899 object. The pages are consecutive in the page cache and are 900 locked. The implementation should decrement the page refcount 901 after starting I/O on each page. Usually the page will be 902 unlocked by the I/O completion handler. The set of pages are 903 divided into some sync pages followed by some async pages, 904 rac->ra->async_size gives the number of async pages. The 905 filesystem should attempt to read all sync pages but may decide 906 to stop once it reaches the async pages. If it does decide to 907 stop attempting I/O, it can simply return. The caller will 908 remove the remaining pages from the address space, unlock them 909 and decrement the page refcount. Set PageUptodate if the I/O 910 completes successfully. Setting PageError on any page will be 911 ignored; simply unlock the page if an I/O error occurs. 912 913``write_begin`` 914 Called by the generic buffered write code to ask the filesystem 915 to prepare to write len bytes at the given offset in the file. 916 The address_space should check that the write will be able to 917 complete, by allocating space if necessary and doing any other 918 internal housekeeping. If the write will update parts of any 919 basic-blocks on storage, then those blocks should be pre-read 920 (if they haven't been read already) so that the updated blocks 921 can be written out properly. 922 923 The filesystem must return the locked pagecache page for the 924 specified offset, in ``*pagep``, for the caller to write into. 925 926 It must be able to cope with short writes (where the length 927 passed to write_begin is greater than the number of bytes copied 928 into the page). 929 930 A void * may be returned in fsdata, which then gets passed into 931 write_end. 932 933 Returns 0 on success; < 0 on failure (which is the error code), 934 in which case write_end is not called. 935 936``write_end`` 937 After a successful write_begin, and data copy, write_end must be 938 called. len is the original len passed to write_begin, and 939 copied is the amount that was able to be copied. 940 941 The filesystem must take care of unlocking the page and 942 releasing it refcount, and updating i_size. 943 944 Returns < 0 on failure, otherwise the number of bytes (<= 945 'copied') that were able to be copied into pagecache. 946 947``bmap`` 948 called by the VFS to map a logical block offset within object to 949 physical block number. This method is used by the FIBMAP ioctl 950 and for working with swap-files. To be able to swap to a file, 951 the file must have a stable mapping to a block device. The swap 952 system does not go through the filesystem but instead uses bmap 953 to find out where the blocks in the file are and uses those 954 addresses directly. 955 956``invalidate_folio`` 957 If a folio has private data, then invalidate_folio will be 958 called when part or all of the folio is to be removed from the 959 address space. This generally corresponds to either a 960 truncation, punch hole or a complete invalidation of the address 961 space (in the latter case 'offset' will always be 0 and 'length' 962 will be folio_size()). Any private data associated with the folio 963 should be updated to reflect this truncation. If offset is 0 964 and length is folio_size(), then the private data should be 965 released, because the folio must be able to be completely 966 discarded. This may be done by calling the ->release_folio 967 function, but in this case the release MUST succeed. 968 969``release_folio`` 970 release_folio is called on folios with private data to tell the 971 filesystem that the folio is about to be freed. ->release_folio 972 should remove any private data from the folio and clear the 973 private flag. If release_folio() fails, it should return false. 974 release_folio() is used in two distinct though related cases. 975 The first is when the VM wants to free a clean folio with no 976 active users. If ->release_folio succeeds, the folio will be 977 removed from the address_space and be freed. 978 979 The second case is when a request has been made to invalidate 980 some or all folios in an address_space. This can happen 981 through the fadvise(POSIX_FADV_DONTNEED) system call or by the 982 filesystem explicitly requesting it as nfs and 9p do (when they 983 believe the cache may be out of date with storage) by calling 984 invalidate_inode_pages2(). If the filesystem makes such a call, 985 and needs to be certain that all folios are invalidated, then 986 its release_folio will need to ensure this. Possibly it can 987 clear the uptodate flag if it cannot free private data yet. 988 989``free_folio`` 990 free_folio is called once the folio is no longer visible in the 991 page cache in order to allow the cleanup of any private data. 992 Since it may be called by the memory reclaimer, it should not 993 assume that the original address_space mapping still exists, and 994 it should not block. 995 996``direct_IO`` 997 called by the generic read/write routines to perform direct_IO - 998 that is IO requests which bypass the page cache and transfer 999 data directly between the storage and the application's address 1000 space. 1001 1002``migrate_folio`` 1003 This is used to compact the physical memory usage. If the VM 1004 wants to relocate a folio (maybe from a memory device that is 1005 signalling imminent failure) it will pass a new folio and an old 1006 folio to this function. migrate_folio should transfer any private 1007 data across and update any references that it has to the folio. 1008 1009``launder_folio`` 1010 Called before freeing a folio - it writes back the dirty folio. 1011 To prevent redirtying the folio, it is kept locked during the 1012 whole operation. 1013 1014``is_partially_uptodate`` 1015 Called by the VM when reading a file through the pagecache when 1016 the underlying blocksize is smaller than the size of the folio. 1017 If the required block is up to date then the read can complete 1018 without needing I/O to bring the whole page up to date. 1019 1020``is_dirty_writeback`` 1021 Called by the VM when attempting to reclaim a folio. The VM uses 1022 dirty and writeback information to determine if it needs to 1023 stall to allow flushers a chance to complete some IO. 1024 Ordinarily it can use folio_test_dirty and folio_test_writeback but 1025 some filesystems have more complex state (unstable folios in NFS 1026 prevent reclaim) or do not set those flags due to locking 1027 problems. This callback allows a filesystem to indicate to the 1028 VM if a folio should be treated as dirty or writeback for the 1029 purposes of stalling. 1030 1031``error_remove_page`` 1032 normally set to generic_error_remove_page if truncation is ok 1033 for this address space. Used for memory failure handling. 1034 Setting this implies you deal with pages going away under you, 1035 unless you have them locked or reference counts increased. 1036 1037``swap_activate`` 1038 1039 Called to prepare the given file for swap. It should perform 1040 any validation and preparation necessary to ensure that writes 1041 can be performed with minimal memory allocation. It should call 1042 add_swap_extent(), or the helper iomap_swapfile_activate(), and 1043 return the number of extents added. If IO should be submitted 1044 through ->swap_rw(), it should set SWP_FS_OPS, otherwise IO will 1045 be submitted directly to the block device ``sis->bdev``. 1046 1047``swap_deactivate`` 1048 Called during swapoff on files where swap_activate was 1049 successful. 1050 1051``swap_rw`` 1052 Called to read or write swap pages when SWP_FS_OPS is set. 1053 1054The File Object 1055=============== 1056 1057A file object represents a file opened by a process. This is also known 1058as an "open file description" in POSIX parlance. 1059 1060 1061struct file_operations 1062---------------------- 1063 1064This describes how the VFS can manipulate an open file. As of kernel 10654.18, the following members are defined: 1066 1067.. code-block:: c 1068 1069 struct file_operations { 1070 struct module *owner; 1071 loff_t (*llseek) (struct file *, loff_t, int); 1072 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); 1073 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); 1074 ssize_t (*read_iter) (struct kiocb *, struct iov_iter *); 1075 ssize_t (*write_iter) (struct kiocb *, struct iov_iter *); 1076 int (*iopoll)(struct kiocb *kiocb, bool spin); 1077 int (*iterate) (struct file *, struct dir_context *); 1078 int (*iterate_shared) (struct file *, struct dir_context *); 1079 __poll_t (*poll) (struct file *, struct poll_table_struct *); 1080 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); 1081 long (*compat_ioctl) (struct file *, unsigned int, unsigned long); 1082 int (*mmap) (struct file *, struct vm_area_struct *); 1083 int (*open) (struct inode *, struct file *); 1084 int (*flush) (struct file *, fl_owner_t id); 1085 int (*release) (struct inode *, struct file *); 1086 int (*fsync) (struct file *, loff_t, loff_t, int datasync); 1087 int (*fasync) (int, struct file *, int); 1088 int (*lock) (struct file *, int, struct file_lock *); 1089 ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int); 1090 unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long); 1091 int (*check_flags)(int); 1092 int (*flock) (struct file *, int, struct file_lock *); 1093 ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, loff_t *, size_t, unsigned int); 1094 ssize_t (*splice_read)(struct file *, loff_t *, struct pipe_inode_info *, size_t, unsigned int); 1095 int (*setlease)(struct file *, long, struct file_lock **, void **); 1096 long (*fallocate)(struct file *file, int mode, loff_t offset, 1097 loff_t len); 1098 void (*show_fdinfo)(struct seq_file *m, struct file *f); 1099 #ifndef CONFIG_MMU 1100 unsigned (*mmap_capabilities)(struct file *); 1101 #endif 1102 ssize_t (*copy_file_range)(struct file *, loff_t, struct file *, loff_t, size_t, unsigned int); 1103 loff_t (*remap_file_range)(struct file *file_in, loff_t pos_in, 1104 struct file *file_out, loff_t pos_out, 1105 loff_t len, unsigned int remap_flags); 1106 int (*fadvise)(struct file *, loff_t, loff_t, int); 1107 }; 1108 1109Again, all methods are called without any locks being held, unless 1110otherwise noted. 1111 1112``llseek`` 1113 called when the VFS needs to move the file position index 1114 1115``read`` 1116 called by read(2) and related system calls 1117 1118``read_iter`` 1119 possibly asynchronous read with iov_iter as destination 1120 1121``write`` 1122 called by write(2) and related system calls 1123 1124``write_iter`` 1125 possibly asynchronous write with iov_iter as source 1126 1127``iopoll`` 1128 called when aio wants to poll for completions on HIPRI iocbs 1129 1130``iterate`` 1131 called when the VFS needs to read the directory contents 1132 1133``iterate_shared`` 1134 called when the VFS needs to read the directory contents when 1135 filesystem supports concurrent dir iterators 1136 1137``poll`` 1138 called by the VFS when a process wants to check if there is 1139 activity on this file and (optionally) go to sleep until there 1140 is activity. Called by the select(2) and poll(2) system calls 1141 1142``unlocked_ioctl`` 1143 called by the ioctl(2) system call. 1144 1145``compat_ioctl`` 1146 called by the ioctl(2) system call when 32 bit system calls are 1147 used on 64 bit kernels. 1148 1149``mmap`` 1150 called by the mmap(2) system call 1151 1152``open`` 1153 called by the VFS when an inode should be opened. When the VFS 1154 opens a file, it creates a new "struct file". It then calls the 1155 open method for the newly allocated file structure. You might 1156 think that the open method really belongs in "struct 1157 inode_operations", and you may be right. I think it's done the 1158 way it is because it makes filesystems simpler to implement. 1159 The open() method is a good place to initialize the 1160 "private_data" member in the file structure if you want to point 1161 to a device structure 1162 1163``flush`` 1164 called by the close(2) system call to flush a file 1165 1166``release`` 1167 called when the last reference to an open file is closed 1168 1169``fsync`` 1170 called by the fsync(2) system call. Also see the section above 1171 entitled "Handling errors during writeback". 1172 1173``fasync`` 1174 called by the fcntl(2) system call when asynchronous 1175 (non-blocking) mode is enabled for a file 1176 1177``lock`` 1178 called by the fcntl(2) system call for F_GETLK, F_SETLK, and 1179 F_SETLKW commands 1180 1181``get_unmapped_area`` 1182 called by the mmap(2) system call 1183 1184``check_flags`` 1185 called by the fcntl(2) system call for F_SETFL command 1186 1187``flock`` 1188 called by the flock(2) system call 1189 1190``splice_write`` 1191 called by the VFS to splice data from a pipe to a file. This 1192 method is used by the splice(2) system call 1193 1194``splice_read`` 1195 called by the VFS to splice data from file to a pipe. This 1196 method is used by the splice(2) system call 1197 1198``setlease`` 1199 called by the VFS to set or release a file lock lease. setlease 1200 implementations should call generic_setlease to record or remove 1201 the lease in the inode after setting it. 1202 1203``fallocate`` 1204 called by the VFS to preallocate blocks or punch a hole. 1205 1206``copy_file_range`` 1207 called by the copy_file_range(2) system call. 1208 1209``remap_file_range`` 1210 called by the ioctl(2) system call for FICLONERANGE and FICLONE 1211 and FIDEDUPERANGE commands to remap file ranges. An 1212 implementation should remap len bytes at pos_in of the source 1213 file into the dest file at pos_out. Implementations must handle 1214 callers passing in len == 0; this means "remap to the end of the 1215 source file". The return value should the number of bytes 1216 remapped, or the usual negative error code if errors occurred 1217 before any bytes were remapped. The remap_flags parameter 1218 accepts REMAP_FILE_* flags. If REMAP_FILE_DEDUP is set then the 1219 implementation must only remap if the requested file ranges have 1220 identical contents. If REMAP_FILE_CAN_SHORTEN is set, the caller is 1221 ok with the implementation shortening the request length to 1222 satisfy alignment or EOF requirements (or any other reason). 1223 1224``fadvise`` 1225 possibly called by the fadvise64() system call. 1226 1227Note that the file operations are implemented by the specific 1228filesystem in which the inode resides. When opening a device node 1229(character or block special) most filesystems will call special 1230support routines in the VFS which will locate the required device 1231driver information. These support routines replace the filesystem file 1232operations with those for the device driver, and then proceed to call 1233the new open() method for the file. This is how opening a device file 1234in the filesystem eventually ends up calling the device driver open() 1235method. 1236 1237 1238Directory Entry Cache (dcache) 1239============================== 1240 1241 1242struct dentry_operations 1243------------------------ 1244 1245This describes how a filesystem can overload the standard dentry 1246operations. Dentries and the dcache are the domain of the VFS and the 1247individual filesystem implementations. Device drivers have no business 1248here. These methods may be set to NULL, as they are either optional or 1249the VFS uses a default. As of kernel 2.6.22, the following members are 1250defined: 1251 1252.. code-block:: c 1253 1254 struct dentry_operations { 1255 int (*d_revalidate)(struct dentry *, unsigned int); 1256 int (*d_weak_revalidate)(struct dentry *, unsigned int); 1257 int (*d_hash)(const struct dentry *, struct qstr *); 1258 int (*d_compare)(const struct dentry *, 1259 unsigned int, const char *, const struct qstr *); 1260 int (*d_delete)(const struct dentry *); 1261 int (*d_init)(struct dentry *); 1262 void (*d_release)(struct dentry *); 1263 void (*d_iput)(struct dentry *, struct inode *); 1264 char *(*d_dname)(struct dentry *, char *, int); 1265 struct vfsmount *(*d_automount)(struct path *); 1266 int (*d_manage)(const struct path *, bool); 1267 struct dentry *(*d_real)(struct dentry *, const struct inode *); 1268 }; 1269 1270``d_revalidate`` 1271 called when the VFS needs to revalidate a dentry. This is 1272 called whenever a name look-up finds a dentry in the dcache. 1273 Most local filesystems leave this as NULL, because all their 1274 dentries in the dcache are valid. Network filesystems are 1275 different since things can change on the server without the 1276 client necessarily being aware of it. 1277 1278 This function should return a positive value if the dentry is 1279 still valid, and zero or a negative error code if it isn't. 1280 1281 d_revalidate may be called in rcu-walk mode (flags & 1282 LOOKUP_RCU). If in rcu-walk mode, the filesystem must 1283 revalidate the dentry without blocking or storing to the dentry, 1284 d_parent and d_inode should not be used without care (because 1285 they can change and, in d_inode case, even become NULL under 1286 us). 1287 1288 If a situation is encountered that rcu-walk cannot handle, 1289 return 1290 -ECHILD and it will be called again in ref-walk mode. 1291 1292``d_weak_revalidate`` 1293 called when the VFS needs to revalidate a "jumped" dentry. This 1294 is called when a path-walk ends at dentry that was not acquired 1295 by doing a lookup in the parent directory. This includes "/", 1296 "." and "..", as well as procfs-style symlinks and mountpoint 1297 traversal. 1298 1299 In this case, we are less concerned with whether the dentry is 1300 still fully correct, but rather that the inode is still valid. 1301 As with d_revalidate, most local filesystems will set this to 1302 NULL since their dcache entries are always valid. 1303 1304 This function has the same return code semantics as 1305 d_revalidate. 1306 1307 d_weak_revalidate is only called after leaving rcu-walk mode. 1308 1309``d_hash`` 1310 called when the VFS adds a dentry to the hash table. The first 1311 dentry passed to d_hash is the parent directory that the name is 1312 to be hashed into. 1313 1314 Same locking and synchronisation rules as d_compare regarding 1315 what is safe to dereference etc. 1316 1317``d_compare`` 1318 called to compare a dentry name with a given name. The first 1319 dentry is the parent of the dentry to be compared, the second is 1320 the child dentry. len and name string are properties of the 1321 dentry to be compared. qstr is the name to compare it with. 1322 1323 Must be constant and idempotent, and should not take locks if 1324 possible, and should not or store into the dentry. Should not 1325 dereference pointers outside the dentry without lots of care 1326 (eg. d_parent, d_inode, d_name should not be used). 1327 1328 However, our vfsmount is pinned, and RCU held, so the dentries 1329 and inodes won't disappear, neither will our sb or filesystem 1330 module. ->d_sb may be used. 1331 1332 It is a tricky calling convention because it needs to be called 1333 under "rcu-walk", ie. without any locks or references on things. 1334 1335``d_delete`` 1336 called when the last reference to a dentry is dropped and the 1337 dcache is deciding whether or not to cache it. Return 1 to 1338 delete immediately, or 0 to cache the dentry. Default is NULL 1339 which means to always cache a reachable dentry. d_delete must 1340 be constant and idempotent. 1341 1342``d_init`` 1343 called when a dentry is allocated 1344 1345``d_release`` 1346 called when a dentry is really deallocated 1347 1348``d_iput`` 1349 called when a dentry loses its inode (just prior to its being 1350 deallocated). The default when this is NULL is that the VFS 1351 calls iput(). If you define this method, you must call iput() 1352 yourself 1353 1354``d_dname`` 1355 called when the pathname of a dentry should be generated. 1356 Useful for some pseudo filesystems (sockfs, pipefs, ...) to 1357 delay pathname generation. (Instead of doing it when dentry is 1358 created, it's done only when the path is needed.). Real 1359 filesystems probably dont want to use it, because their dentries 1360 are present in global dcache hash, so their hash should be an 1361 invariant. As no lock is held, d_dname() should not try to 1362 modify the dentry itself, unless appropriate SMP safety is used. 1363 CAUTION : d_path() logic is quite tricky. The correct way to 1364 return for example "Hello" is to put it at the end of the 1365 buffer, and returns a pointer to the first char. 1366 dynamic_dname() helper function is provided to take care of 1367 this. 1368 1369 Example : 1370 1371.. code-block:: c 1372 1373 static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) 1374 { 1375 return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", 1376 dentry->d_inode->i_ino); 1377 } 1378 1379``d_automount`` 1380 called when an automount dentry is to be traversed (optional). 1381 This should create a new VFS mount record and return the record 1382 to the caller. The caller is supplied with a path parameter 1383 giving the automount directory to describe the automount target 1384 and the parent VFS mount record to provide inheritable mount 1385 parameters. NULL should be returned if someone else managed to 1386 make the automount first. If the vfsmount creation failed, then 1387 an error code should be returned. If -EISDIR is returned, then 1388 the directory will be treated as an ordinary directory and 1389 returned to pathwalk to continue walking. 1390 1391 If a vfsmount is returned, the caller will attempt to mount it 1392 on the mountpoint and will remove the vfsmount from its 1393 expiration list in the case of failure. The vfsmount should be 1394 returned with 2 refs on it to prevent automatic expiration - the 1395 caller will clean up the additional ref. 1396 1397 This function is only used if DCACHE_NEED_AUTOMOUNT is set on 1398 the dentry. This is set by __d_instantiate() if S_AUTOMOUNT is 1399 set on the inode being added. 1400 1401``d_manage`` 1402 called to allow the filesystem to manage the transition from a 1403 dentry (optional). This allows autofs, for example, to hold up 1404 clients waiting to explore behind a 'mountpoint' while letting 1405 the daemon go past and construct the subtree there. 0 should be 1406 returned to let the calling process continue. -EISDIR can be 1407 returned to tell pathwalk to use this directory as an ordinary 1408 directory and to ignore anything mounted on it and not to check 1409 the automount flag. Any other error code will abort pathwalk 1410 completely. 1411 1412 If the 'rcu_walk' parameter is true, then the caller is doing a 1413 pathwalk in RCU-walk mode. Sleeping is not permitted in this 1414 mode, and the caller can be asked to leave it and call again by 1415 returning -ECHILD. -EISDIR may also be returned to tell 1416 pathwalk to ignore d_automount or any mounts. 1417 1418 This function is only used if DCACHE_MANAGE_TRANSIT is set on 1419 the dentry being transited from. 1420 1421``d_real`` 1422 overlay/union type filesystems implement this method to return 1423 one of the underlying dentries hidden by the overlay. It is 1424 used in two different modes: 1425 1426 Called from file_dentry() it returns the real dentry matching 1427 the inode argument. The real dentry may be from a lower layer 1428 already copied up, but still referenced from the file. This 1429 mode is selected with a non-NULL inode argument. 1430 1431 With NULL inode the topmost real underlying dentry is returned. 1432 1433Each dentry has a pointer to its parent dentry, as well as a hash list 1434of child dentries. Child dentries are basically like files in a 1435directory. 1436 1437 1438Directory Entry Cache API 1439-------------------------- 1440 1441There are a number of functions defined which permit a filesystem to 1442manipulate dentries: 1443 1444``dget`` 1445 open a new handle for an existing dentry (this just increments 1446 the usage count) 1447 1448``dput`` 1449 close a handle for a dentry (decrements the usage count). If 1450 the usage count drops to 0, and the dentry is still in its 1451 parent's hash, the "d_delete" method is called to check whether 1452 it should be cached. If it should not be cached, or if the 1453 dentry is not hashed, it is deleted. Otherwise cached dentries 1454 are put into an LRU list to be reclaimed on memory shortage. 1455 1456``d_drop`` 1457 this unhashes a dentry from its parents hash list. A subsequent 1458 call to dput() will deallocate the dentry if its usage count 1459 drops to 0 1460 1461``d_delete`` 1462 delete a dentry. If there are no other open references to the 1463 dentry then the dentry is turned into a negative dentry (the 1464 d_iput() method is called). If there are other references, then 1465 d_drop() is called instead 1466 1467``d_add`` 1468 add a dentry to its parents hash list and then calls 1469 d_instantiate() 1470 1471``d_instantiate`` 1472 add a dentry to the alias hash list for the inode and updates 1473 the "d_inode" member. The "i_count" member in the inode 1474 structure should be set/incremented. If the inode pointer is 1475 NULL, the dentry is called a "negative dentry". This function 1476 is commonly called when an inode is created for an existing 1477 negative dentry 1478 1479``d_lookup`` 1480 look up a dentry given its parent and path name component It 1481 looks up the child of that given name from the dcache hash 1482 table. If it is found, the reference count is incremented and 1483 the dentry is returned. The caller must use dput() to free the 1484 dentry when it finishes using it. 1485 1486 1487Mount Options 1488============= 1489 1490 1491Parsing options 1492--------------- 1493 1494On mount and remount the filesystem is passed a string containing a 1495comma separated list of mount options. The options can have either of 1496these forms: 1497 1498 option 1499 option=value 1500 1501The <linux/parser.h> header defines an API that helps parse these 1502options. There are plenty of examples on how to use it in existing 1503filesystems. 1504 1505 1506Showing options 1507--------------- 1508 1509If a filesystem accepts mount options, it must define show_options() to 1510show all the currently active options. The rules are: 1511 1512 - options MUST be shown which are not default or their values differ 1513 from the default 1514 1515 - options MAY be shown which are enabled by default or have their 1516 default value 1517 1518Options used only internally between a mount helper and the kernel (such 1519as file descriptors), or which only have an effect during the mounting 1520(such as ones controlling the creation of a journal) are exempt from the 1521above rules. 1522 1523The underlying reason for the above rules is to make sure, that a mount 1524can be accurately replicated (e.g. umounting and mounting again) based 1525on the information found in /proc/mounts. 1526 1527 1528Resources 1529========= 1530 1531(Note some of these resources are not up-to-date with the latest kernel 1532 version.) 1533 1534Creating Linux virtual filesystems. 2002 1535 <https://lwn.net/Articles/13325/> 1536 1537The Linux Virtual File-system Layer by Neil Brown. 1999 1538 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> 1539 1540A tour of the Linux VFS by Michael K. Johnson. 1996 1541 <https://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> 1542 1543A small trail through the Linux kernel by Andries Brouwer. 2001 1544 <https://www.win.tue.nl/~aeb/linux/vfs/trail.html> 1545