linux/Documentation/filesystems/vfs.txt
<<
>>
Prefs
   1
   2              Overview of the Linux Virtual File System
   3
   4        Original author: Richard Gooch <rgooch@atnf.csiro.au>
   5
   6                  Last updated on June 24, 2007.
   7
   8  Copyright (C) 1999 Richard Gooch
   9  Copyright (C) 2005 Pekka Enberg
  10
  11  This file is released under the GPLv2.
  12
  13
  14Introduction
  15============
  16
  17The Virtual File System (also known as the Virtual Filesystem Switch)
  18is the software layer in the kernel that provides the filesystem
  19interface to userspace programs. It also provides an abstraction
  20within the kernel which allows different filesystem implementations to
  21coexist.
  22
  23VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so
  24on are called from a process context. Filesystem locking is described
  25in the document Documentation/filesystems/Locking.
  26
  27
  28Directory Entry Cache (dcache)
  29------------------------------
  30
  31The VFS implements the open(2), stat(2), chmod(2), and similar system
  32calls. The pathname argument that is passed to them is used by the VFS
  33to search through the directory entry cache (also known as the dentry
  34cache or dcache). This provides a very fast look-up mechanism to
  35translate a pathname (filename) into a specific dentry. Dentries live
  36in RAM and are never saved to disc: they exist only for performance.
  37
  38The dentry cache is meant to be a view into your entire filespace. As
  39most computers cannot fit all dentries in the RAM at the same time,
  40some bits of the cache are missing. In order to resolve your pathname
  41into a dentry, the VFS may have to resort to creating dentries along
  42the way, and then loading the inode. This is done by looking up the
  43inode.
  44
  45
  46The Inode Object
  47----------------
  48
  49An individual dentry usually has a pointer to an inode. Inodes are
  50filesystem objects such as regular files, directories, FIFOs and other
  51beasts.  They live either on the disc (for block device filesystems)
  52or in the memory (for pseudo filesystems). Inodes that live on the
  53disc are copied into the memory when required and changes to the inode
  54are written back to disc. A single inode can be pointed to by multiple
  55dentries (hard links, for example, do this).
  56
  57To look up an inode requires that the VFS calls the lookup() method of
  58the parent directory inode. This method is installed by the specific
  59filesystem implementation that the inode lives in. Once the VFS has
  60the required dentry (and hence the inode), we can do all those boring
  61things like open(2) the file, or stat(2) it to peek at the inode
  62data. The stat(2) operation is fairly simple: once the VFS has the
  63dentry, it peeks at the inode data and passes some of it back to
  64userspace.
  65
  66
  67The File Object
  68---------------
  69
  70Opening a file requires another operation: allocation of a file
  71structure (this is the kernel-side implementation of file
  72descriptors). The freshly allocated file structure is initialized with
  73a pointer to the dentry and a set of file operation member functions.
  74These are taken from the inode data. The open() file method is then
  75called so the specific filesystem implementation can do its work. You
  76can see that this is another switch performed by the VFS. The file
  77structure is placed into the file descriptor table for the process.
  78
  79Reading, writing and closing files (and other assorted VFS operations)
  80is done by using the userspace file descriptor to grab the appropriate
  81file structure, and then calling the required file structure method to
  82do whatever is required. For as long as the file is open, it keeps the
  83dentry in use, which in turn means that the VFS inode is still in use.
  84
  85
  86Registering and Mounting a Filesystem
  87=====================================
  88
  89To register and unregister a filesystem, use the following API
  90functions:
  91
  92   #include <linux/fs.h>
  93
  94   extern int register_filesystem(struct file_system_type *);
  95   extern int unregister_filesystem(struct file_system_type *);
  96
  97The passed struct file_system_type describes your filesystem. When a
  98request is made to mount a filesystem onto a directory in your namespace,
  99the VFS will call the appropriate mount() method for the specific
 100filesystem.  New vfsmount referring to the tree returned by ->mount()
 101will be attached to the mountpoint, so that when pathname resolution
 102reaches the mountpoint it will jump into the root of that vfsmount.
 103
 104You can see all filesystems that are registered to the kernel in the
 105file /proc/filesystems.
 106
 107
 108struct file_system_type
 109-----------------------
 110
 111This describes the filesystem. As of kernel 2.6.39, the following
 112members are defined:
 113
 114struct file_system_type {
 115        const char *name;
 116        int fs_flags;
 117        struct dentry *(*mount) (struct file_system_type *, int,
 118                       const char *, void *);
 119        void (*kill_sb) (struct super_block *);
 120        struct module *owner;
 121        struct file_system_type * next;
 122        struct list_head fs_supers;
 123        struct lock_class_key s_lock_key;
 124        struct lock_class_key s_umount_key;
 125};
 126
 127  name: the name of the filesystem type, such as "ext2", "iso9660",
 128        "msdos" and so on
 129
 130  fs_flags: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.)
 131
 132  mount: the method to call when a new instance of this
 133        filesystem should be mounted
 134
 135  kill_sb: the method to call when an instance of this filesystem
 136        should be shut down
 137
 138  owner: for internal VFS use: you should initialize this to THIS_MODULE in
 139        most cases.
 140
 141  next: for internal VFS use: you should initialize this to NULL
 142
 143  s_lock_key, s_umount_key: lockdep-specific
 144
 145The mount() method has the following arguments:
 146
 147  struct file_system_type *fs_type: describes the filesystem, partly initialized
 148        by the specific filesystem code
 149
 150  int flags: mount flags
 151
 152  const char *dev_name: the device name we are mounting.
 153
 154  void *data: arbitrary mount options, usually comes as an ASCII
 155        string (see "Mount Options" section)
 156
 157The mount() method must return the root dentry of the tree requested by
 158caller.  An active reference to its superblock must be grabbed and the
 159superblock must be locked.  On failure it should return ERR_PTR(error).
 160
 161The arguments match those of mount(2) and their interpretation
 162depends on filesystem type.  E.g. for block filesystems, dev_name is
 163interpreted as block device name, that device is opened and if it
 164contains a suitable filesystem image the method creates and initializes
 165struct super_block accordingly, returning its root dentry to caller.
 166
 167->mount() may choose to return a subtree of existing filesystem - it
 168doesn't have to create a new one.  The main result from the caller's
 169point of view is a reference to dentry at the root of (sub)tree to
 170be attached; creation of new superblock is a common side effect.
 171
 172The most interesting member of the superblock structure that the
 173mount() method fills in is the "s_op" field. This is a pointer to
 174a "struct super_operations" which describes the next level of the
 175filesystem implementation.
 176
 177Usually, a filesystem uses one of the generic mount() implementations
 178and provides a fill_super() callback instead. The generic variants are:
 179
 180  mount_bdev: mount a filesystem residing on a block device
 181
 182  mount_nodev: mount a filesystem that is not backed by a device
 183
 184  mount_single: mount a filesystem which shares the instance between
 185        all mounts
 186
 187A fill_super() callback implementation has the following arguments:
 188
 189  struct super_block *sb: the superblock structure. The callback
 190        must initialize this properly.
 191
 192  void *data: arbitrary mount options, usually comes as an ASCII
 193        string (see "Mount Options" section)
 194
 195  int silent: whether or not to be silent on error
 196
 197
 198The Superblock Object
 199=====================
 200
 201A superblock object represents a mounted filesystem.
 202
 203
 204struct super_operations
 205-----------------------
 206
 207This describes how the VFS can manipulate the superblock of your
 208filesystem. As of kernel 2.6.22, the following members are defined:
 209
 210struct super_operations {
 211        struct inode *(*alloc_inode)(struct super_block *sb);
 212        void (*destroy_inode)(struct inode *);
 213
 214        void (*dirty_inode) (struct inode *, int flags);
 215        int (*write_inode) (struct inode *, int);
 216        void (*drop_inode) (struct inode *);
 217        void (*delete_inode) (struct inode *);
 218        void (*put_super) (struct super_block *);
 219        int (*sync_fs)(struct super_block *sb, int wait);
 220        int (*freeze_fs) (struct super_block *);
 221        int (*unfreeze_fs) (struct super_block *);
 222        int (*statfs) (struct dentry *, struct kstatfs *);
 223        int (*remount_fs) (struct super_block *, int *, char *);
 224        void (*clear_inode) (struct inode *);
 225        void (*umount_begin) (struct super_block *);
 226
 227        int (*show_options)(struct seq_file *, struct dentry *);
 228
 229        ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
 230        ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
 231        int (*nr_cached_objects)(struct super_block *);
 232        void (*free_cached_objects)(struct super_block *, int);
 233};
 234
 235All methods are called without any locks being held, unless otherwise
 236noted. This means that most methods can block safely. All methods are
 237only called from a process context (i.e. not from an interrupt handler
 238or bottom half).
 239
 240  alloc_inode: this method is called by inode_alloc() to allocate memory
 241        for struct inode and initialize it.  If this function is not
 242        defined, a simple 'struct inode' is allocated.  Normally
 243        alloc_inode will be used to allocate a larger structure which
 244        contains a 'struct inode' embedded within it.
 245
 246  destroy_inode: this method is called by destroy_inode() to release
 247        resources allocated for struct inode.  It is only required if
 248        ->alloc_inode was defined and simply undoes anything done by
 249        ->alloc_inode.
 250
 251  dirty_inode: this method is called by the VFS to mark an inode dirty.
 252
 253  write_inode: this method is called when the VFS needs to write an
 254        inode to disc.  The second parameter indicates whether the write
 255        should be synchronous or not, not all filesystems check this flag.
 256
 257  drop_inode: called when the last access to the inode is dropped,
 258        with the inode->i_lock spinlock held.
 259
 260        This method should be either NULL (normal UNIX filesystem
 261        semantics) or "generic_delete_inode" (for filesystems that do not
 262        want to cache inodes - causing "delete_inode" to always be
 263        called regardless of the value of i_nlink)
 264
 265        The "generic_delete_inode()" behavior is equivalent to the
 266        old practice of using "force_delete" in the put_inode() case,
 267        but does not have the races that the "force_delete()" approach
 268        had. 
 269
 270  delete_inode: called when the VFS wants to delete an inode
 271
 272  put_super: called when the VFS wishes to free the superblock
 273        (i.e. unmount). This is called with the superblock lock held
 274
 275  sync_fs: called when VFS is writing out all dirty data associated with
 276        a superblock. The second parameter indicates whether the method
 277        should wait until the write out has been completed. Optional.
 278
 279  freeze_fs: called when VFS is locking a filesystem and
 280        forcing it into a consistent state.  This method is currently
 281        used by the Logical Volume Manager (LVM).
 282
 283  unfreeze_fs: called when VFS is unlocking a filesystem and making it writable
 284        again.
 285
 286  statfs: called when the VFS needs to get filesystem statistics.
 287
 288  remount_fs: called when the filesystem is remounted. This is called
 289        with the kernel lock held
 290
 291  clear_inode: called then the VFS clears the inode. Optional
 292
 293  umount_begin: called when the VFS is unmounting a filesystem.
 294
 295  show_options: called by the VFS to show mount options for
 296        /proc/<pid>/mounts.  (see "Mount Options" section)
 297
 298  quota_read: called by the VFS to read from filesystem quota file.
 299
 300  quota_write: called by the VFS to write to filesystem quota file.
 301
 302  nr_cached_objects: called by the sb cache shrinking function for the
 303        filesystem to return the number of freeable cached objects it contains.
 304        Optional.
 305
 306  free_cache_objects: called by the sb cache shrinking function for the
 307        filesystem to scan the number of objects indicated to try to free them.
 308        Optional, but any filesystem implementing this method needs to also
 309        implement ->nr_cached_objects for it to be called correctly.
 310
 311        We can't do anything with any errors that the filesystem might
 312        encountered, hence the void return type. This will never be called if
 313        the VM is trying to reclaim under GFP_NOFS conditions, hence this
 314        method does not need to handle that situation itself.
 315
 316        Implementations must include conditional reschedule calls inside any
 317        scanning loop that is done. This allows the VFS to determine
 318        appropriate scan batch sizes without having to worry about whether
 319        implementations will cause holdoff problems due to large scan batch
 320        sizes.
 321
 322Whoever sets up the inode is responsible for filling in the "i_op" field. This
 323is a pointer to a "struct inode_operations" which describes the methods that
 324can be performed on individual inodes.
 325
 326
 327The Inode Object
 328================
 329
 330An inode object represents an object within the filesystem.
 331
 332
 333struct inode_operations
 334-----------------------
 335
 336This describes how the VFS can manipulate an inode in your
 337filesystem. As of kernel 2.6.22, the following members are defined:
 338
 339struct inode_operations {
 340        int (*create) (struct inode *,struct dentry *, umode_t, bool);
 341        struct dentry * (*lookup) (struct inode *,struct dentry *, unsigned int);
 342        int (*link) (struct dentry *,struct inode *,struct dentry *);
 343        int (*unlink) (struct inode *,struct dentry *);
 344        int (*symlink) (struct inode *,struct dentry *,const char *);
 345        int (*mkdir) (struct inode *,struct dentry *,umode_t);
 346        int (*rmdir) (struct inode *,struct dentry *);
 347        int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t);
 348        int (*rename) (struct inode *, struct dentry *,
 349                        struct inode *, struct dentry *);
 350        int (*readlink) (struct dentry *, char __user *,int);
 351        void * (*follow_link) (struct dentry *, struct nameidata *);
 352        void (*put_link) (struct dentry *, struct nameidata *, void *);
 353        int (*permission) (struct inode *, int);
 354        int (*get_acl)(struct inode *, int);
 355        int (*setattr) (struct dentry *, struct iattr *);
 356        int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *);
 357        int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
 358        ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
 359        ssize_t (*listxattr) (struct dentry *, char *, size_t);
 360        int (*removexattr) (struct dentry *, const char *);
 361        void (*update_time)(struct inode *, struct timespec *, int);
 362        int (*atomic_open)(struct inode *, struct dentry *,
 363        int (*tmpfile) (struct inode *, struct dentry *, umode_t);
 364} ____cacheline_aligned;
 365                                struct file *, unsigned open_flag,
 366                                umode_t create_mode, int *opened);
 367};
 368
 369Again, all methods are called without any locks being held, unless
 370otherwise noted.
 371
 372  create: called by the open(2) and creat(2) system calls. Only
 373        required if you want to support regular files. The dentry you
 374        get should not have an inode (i.e. it should be a negative
 375        dentry). Here you will probably call d_instantiate() with the
 376        dentry and the newly created inode
 377
 378  lookup: called when the VFS needs to look up an inode in a parent
 379        directory. The name to look for is found in the dentry. This
 380        method must call d_add() to insert the found inode into the
 381        dentry. The "i_count" field in the inode structure should be
 382        incremented. If the named inode does not exist a NULL inode
 383        should be inserted into the dentry (this is called a negative
 384        dentry). Returning an error code from this routine must only
 385        be done on a real error, otherwise creating inodes with system
 386        calls like create(2), mknod(2), mkdir(2) and so on will fail.
 387        If you wish to overload the dentry methods then you should
 388        initialise the "d_dop" field in the dentry; this is a pointer
 389        to a struct "dentry_operations".
 390        This method is called with the directory inode semaphore held
 391
 392  link: called by the link(2) system call. Only required if you want
 393        to support hard links. You will probably need to call
 394        d_instantiate() just as you would in the create() method
 395
 396  unlink: called by the unlink(2) system call. Only required if you
 397        want to support deleting inodes
 398
 399  symlink: called by the symlink(2) system call. Only required if you
 400        want to support symlinks. You will probably need to call
 401        d_instantiate() just as you would in the create() method
 402
 403  mkdir: called by the mkdir(2) system call. Only required if you want
 404        to support creating subdirectories. You will probably need to
 405        call d_instantiate() just as you would in the create() method
 406
 407  rmdir: called by the rmdir(2) system call. Only required if you want
 408        to support deleting subdirectories
 409
 410  mknod: called by the mknod(2) system call to create a device (char,
 411        block) inode or a named pipe (FIFO) or socket. Only required
 412        if you want to support creating these types of inodes. You
 413        will probably need to call d_instantiate() just as you would
 414        in the create() method
 415
 416  rename: called by the rename(2) system call to rename the object to
 417        have the parent and name given by the second inode and dentry.
 418
 419  readlink: called by the readlink(2) system call. Only required if
 420        you want to support reading symbolic links
 421
 422  follow_link: called by the VFS to follow a symbolic link to the
 423        inode it points to.  Only required if you want to support
 424        symbolic links.  This method returns a void pointer cookie
 425        that is passed to put_link().
 426
 427  put_link: called by the VFS to release resources allocated by
 428        follow_link().  The cookie returned by follow_link() is passed
 429        to this method as the last parameter.  It is used by
 430        filesystems such as NFS where page cache is not stable
 431        (i.e. page that was installed when the symbolic link walk
 432        started might not be in the page cache at the end of the
 433        walk).
 434
 435  permission: called by the VFS to check for access rights on a POSIX-like
 436        filesystem.
 437
 438        May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in rcu-walk
 439        mode, the filesystem must check the permission without blocking or
 440        storing to the inode.
 441
 442        If a situation is encountered that rcu-walk cannot handle, return
 443        -ECHILD and it will be called again in ref-walk mode.
 444
 445  setattr: called by the VFS to set attributes for a file. This method
 446        is called by chmod(2) and related system calls.
 447
 448  getattr: called by the VFS to get attributes of a file. This method
 449        is called by stat(2) and related system calls.
 450
 451  setxattr: called by the VFS to set an extended attribute for a file.
 452        Extended attribute is a name:value pair associated with an
 453        inode. This method is called by setxattr(2) system call.
 454
 455  getxattr: called by the VFS to retrieve the value of an extended
 456        attribute name. This method is called by getxattr(2) function
 457        call.
 458
 459  listxattr: called by the VFS to list all extended attributes for a
 460        given file. This method is called by listxattr(2) system call.
 461
 462  removexattr: called by the VFS to remove an extended attribute from
 463        a file. This method is called by removexattr(2) system call.
 464
 465  update_time: called by the VFS to update a specific time or the i_version of
 466        an inode.  If this is not defined the VFS will update the inode itself
 467        and call mark_inode_dirty_sync.
 468
 469  atomic_open: called on the last component of an open.  Using this optional
 470        method the filesystem can look up, possibly create and open the file in
 471        one atomic operation.  If it cannot perform this (e.g. the file type
 472        turned out to be wrong) it may signal this by returning 1 instead of
 473        usual 0 or -ve .  This method is only called if the last
 474        component is negative or needs lookup.  Cached positive dentries are
 475        still handled by f_op->open().
 476
 477  tmpfile: called in the end of O_TMPFILE open().  Optional, equivalent to
 478        atomically creating, opening and unlinking a file in given directory.
 479
 480The Address Space Object
 481========================
 482
 483The address space object is used to group and manage pages in the page
 484cache.  It can be used to keep track of the pages in a file (or
 485anything else) and also track the mapping of sections of the file into
 486process address spaces.
 487
 488There are a number of distinct yet related services that an
 489address-space can provide.  These include communicating memory
 490pressure, page lookup by address, and keeping track of pages tagged as
 491Dirty or Writeback.
 492
 493The first can be used independently to the others.  The VM can try to
 494either write dirty pages in order to clean them, or release clean
 495pages in order to reuse them.  To do this it can call the ->writepage
 496method on dirty pages, and ->releasepage on clean pages with
 497PagePrivate set. Clean pages without PagePrivate and with no external
 498references will be released without notice being given to the
 499address_space.
 500
 501To achieve this functionality, pages need to be placed on an LRU with
 502lru_cache_add and mark_page_active needs to be called whenever the
 503page is used.
 504
 505Pages are normally kept in a radix tree index by ->index. This tree
 506maintains information about the PG_Dirty and PG_Writeback status of
 507each page, so that pages with either of these flags can be found
 508quickly.
 509
 510The Dirty tag is primarily used by mpage_writepages - the default
 511->writepages method.  It uses the tag to find dirty pages to call
 512->writepage on.  If mpage_writepages is not used (i.e. the address
 513provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is
 514almost unused.  write_inode_now and sync_inode do use it (through
 515__sync_single_inode) to check if ->writepages has been successful in
 516writing out the whole address_space.
 517
 518The Writeback tag is used by filemap*wait* and sync_page* functions,
 519via filemap_fdatawait_range, to wait for all writeback to
 520complete.  While waiting ->sync_page (if defined) will be called on
 521each page that is found to require writeback.
 522
 523An address_space handler may attach extra information to a page,
 524typically using the 'private' field in the 'struct page'.  If such
 525information is attached, the PG_Private flag should be set.  This will
 526cause various VM routines to make extra calls into the address_space
 527handler to deal with that data.
 528
 529An address space acts as an intermediate between storage and
 530application.  Data is read into the address space a whole page at a
 531time, and provided to the application either by copying of the page,
 532or by memory-mapping the page.
 533Data is written into the address space by the application, and then
 534written-back to storage typically in whole pages, however the
 535address_space has finer control of write sizes.
 536
 537The read process essentially only requires 'readpage'.  The write
 538process is more complicated and uses write_begin/write_end or
 539set_page_dirty to write data into the address_space, and writepage,
 540sync_page, and writepages to writeback data to storage.
 541
 542Adding and removing pages to/from an address_space is protected by the
 543inode's i_mutex.
 544
 545When data is written to a page, the PG_Dirty flag should be set.  It
 546typically remains set until writepage asks for it to be written.  This
 547should clear PG_Dirty and set PG_Writeback.  It can be actually
 548written at any point after PG_Dirty is clear.  Once it is known to be
 549safe, PG_Writeback is cleared.
 550
 551Writeback makes use of a writeback_control structure...
 552
 553struct address_space_operations
 554-------------------------------
 555
 556This describes how the VFS can manipulate mapping of a file to page cache in
 557your filesystem. The following members are defined:
 558
 559struct address_space_operations {
 560        int (*writepage)(struct page *page, struct writeback_control *wbc);
 561        int (*readpage)(struct file *, struct page *);
 562        int (*writepages)(struct address_space *, struct writeback_control *);
 563        int (*set_page_dirty)(struct page *page);
 564        int (*readpages)(struct file *filp, struct address_space *mapping,
 565                        struct list_head *pages, unsigned nr_pages);
 566        int (*write_begin)(struct file *, struct address_space *mapping,
 567                                loff_t pos, unsigned len, unsigned flags,
 568                                struct page **pagep, void **fsdata);
 569        int (*write_end)(struct file *, struct address_space *mapping,
 570                                loff_t pos, unsigned len, unsigned copied,
 571                                struct page *page, void *fsdata);
 572        sector_t (*bmap)(struct address_space *, sector_t);
 573        void (*invalidatepage) (struct page *, unsigned int, unsigned int);
 574        int (*releasepage) (struct page *, int);
 575        void (*freepage)(struct page *);
 576        ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
 577                        loff_t offset, unsigned long nr_segs);
 578        struct page* (*get_xip_page)(struct address_space *, sector_t,
 579                        int);
 580        /* migrate the contents of a page to the specified target */
 581        int (*migratepage) (struct page *, struct page *);
 582        int (*launder_page) (struct page *);
 583        int (*is_partially_uptodate) (struct page *, read_descriptor_t *,
 584                                        unsigned long);
 585        void (*is_dirty_writeback) (struct page *, bool *, bool *);
 586        int (*error_remove_page) (struct mapping *mapping, struct page *page);
 587        int (*swap_activate)(struct file *);
 588        int (*swap_deactivate)(struct file *);
 589};
 590
 591  writepage: called by the VM to write a dirty page to backing store.
 592      This may happen for data integrity reasons (i.e. 'sync'), or
 593      to free up memory (flush).  The difference can be seen in
 594      wbc->sync_mode.
 595      The PG_Dirty flag has been cleared and PageLocked is true.
 596      writepage should start writeout, should set PG_Writeback,
 597      and should make sure the page is unlocked, either synchronously
 598      or asynchronously when the write operation completes.
 599
 600      If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to
 601      try too hard if there are problems, and may choose to write out
 602      other pages from the mapping if that is easier (e.g. due to
 603      internal dependencies).  If it chooses not to start writeout, it
 604      should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep
 605      calling ->writepage on that page.
 606
 607      See the file "Locking" for more details.
 608
 609  readpage: called by the VM to read a page from backing store.
 610       The page will be Locked when readpage is called, and should be
 611       unlocked and marked uptodate once the read completes.
 612       If ->readpage discovers that it needs to unlock the page for
 613       some reason, it can do so, and then return AOP_TRUNCATED_PAGE.
 614       In this case, the page will be relocated, relocked and if
 615       that all succeeds, ->readpage will be called again.
 616
 617  writepages: called by the VM to write out pages associated with the
 618        address_space object.  If wbc->sync_mode is WBC_SYNC_ALL, then
 619        the writeback_control will specify a range of pages that must be
 620        written out.  If it is WBC_SYNC_NONE, then a nr_to_write is given
 621        and that many pages should be written if possible.
 622        If no ->writepages is given, then mpage_writepages is used
 623        instead.  This will choose pages from the address space that are
 624        tagged as DIRTY and will pass them to ->writepage.
 625
 626  set_page_dirty: called by the VM to set a page dirty.
 627        This is particularly needed if an address space attaches
 628        private data to a page, and that data needs to be updated when
 629        a page is dirtied.  This is called, for example, when a memory
 630        mapped page gets modified.
 631        If defined, it should set the PageDirty flag, and the
 632        PAGECACHE_TAG_DIRTY tag in the radix tree.
 633
 634  readpages: called by the VM to read pages associated with the address_space
 635        object. This is essentially just a vector version of
 636        readpage.  Instead of just one page, several pages are
 637        requested.
 638        readpages is only used for read-ahead, so read errors are
 639        ignored.  If anything goes wrong, feel free to give up.
 640
 641  write_begin:
 642        Called by the generic buffered write code to ask the filesystem to
 643        prepare to write len bytes at the given offset in the file. The
 644        address_space should check that the write will be able to complete,
 645        by allocating space if necessary and doing any other internal
 646        housekeeping.  If the write will update parts of any basic-blocks on
 647        storage, then those blocks should be pre-read (if they haven't been
 648        read already) so that the updated blocks can be written out properly.
 649
 650        The filesystem must return the locked pagecache page for the specified
 651        offset, in *pagep, for the caller to write into.
 652
 653        It must be able to cope with short writes (where the length passed to
 654        write_begin is greater than the number of bytes copied into the page).
 655
 656        flags is a field for AOP_FLAG_xxx flags, described in
 657        include/linux/fs.h.
 658
 659        A void * may be returned in fsdata, which then gets passed into
 660        write_end.
 661
 662        Returns 0 on success; < 0 on failure (which is the error code), in
 663        which case write_end is not called.
 664
 665  write_end: After a successful write_begin, and data copy, write_end must
 666        be called. len is the original len passed to write_begin, and copied
 667        is the amount that was able to be copied (copied == len is always true
 668        if write_begin was called with the AOP_FLAG_UNINTERRUPTIBLE flag).
 669
 670        The filesystem must take care of unlocking the page and releasing it
 671        refcount, and updating i_size.
 672
 673        Returns < 0 on failure, otherwise the number of bytes (<= 'copied')
 674        that were able to be copied into pagecache.
 675
 676  bmap: called by the VFS to map a logical block offset within object to
 677        physical block number. This method is used by the FIBMAP
 678        ioctl and for working with swap-files.  To be able to swap to
 679        a file, the file must have a stable mapping to a block
 680        device.  The swap system does not go through the filesystem
 681        but instead uses bmap to find out where the blocks in the file
 682        are and uses those addresses directly.
 683
 684
 685  invalidatepage: If a page has PagePrivate set, then invalidatepage
 686        will be called when part or all of the page is to be removed
 687        from the address space.  This generally corresponds to either a
 688        truncation, punch hole  or a complete invalidation of the address
 689        space (in the latter case 'offset' will always be 0 and 'length'
 690        will be PAGE_CACHE_SIZE). Any private data associated with the page
 691        should be updated to reflect this truncation.  If offset is 0 and
 692        length is PAGE_CACHE_SIZE, then the private data should be released,
 693        because the page must be able to be completely discarded.  This may
 694        be done by calling the ->releasepage function, but in this case the
 695        release MUST succeed.
 696
 697  releasepage: releasepage is called on PagePrivate pages to indicate
 698        that the page should be freed if possible.  ->releasepage
 699        should remove any private data from the page and clear the
 700        PagePrivate flag. If releasepage() fails for some reason, it must
 701        indicate failure with a 0 return value.
 702        releasepage() is used in two distinct though related cases.  The
 703        first is when the VM finds a clean page with no active users and
 704        wants to make it a free page.  If ->releasepage succeeds, the
 705        page will be removed from the address_space and become free.
 706
 707        The second case is when a request has been made to invalidate
 708        some or all pages in an address_space.  This can happen
 709        through the fadvice(POSIX_FADV_DONTNEED) system call or by the
 710        filesystem explicitly requesting it as nfs and 9fs do (when
 711        they believe the cache may be out of date with storage) by
 712        calling invalidate_inode_pages2().
 713        If the filesystem makes such a call, and needs to be certain
 714        that all pages are invalidated, then its releasepage will
 715        need to ensure this.  Possibly it can clear the PageUptodate
 716        bit if it cannot free private data yet.
 717
 718  freepage: freepage is called once the page is no longer visible in
 719        the page cache in order to allow the cleanup of any private
 720        data. Since it may be called by the memory reclaimer, it
 721        should not assume that the original address_space mapping still
 722        exists, and it should not block.
 723
 724  direct_IO: called by the generic read/write routines to perform
 725        direct_IO - that is IO requests which bypass the page cache
 726        and transfer data directly between the storage and the
 727        application's address space.
 728
 729  get_xip_page: called by the VM to translate a block number to a page.
 730        The page is valid until the corresponding filesystem is unmounted.
 731        Filesystems that want to use execute-in-place (XIP) need to implement
 732        it.  An example implementation can be found in fs/ext2/xip.c.
 733
 734  migrate_page:  This is used to compact the physical memory usage.
 735        If the VM wants to relocate a page (maybe off a memory card
 736        that is signalling imminent failure) it will pass a new page
 737        and an old page to this function.  migrate_page should
 738        transfer any private data across and update any references
 739        that it has to the page.
 740
 741  launder_page: Called before freeing a page - it writes back the dirty page. To
 742        prevent redirtying the page, it is kept locked during the whole
 743        operation.
 744
 745  is_partially_uptodate: Called by the VM when reading a file through the
 746        pagecache when the underlying blocksize != pagesize. If the required
 747        block is up to date then the read can complete without needing the IO
 748        to bring the whole page up to date.
 749
 750  is_dirty_writeback: Called by the VM when attempting to reclaim a page.
 751        The VM uses dirty and writeback information to determine if it needs
 752        to stall to allow flushers a chance to complete some IO. Ordinarily
 753        it can use PageDirty and PageWriteback but some filesystems have
 754        more complex state (unstable pages in NFS prevent reclaim) or
 755        do not set those flags due to locking problems (jbd). This callback
 756        allows a filesystem to indicate to the VM if a page should be
 757        treated as dirty or writeback for the purposes of stalling.
 758
 759  error_remove_page: normally set to generic_error_remove_page if truncation
 760        is ok for this address space. Used for memory failure handling.
 761        Setting this implies you deal with pages going away under you,
 762        unless you have them locked or reference counts increased.
 763
 764  swap_activate: Called when swapon is used on a file to allocate
 765        space if necessary and pin the block lookup information in
 766        memory. A return value of zero indicates success,
 767        in which case this file can be used to back swapspace. The
 768        swapspace operations will be proxied to this address space's
 769        ->swap_{out,in} methods.
 770
 771  swap_deactivate: Called during swapoff on files where swap_activate
 772        was successful.
 773
 774
 775The File Object
 776===============
 777
 778A file object represents a file opened by a process.
 779
 780
 781struct file_operations
 782----------------------
 783
 784This describes how the VFS can manipulate an open file. As of kernel
 7853.5, the following members are defined:
 786
 787struct file_operations {
 788        struct module *owner;
 789        loff_t (*llseek) (struct file *, loff_t, int);
 790        ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
 791        ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
 792        ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
 793        ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
 794        int (*iterate) (struct file *, struct dir_context *);
 795        unsigned int (*poll) (struct file *, struct poll_table_struct *);
 796        long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
 797        long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
 798        int (*mmap) (struct file *, struct vm_area_struct *);
 799        int (*open) (struct inode *, struct file *);
 800        int (*flush) (struct file *);
 801        int (*release) (struct inode *, struct file *);
 802        int (*fsync) (struct file *, loff_t, loff_t, int datasync);
 803        int (*aio_fsync) (struct kiocb *, int datasync);
 804        int (*fasync) (int, struct file *, int);
 805        int (*lock) (struct file *, int, struct file_lock *);
 806        ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);
 807        ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *);
 808        ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *);
 809        ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
 810        unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
 811        int (*check_flags)(int);
 812        int (*flock) (struct file *, int, struct file_lock *);
 813        ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, size_t, unsigned int);
 814        ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned int);
 815        int (*setlease)(struct file *, long arg, struct file_lock **);
 816        long (*fallocate)(struct file *, int mode, loff_t offset, loff_t len);
 817};
 818
 819Again, all methods are called without any locks being held, unless
 820otherwise noted.
 821
 822  llseek: called when the VFS needs to move the file position index
 823
 824  read: called by read(2) and related system calls
 825
 826  aio_read: called by io_submit(2) and other asynchronous I/O operations
 827
 828  write: called by write(2) and related system calls
 829
 830  aio_write: called by io_submit(2) and other asynchronous I/O operations
 831
 832  iterate: called when the VFS needs to read the directory contents
 833
 834  poll: called by the VFS when a process wants to check if there is
 835        activity on this file and (optionally) go to sleep until there
 836        is activity. Called by the select(2) and poll(2) system calls
 837
 838  unlocked_ioctl: called by the ioctl(2) system call.
 839
 840  compat_ioctl: called by the ioctl(2) system call when 32 bit system calls
 841         are used on 64 bit kernels.
 842
 843  mmap: called by the mmap(2) system call
 844
 845  open: called by the VFS when an inode should be opened. When the VFS
 846        opens a file, it creates a new "struct file". It then calls the
 847        open method for the newly allocated file structure. You might
 848        think that the open method really belongs in
 849        "struct inode_operations", and you may be right. I think it's
 850        done the way it is because it makes filesystems simpler to
 851        implement. The open() method is a good place to initialize the
 852        "private_data" member in the file structure if you want to point
 853        to a device structure
 854
 855  flush: called by the close(2) system call to flush a file
 856
 857  release: called when the last reference to an open file is closed
 858
 859  fsync: called by the fsync(2) system call
 860
 861  fasync: called by the fcntl(2) system call when asynchronous
 862        (non-blocking) mode is enabled for a file
 863
 864  lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW
 865        commands
 866
 867  readv: called by the readv(2) system call
 868
 869  writev: called by the writev(2) system call
 870
 871  sendfile: called by the sendfile(2) system call
 872
 873  get_unmapped_area: called by the mmap(2) system call
 874
 875  check_flags: called by the fcntl(2) system call for F_SETFL command
 876
 877  flock: called by the flock(2) system call
 878
 879  splice_write: called by the VFS to splice data from a pipe to a file. This
 880                method is used by the splice(2) system call
 881
 882  splice_read: called by the VFS to splice data from file to a pipe. This
 883               method is used by the splice(2) system call
 884
 885  setlease: called by the VFS to set or release a file lock lease.
 886            setlease has the file_lock_lock held and must not sleep.
 887
 888  fallocate: called by the VFS to preallocate blocks or punch a hole.
 889
 890Note that the file operations are implemented by the specific
 891filesystem in which the inode resides. When opening a device node
 892(character or block special) most filesystems will call special
 893support routines in the VFS which will locate the required device
 894driver information. These support routines replace the filesystem file
 895operations with those for the device driver, and then proceed to call
 896the new open() method for the file. This is how opening a device file
 897in the filesystem eventually ends up calling the device driver open()
 898method.
 899
 900
 901Directory Entry Cache (dcache)
 902==============================
 903
 904
 905struct dentry_operations
 906------------------------
 907
 908This describes how a filesystem can overload the standard dentry
 909operations. Dentries and the dcache are the domain of the VFS and the
 910individual filesystem implementations. Device drivers have no business
 911here. These methods may be set to NULL, as they are either optional or
 912the VFS uses a default. As of kernel 2.6.22, the following members are
 913defined:
 914
 915struct dentry_operations {
 916        int (*d_revalidate)(struct dentry *, unsigned int);
 917        int (*d_weak_revalidate)(struct dentry *, unsigned int);
 918        int (*d_hash)(const struct dentry *, struct qstr *);
 919        int (*d_compare)(const struct dentry *, const struct dentry *,
 920                        unsigned int, const char *, const struct qstr *);
 921        int (*d_delete)(const struct dentry *);
 922        void (*d_release)(struct dentry *);
 923        void (*d_iput)(struct dentry *, struct inode *);
 924        char *(*d_dname)(struct dentry *, char *, int);
 925        struct vfsmount *(*d_automount)(struct path *);
 926        int (*d_manage)(struct dentry *, bool);
 927};
 928
 929  d_revalidate: called when the VFS needs to revalidate a dentry. This
 930        is called whenever a name look-up finds a dentry in the
 931        dcache. Most local filesystems leave this as NULL, because all their
 932        dentries in the dcache are valid. Network filesystems are different
 933        since things can change on the server without the client necessarily
 934        being aware of it.
 935
 936        This function should return a positive value if the dentry is still
 937        valid, and zero or a negative error code if it isn't.
 938
 939        d_revalidate may be called in rcu-walk mode (flags & LOOKUP_RCU).
 940        If in rcu-walk mode, the filesystem must revalidate the dentry without
 941        blocking or storing to the dentry, d_parent and d_inode should not be
 942        used without care (because they can change and, in d_inode case, even
 943        become NULL under us).
 944
 945        If a situation is encountered that rcu-walk cannot handle, return
 946        -ECHILD and it will be called again in ref-walk mode.
 947
 948 d_weak_revalidate: called when the VFS needs to revalidate a "jumped" dentry.
 949        This is called when a path-walk ends at dentry that was not acquired by
 950        doing a lookup in the parent directory. This includes "/", "." and "..",
 951        as well as procfs-style symlinks and mountpoint traversal.
 952
 953        In this case, we are less concerned with whether the dentry is still
 954        fully correct, but rather that the inode is still valid. As with
 955        d_revalidate, most local filesystems will set this to NULL since their
 956        dcache entries are always valid.
 957
 958        This function has the same return code semantics as d_revalidate.
 959
 960        d_weak_revalidate is only called after leaving rcu-walk mode.
 961
 962  d_hash: called when the VFS adds a dentry to the hash table. The first
 963        dentry passed to d_hash is the parent directory that the name is
 964        to be hashed into.
 965
 966        Same locking and synchronisation rules as d_compare regarding
 967        what is safe to dereference etc.
 968
 969  d_compare: called to compare a dentry name with a given name. The first
 970        dentry is the parent of the dentry to be compared, the second is
 971        the child dentry. len and name string are properties of the dentry
 972        to be compared. qstr is the name to compare it with.
 973
 974        Must be constant and idempotent, and should not take locks if
 975        possible, and should not or store into the dentry.
 976        Should not dereference pointers outside the dentry without
 977        lots of care (eg.  d_parent, d_inode, d_name should not be used).
 978
 979        However, our vfsmount is pinned, and RCU held, so the dentries and
 980        inodes won't disappear, neither will our sb or filesystem module.
 981        ->d_sb may be used.
 982
 983        It is a tricky calling convention because it needs to be called under
 984        "rcu-walk", ie. without any locks or references on things.
 985
 986  d_delete: called when the last reference to a dentry is dropped and the
 987        dcache is deciding whether or not to cache it. Return 1 to delete
 988        immediately, or 0 to cache the dentry. Default is NULL which means to
 989        always cache a reachable dentry. d_delete must be constant and
 990        idempotent.
 991
 992  d_release: called when a dentry is really deallocated
 993
 994  d_iput: called when a dentry loses its inode (just prior to its
 995        being deallocated). The default when this is NULL is that the
 996        VFS calls iput(). If you define this method, you must call
 997        iput() yourself
 998
 999  d_dname: called when the pathname of a dentry should be generated.
1000        Useful for some pseudo filesystems (sockfs, pipefs, ...) to delay
1001        pathname generation. (Instead of doing it when dentry is created,
1002        it's done only when the path is needed.). Real filesystems probably
1003        dont want to use it, because their dentries are present in global
1004        dcache hash, so their hash should be an invariant. As no lock is
1005        held, d_dname() should not try to modify the dentry itself, unless
1006        appropriate SMP safety is used. CAUTION : d_path() logic is quite
1007        tricky. The correct way to return for example "Hello" is to put it
1008        at the end of the buffer, and returns a pointer to the first char.
1009        dynamic_dname() helper function is provided to take care of this.
1010
1011  d_automount: called when an automount dentry is to be traversed (optional).
1012        This should create a new VFS mount record and return the record to the
1013        caller.  The caller is supplied with a path parameter giving the
1014        automount directory to describe the automount target and the parent
1015        VFS mount record to provide inheritable mount parameters.  NULL should
1016        be returned if someone else managed to make the automount first.  If
1017        the vfsmount creation failed, then an error code should be returned.
1018        If -EISDIR is returned, then the directory will be treated as an
1019        ordinary directory and returned to pathwalk to continue walking.
1020
1021        If a vfsmount is returned, the caller will attempt to mount it on the
1022        mountpoint and will remove the vfsmount from its expiration list in
1023        the case of failure.  The vfsmount should be returned with 2 refs on
1024        it to prevent automatic expiration - the caller will clean up the
1025        additional ref.
1026
1027        This function is only used if DCACHE_NEED_AUTOMOUNT is set on the
1028        dentry.  This is set by __d_instantiate() if S_AUTOMOUNT is set on the
1029        inode being added.
1030
1031  d_manage: called to allow the filesystem to manage the transition from a
1032        dentry (optional).  This allows autofs, for example, to hold up clients
1033        waiting to explore behind a 'mountpoint' whilst letting the daemon go
1034        past and construct the subtree there.  0 should be returned to let the
1035        calling process continue.  -EISDIR can be returned to tell pathwalk to
1036        use this directory as an ordinary directory and to ignore anything
1037        mounted on it and not to check the automount flag.  Any other error
1038        code will abort pathwalk completely.
1039
1040        If the 'rcu_walk' parameter is true, then the caller is doing a
1041        pathwalk in RCU-walk mode.  Sleeping is not permitted in this mode,
1042        and the caller can be asked to leave it and call again by returning
1043        -ECHILD.
1044
1045        This function is only used if DCACHE_MANAGE_TRANSIT is set on the
1046        dentry being transited from.
1047
1048Example :
1049
1050static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
1051{
1052        return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
1053                                dentry->d_inode->i_ino);
1054}
1055
1056Each dentry has a pointer to its parent dentry, as well as a hash list
1057of child dentries. Child dentries are basically like files in a
1058directory.
1059
1060
1061Directory Entry Cache API
1062--------------------------
1063
1064There are a number of functions defined which permit a filesystem to
1065manipulate dentries:
1066
1067  dget: open a new handle for an existing dentry (this just increments
1068        the usage count)
1069
1070  dput: close a handle for a dentry (decrements the usage count). If
1071        the usage count drops to 0, and the dentry is still in its
1072        parent's hash, the "d_delete" method is called to check whether
1073        it should be cached. If it should not be cached, or if the dentry
1074        is not hashed, it is deleted. Otherwise cached dentries are put
1075        into an LRU list to be reclaimed on memory shortage.
1076
1077  d_drop: this unhashes a dentry from its parents hash list. A
1078        subsequent call to dput() will deallocate the dentry if its
1079        usage count drops to 0
1080
1081  d_delete: delete a dentry. If there are no other open references to
1082        the dentry then the dentry is turned into a negative dentry
1083        (the d_iput() method is called). If there are other
1084        references, then d_drop() is called instead
1085
1086  d_add: add a dentry to its parents hash list and then calls
1087        d_instantiate()
1088
1089  d_instantiate: add a dentry to the alias hash list for the inode and
1090        updates the "d_inode" member. The "i_count" member in the
1091        inode structure should be set/incremented. If the inode
1092        pointer is NULL, the dentry is called a "negative
1093        dentry". This function is commonly called when an inode is
1094        created for an existing negative dentry
1095
1096  d_lookup: look up a dentry given its parent and path name component
1097        It looks up the child of that given name from the dcache
1098        hash table. If it is found, the reference count is incremented
1099        and the dentry is returned. The caller must use dput()
1100        to free the dentry when it finishes using it.
1101
1102Mount Options
1103=============
1104
1105Parsing options
1106---------------
1107
1108On mount and remount the filesystem is passed a string containing a
1109comma separated list of mount options.  The options can have either of
1110these forms:
1111
1112  option
1113  option=value
1114
1115The <linux/parser.h> header defines an API that helps parse these
1116options.  There are plenty of examples on how to use it in existing
1117filesystems.
1118
1119Showing options
1120---------------
1121
1122If a filesystem accepts mount options, it must define show_options()
1123to show all the currently active options.  The rules are:
1124
1125  - options MUST be shown which are not default or their values differ
1126    from the default
1127
1128  - options MAY be shown which are enabled by default or have their
1129    default value
1130
1131Options used only internally between a mount helper and the kernel
1132(such as file descriptors), or which only have an effect during the
1133mounting (such as ones controlling the creation of a journal) are exempt
1134from the above rules.
1135
1136The underlying reason for the above rules is to make sure, that a
1137mount can be accurately replicated (e.g. umounting and mounting again)
1138based on the information found in /proc/mounts.
1139
1140A simple method of saving options at mount/remount time and showing
1141them is provided with the save_mount_options() and
1142generic_show_options() helper functions.  Please note, that using
1143these may have drawbacks.  For more info see header comments for these
1144functions in fs/namespace.c.
1145
1146Resources
1147=========
1148
1149(Note some of these resources are not up-to-date with the latest kernel
1150 version.)
1151
1152Creating Linux virtual filesystems. 2002
1153    <http://lwn.net/Articles/13325/>
1154
1155The Linux Virtual File-system Layer by Neil Brown. 1999
1156    <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
1157
1158A tour of the Linux VFS by Michael K. Johnson. 1996
1159    <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
1160
1161A small trail through the Linux kernel by Andries Brouwer. 2001
1162    <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>
1163
lxr.linux.no kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.