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                                struct file *, unsigned open_flag,
 364                                umode_t create_mode, int *opened);
 365};
 366
 367Again, all methods are called without any locks being held, unless
 368otherwise noted.
 369
 370  create: called by the open(2) and creat(2) system calls. Only
 371        required if you want to support regular files. The dentry you
 372        get should not have an inode (i.e. it should be a negative
 373        dentry). Here you will probably call d_instantiate() with the
 374        dentry and the newly created inode
 375
 376  lookup: called when the VFS needs to look up an inode in a parent
 377        directory. The name to look for is found in the dentry. This
 378        method must call d_add() to insert the found inode into the
 379        dentry. The "i_count" field in the inode structure should be
 380        incremented. If the named inode does not exist a NULL inode
 381        should be inserted into the dentry (this is called a negative
 382        dentry). Returning an error code from this routine must only
 383        be done on a real error, otherwise creating inodes with system
 384        calls like create(2), mknod(2), mkdir(2) and so on will fail.
 385        If you wish to overload the dentry methods then you should
 386        initialise the "d_dop" field in the dentry; this is a pointer
 387        to a struct "dentry_operations".
 388        This method is called with the directory inode semaphore held
 389
 390  link: called by the link(2) system call. Only required if you want
 391        to support hard links. You will probably need to call
 392        d_instantiate() just as you would in the create() method
 393
 394  unlink: called by the unlink(2) system call. Only required if you
 395        want to support deleting inodes
 396
 397  symlink: called by the symlink(2) system call. Only required if you
 398        want to support symlinks. You will probably need to call
 399        d_instantiate() just as you would in the create() method
 400
 401  mkdir: called by the mkdir(2) system call. Only required if you want
 402        to support creating subdirectories. You will probably need to
 403        call d_instantiate() just as you would in the create() method
 404
 405  rmdir: called by the rmdir(2) system call. Only required if you want
 406        to support deleting subdirectories
 407
 408  mknod: called by the mknod(2) system call to create a device (char,
 409        block) inode or a named pipe (FIFO) or socket. Only required
 410        if you want to support creating these types of inodes. You
 411        will probably need to call d_instantiate() just as you would
 412        in the create() method
 413
 414  rename: called by the rename(2) system call to rename the object to
 415        have the parent and name given by the second inode and dentry.
 416
 417  readlink: called by the readlink(2) system call. Only required if
 418        you want to support reading symbolic links
 419
 420  follow_link: called by the VFS to follow a symbolic link to the
 421        inode it points to.  Only required if you want to support
 422        symbolic links.  This method returns a void pointer cookie
 423        that is passed to put_link().
 424
 425  put_link: called by the VFS to release resources allocated by
 426        follow_link().  The cookie returned by follow_link() is passed
 427        to this method as the last parameter.  It is used by
 428        filesystems such as NFS where page cache is not stable
 429        (i.e. page that was installed when the symbolic link walk
 430        started might not be in the page cache at the end of the
 431        walk).
 432
 433  permission: called by the VFS to check for access rights on a POSIX-like
 434        filesystem.
 435
 436        May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in rcu-walk
 437        mode, the filesystem must check the permission without blocking or
 438        storing to the inode.
 439
 440        If a situation is encountered that rcu-walk cannot handle, return
 441        -ECHILD and it will be called again in ref-walk mode.
 442
 443  setattr: called by the VFS to set attributes for a file. This method
 444        is called by chmod(2) and related system calls.
 445
 446  getattr: called by the VFS to get attributes of a file. This method
 447        is called by stat(2) and related system calls.
 448
 449  setxattr: called by the VFS to set an extended attribute for a file.
 450        Extended attribute is a name:value pair associated with an
 451        inode. This method is called by setxattr(2) system call.
 452
 453  getxattr: called by the VFS to retrieve the value of an extended
 454        attribute name. This method is called by getxattr(2) function
 455        call.
 456
 457  listxattr: called by the VFS to list all extended attributes for a
 458        given file. This method is called by listxattr(2) system call.
 459
 460  removexattr: called by the VFS to remove an extended attribute from
 461        a file. This method is called by removexattr(2) system call.
 462
 463  update_time: called by the VFS to update a specific time or the i_version of
 464        an inode.  If this is not defined the VFS will update the inode itself
 465        and call mark_inode_dirty_sync.
 466
 467  atomic_open: called on the last component of an open.  Using this optional
 468        method the filesystem can look up, possibly create and open the file in
 469        one atomic operation.  If it cannot perform this (e.g. the file type
 470        turned out to be wrong) it may signal this by returning 1 instead of
 471        usual 0 or -ve .  This method is only called if the last
 472        component is negative or needs lookup.  Cached positive dentries are
 473        still handled by f_op->open().
 474
 475The Address Space Object
 476========================
 477
 478The address space object is used to group and manage pages in the page
 479cache.  It can be used to keep track of the pages in a file (or
 480anything else) and also track the mapping of sections of the file into
 481process address spaces.
 482
 483There are a number of distinct yet related services that an
 484address-space can provide.  These include communicating memory
 485pressure, page lookup by address, and keeping track of pages tagged as
 486Dirty or Writeback.
 487
 488The first can be used independently to the others.  The VM can try to
 489either write dirty pages in order to clean them, or release clean
 490pages in order to reuse them.  To do this it can call the ->writepage
 491method on dirty pages, and ->releasepage on clean pages with
 492PagePrivate set. Clean pages without PagePrivate and with no external
 493references will be released without notice being given to the
 494address_space.
 495
 496To achieve this functionality, pages need to be placed on an LRU with
 497lru_cache_add and mark_page_active needs to be called whenever the
 498page is used.
 499
 500Pages are normally kept in a radix tree index by ->index. This tree
 501maintains information about the PG_Dirty and PG_Writeback status of
 502each page, so that pages with either of these flags can be found
 503quickly.
 504
 505The Dirty tag is primarily used by mpage_writepages - the default
 506->writepages method.  It uses the tag to find dirty pages to call
 507->writepage on.  If mpage_writepages is not used (i.e. the address
 508provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is
 509almost unused.  write_inode_now and sync_inode do use it (through
 510__sync_single_inode) to check if ->writepages has been successful in
 511writing out the whole address_space.
 512
 513The Writeback tag is used by filemap*wait* and sync_page* functions,
 514via filemap_fdatawait_range, to wait for all writeback to
 515complete.  While waiting ->sync_page (if defined) will be called on
 516each page that is found to require writeback.
 517
 518An address_space handler may attach extra information to a page,
 519typically using the 'private' field in the 'struct page'.  If such
 520information is attached, the PG_Private flag should be set.  This will
 521cause various VM routines to make extra calls into the address_space
 522handler to deal with that data.
 523
 524An address space acts as an intermediate between storage and
 525application.  Data is read into the address space a whole page at a
 526time, and provided to the application either by copying of the page,
 527or by memory-mapping the page.
 528Data is written into the address space by the application, and then
 529written-back to storage typically in whole pages, however the
 530address_space has finer control of write sizes.
 531
 532The read process essentially only requires 'readpage'.  The write
 533process is more complicated and uses write_begin/write_end or
 534set_page_dirty to write data into the address_space, and writepage,
 535sync_page, and writepages to writeback data to storage.
 536
 537Adding and removing pages to/from an address_space is protected by the
 538inode's i_mutex.
 539
 540When data is written to a page, the PG_Dirty flag should be set.  It
 541typically remains set until writepage asks for it to be written.  This
 542should clear PG_Dirty and set PG_Writeback.  It can be actually
 543written at any point after PG_Dirty is clear.  Once it is known to be
 544safe, PG_Writeback is cleared.
 545
 546Writeback makes use of a writeback_control structure...
 547
 548struct address_space_operations
 549-------------------------------
 550
 551This describes how the VFS can manipulate mapping of a file to page cache in
 552your filesystem. As of kernel 2.6.22, the following members are defined:
 553
 554struct address_space_operations {
 555        int (*writepage)(struct page *page, struct writeback_control *wbc);
 556        int (*readpage)(struct file *, struct page *);
 557        int (*sync_page)(struct page *);
 558        int (*writepages)(struct address_space *, struct writeback_control *);
 559        int (*set_page_dirty)(struct page *page);
 560        int (*readpages)(struct file *filp, struct address_space *mapping,
 561                        struct list_head *pages, unsigned nr_pages);
 562        int (*write_begin)(struct file *, struct address_space *mapping,
 563                                loff_t pos, unsigned len, unsigned flags,
 564                                struct page **pagep, void **fsdata);
 565        int (*write_end)(struct file *, struct address_space *mapping,
 566                                loff_t pos, unsigned len, unsigned copied,
 567                                struct page *page, void *fsdata);
 568        sector_t (*bmap)(struct address_space *, sector_t);
 569        int (*invalidatepage) (struct page *, unsigned long);
 570        int (*releasepage) (struct page *, int);
 571        void (*freepage)(struct page *);
 572        ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
 573                        loff_t offset, unsigned long nr_segs);
 574        struct page* (*get_xip_page)(struct address_space *, sector_t,
 575                        int);
 576        /* migrate the contents of a page to the specified target */
 577        int (*migratepage) (struct page *, struct page *);
 578        int (*launder_page) (struct page *);
 579        int (*error_remove_page) (struct mapping *mapping, struct page *page);
 580        int (*swap_activate)(struct file *);
 581        int (*swap_deactivate)(struct file *);
 582};
 583
 584  writepage: called by the VM to write a dirty page to backing store.
 585      This may happen for data integrity reasons (i.e. 'sync'), or
 586      to free up memory (flush).  The difference can be seen in
 587      wbc->sync_mode.
 588      The PG_Dirty flag has been cleared and PageLocked is true.
 589      writepage should start writeout, should set PG_Writeback,
 590      and should make sure the page is unlocked, either synchronously
 591      or asynchronously when the write operation completes.
 592
 593      If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to
 594      try too hard if there are problems, and may choose to write out
 595      other pages from the mapping if that is easier (e.g. due to
 596      internal dependencies).  If it chooses not to start writeout, it
 597      should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep
 598      calling ->writepage on that page.
 599
 600      See the file "Locking" for more details.
 601
 602  readpage: called by the VM to read a page from backing store.
 603       The page will be Locked when readpage is called, and should be
 604       unlocked and marked uptodate once the read completes.
 605       If ->readpage discovers that it needs to unlock the page for
 606       some reason, it can do so, and then return AOP_TRUNCATED_PAGE.
 607       In this case, the page will be relocated, relocked and if
 608       that all succeeds, ->readpage will be called again.
 609
 610  sync_page: called by the VM to notify the backing store to perform all
 611        queued I/O operations for a page. I/O operations for other pages
 612        associated with this address_space object may also be performed.
 613
 614        This function is optional and is called only for pages with
 615        PG_Writeback set while waiting for the writeback to complete.
 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 or a complete invalidation of the address space
 689        (in the latter case 'offset' will always be 0).
 690        Any private data associated with the page should be updated
 691        to reflect this truncation.  If offset is 0, then
 692        the private data should be released, because the page
 693        must be able to be completely discarded.  This may be done by
 694        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  error_remove_page: normally set to generic_error_remove_page if truncation
 746        is ok for this address space. Used for memory failure handling.
 747        Setting this implies you deal with pages going away under you,
 748        unless you have them locked or reference counts increased.
 749
 750  swap_activate: Called when swapon is used on a file to allocate
 751        space if necessary and pin the block lookup information in
 752        memory. A return value of zero indicates success,
 753        in which case this file can be used to back swapspace. The
 754        swapspace operations will be proxied to this address space's
 755        ->swap_{out,in} methods.
 756
 757  swap_deactivate: Called during swapoff on files where swap_activate
 758        was successful.
 759
 760
 761The File Object
 762===============
 763
 764A file object represents a file opened by a process.
 765
 766
 767struct file_operations
 768----------------------
 769
 770This describes how the VFS can manipulate an open file. As of kernel
 7713.5, the following members are defined:
 772
 773struct file_operations {
 774        struct module *owner;
 775        loff_t (*llseek) (struct file *, loff_t, int);
 776        ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
 777        ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
 778        ssize_t (*aio_read) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
 779        ssize_t (*aio_write) (struct kiocb *, const struct iovec *, unsigned long, loff_t);
 780        int (*readdir) (struct file *, void *, filldir_t);
 781        unsigned int (*poll) (struct file *, struct poll_table_struct *);
 782        long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
 783        long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
 784        int (*mmap) (struct file *, struct vm_area_struct *);
 785        int (*open) (struct inode *, struct file *);
 786        int (*flush) (struct file *);
 787        int (*release) (struct inode *, struct file *);
 788        int (*fsync) (struct file *, loff_t, loff_t, int datasync);
 789        int (*aio_fsync) (struct kiocb *, int datasync);
 790        int (*fasync) (int, struct file *, int);
 791        int (*lock) (struct file *, int, struct file_lock *);
 792        ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);
 793        ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *);
 794        ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *);
 795        ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
 796        unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
 797        int (*check_flags)(int);
 798        int (*flock) (struct file *, int, struct file_lock *);
 799        ssize_t (*splice_write)(struct pipe_inode_info *, struct file *, size_t, unsigned int);
 800        ssize_t (*splice_read)(struct file *, struct pipe_inode_info *, size_t, unsigned int);
 801        int (*setlease)(struct file *, long arg, struct file_lock **);
 802        long (*fallocate)(struct file *, int mode, loff_t offset, loff_t len);
 803};
 804
 805Again, all methods are called without any locks being held, unless
 806otherwise noted.
 807
 808  llseek: called when the VFS needs to move the file position index
 809
 810  read: called by read(2) and related system calls
 811
 812  aio_read: called by io_submit(2) and other asynchronous I/O operations
 813
 814  write: called by write(2) and related system calls
 815
 816  aio_write: called by io_submit(2) and other asynchronous I/O operations
 817
 818  readdir: called when the VFS needs to read the directory contents
 819
 820  poll: called by the VFS when a process wants to check if there is
 821        activity on this file and (optionally) go to sleep until there
 822        is activity. Called by the select(2) and poll(2) system calls
 823
 824  unlocked_ioctl: called by the ioctl(2) system call.
 825
 826  compat_ioctl: called by the ioctl(2) system call when 32 bit system calls
 827         are used on 64 bit kernels.
 828
 829  mmap: called by the mmap(2) system call
 830
 831  open: called by the VFS when an inode should be opened. When the VFS
 832        opens a file, it creates a new "struct file". It then calls the
 833        open method for the newly allocated file structure. You might
 834        think that the open method really belongs in
 835        "struct inode_operations", and you may be right. I think it's
 836        done the way it is because it makes filesystems simpler to
 837        implement. The open() method is a good place to initialize the
 838        "private_data" member in the file structure if you want to point
 839        to a device structure
 840
 841  flush: called by the close(2) system call to flush a file
 842
 843  release: called when the last reference to an open file is closed
 844
 845  fsync: called by the fsync(2) system call
 846
 847  fasync: called by the fcntl(2) system call when asynchronous
 848        (non-blocking) mode is enabled for a file
 849
 850  lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW
 851        commands
 852
 853  readv: called by the readv(2) system call
 854
 855  writev: called by the writev(2) system call
 856
 857  sendfile: called by the sendfile(2) system call
 858
 859  get_unmapped_area: called by the mmap(2) system call
 860
 861  check_flags: called by the fcntl(2) system call for F_SETFL command
 862
 863  flock: called by the flock(2) system call
 864
 865  splice_write: called by the VFS to splice data from a pipe to a file. This
 866                method is used by the splice(2) system call
 867
 868  splice_read: called by the VFS to splice data from file to a pipe. This
 869               method is used by the splice(2) system call
 870
 871  setlease: called by the VFS to set or release a file lock lease.
 872            setlease has the file_lock_lock held and must not sleep.
 873
 874  fallocate: called by the VFS to preallocate blocks or punch a hole.
 875
 876Note that the file operations are implemented by the specific
 877filesystem in which the inode resides. When opening a device node
 878(character or block special) most filesystems will call special
 879support routines in the VFS which will locate the required device
 880driver information. These support routines replace the filesystem file
 881operations with those for the device driver, and then proceed to call
 882the new open() method for the file. This is how opening a device file
 883in the filesystem eventually ends up calling the device driver open()
 884method.
 885
 886
 887Directory Entry Cache (dcache)
 888==============================
 889
 890
 891struct dentry_operations
 892------------------------
 893
 894This describes how a filesystem can overload the standard dentry
 895operations. Dentries and the dcache are the domain of the VFS and the
 896individual filesystem implementations. Device drivers have no business
 897here. These methods may be set to NULL, as they are either optional or
 898the VFS uses a default. As of kernel 2.6.22, the following members are
 899defined:
 900
 901struct dentry_operations {
 902        int (*d_revalidate)(struct dentry *, unsigned int);
 903        int (*d_weak_revalidate)(struct dentry *, unsigned int);
 904        int (*d_hash)(const struct dentry *, const struct inode *,
 905                        struct qstr *);
 906        int (*d_compare)(const struct dentry *, const struct inode *,
 907                        const struct dentry *, const struct inode *,
 908                        unsigned int, const char *, const struct qstr *);
 909        int (*d_delete)(const struct dentry *);
 910        void (*d_release)(struct dentry *);
 911        void (*d_iput)(struct dentry *, struct inode *);
 912        char *(*d_dname)(struct dentry *, char *, int);
 913        struct vfsmount *(*d_automount)(struct path *);
 914        int (*d_manage)(struct dentry *, bool);
 915};
 916
 917  d_revalidate: called when the VFS needs to revalidate a dentry. This
 918        is called whenever a name look-up finds a dentry in the
 919        dcache. Most local filesystems leave this as NULL, because all their
 920        dentries in the dcache are valid. Network filesystems are different
 921        since things can change on the server without the client necessarily
 922        being aware of it.
 923
 924        This function should return a positive value if the dentry is still
 925        valid, and zero or a negative error code if it isn't.
 926
 927        d_revalidate may be called in rcu-walk mode (flags & LOOKUP_RCU).
 928        If in rcu-walk mode, the filesystem must revalidate the dentry without
 929        blocking or storing to the dentry, d_parent and d_inode should not be
 930        used without care (because they can change and, in d_inode case, even
 931        become NULL under us).
 932
 933        If a situation is encountered that rcu-walk cannot handle, return
 934        -ECHILD and it will be called again in ref-walk mode.
 935
 936 d_weak_revalidate: called when the VFS needs to revalidate a "jumped" dentry.
 937        This is called when a path-walk ends at dentry that was not acquired by
 938        doing a lookup in the parent directory. This includes "/", "." and "..",
 939        as well as procfs-style symlinks and mountpoint traversal.
 940
 941        In this case, we are less concerned with whether the dentry is still
 942        fully correct, but rather that the inode is still valid. As with
 943        d_revalidate, most local filesystems will set this to NULL since their
 944        dcache entries are always valid.
 945
 946        This function has the same return code semantics as d_revalidate.
 947
 948        d_weak_revalidate is only called after leaving rcu-walk mode.
 949
 950  d_hash: called when the VFS adds a dentry to the hash table. The first
 951        dentry passed to d_hash is the parent directory that the name is
 952        to be hashed into. The inode is the dentry's inode.
 953
 954        Same locking and synchronisation rules as d_compare regarding
 955        what is safe to dereference etc.
 956
 957  d_compare: called to compare a dentry name with a given name. The first
 958        dentry is the parent of the dentry to be compared, the second is
 959        the parent's inode, then the dentry and inode (may be NULL) of the
 960        child dentry. len and name string are properties of the dentry to be
 961        compared. qstr is the name to compare it with.
 962
 963        Must be constant and idempotent, and should not take locks if
 964        possible, and should not or store into the dentry or inodes.
 965        Should not dereference pointers outside the dentry or inodes without
 966        lots of care (eg.  d_parent, d_inode, d_name should not be used).
 967
 968        However, our vfsmount is pinned, and RCU held, so the dentries and
 969        inodes won't disappear, neither will our sb or filesystem module.
 970        ->i_sb and ->d_sb may be used.
 971
 972        It is a tricky calling convention because it needs to be called under
 973        "rcu-walk", ie. without any locks or references on things.
 974
 975  d_delete: called when the last reference to a dentry is dropped and the
 976        dcache is deciding whether or not to cache it. Return 1 to delete
 977        immediately, or 0 to cache the dentry. Default is NULL which means to
 978        always cache a reachable dentry. d_delete must be constant and
 979        idempotent.
 980
 981  d_release: called when a dentry is really deallocated
 982
 983  d_iput: called when a dentry loses its inode (just prior to its
 984        being deallocated). The default when this is NULL is that the
 985        VFS calls iput(). If you define this method, you must call
 986        iput() yourself
 987
 988  d_dname: called when the pathname of a dentry should be generated.
 989        Useful for some pseudo filesystems (sockfs, pipefs, ...) to delay
 990        pathname generation. (Instead of doing it when dentry is created,
 991        it's done only when the path is needed.). Real filesystems probably
 992        dont want to use it, because their dentries are present in global
 993        dcache hash, so their hash should be an invariant. As no lock is
 994        held, d_dname() should not try to modify the dentry itself, unless
 995        appropriate SMP safety is used. CAUTION : d_path() logic is quite
 996        tricky. The correct way to return for example "Hello" is to put it
 997        at the end of the buffer, and returns a pointer to the first char.
 998        dynamic_dname() helper function is provided to take care of this.
 999
1000  d_automount: called when an automount dentry is to be traversed (optional).
1001        This should create a new VFS mount record and return the record to the
1002        caller.  The caller is supplied with a path parameter giving the
1003        automount directory to describe the automount target and the parent
1004        VFS mount record to provide inheritable mount parameters.  NULL should
1005        be returned if someone else managed to make the automount first.  If
1006        the vfsmount creation failed, then an error code should be returned.
1007        If -EISDIR is returned, then the directory will be treated as an
1008        ordinary directory and returned to pathwalk to continue walking.
1009
1010        If a vfsmount is returned, the caller will attempt to mount it on the
1011        mountpoint and will remove the vfsmount from its expiration list in
1012        the case of failure.  The vfsmount should be returned with 2 refs on
1013        it to prevent automatic expiration - the caller will clean up the
1014        additional ref.
1015
1016        This function is only used if DCACHE_NEED_AUTOMOUNT is set on the
1017        dentry.  This is set by __d_instantiate() if S_AUTOMOUNT is set on the
1018        inode being added.
1019
1020  d_manage: called to allow the filesystem to manage the transition from a
1021        dentry (optional).  This allows autofs, for example, to hold up clients
1022        waiting to explore behind a 'mountpoint' whilst letting the daemon go
1023        past and construct the subtree there.  0 should be returned to let the
1024        calling process continue.  -EISDIR can be returned to tell pathwalk to
1025        use this directory as an ordinary directory and to ignore anything
1026        mounted on it and not to check the automount flag.  Any other error
1027        code will abort pathwalk completely.
1028
1029        If the 'rcu_walk' parameter is true, then the caller is doing a
1030        pathwalk in RCU-walk mode.  Sleeping is not permitted in this mode,
1031        and the caller can be asked to leave it and call again by returning
1032        -ECHILD.
1033
1034        This function is only used if DCACHE_MANAGE_TRANSIT is set on the
1035        dentry being transited from.
1036
1037Example :
1038
1039static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen)
1040{
1041        return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]",
1042                                dentry->d_inode->i_ino);
1043}
1044
1045Each dentry has a pointer to its parent dentry, as well as a hash list
1046of child dentries. Child dentries are basically like files in a
1047directory.
1048
1049
1050Directory Entry Cache API
1051--------------------------
1052
1053There are a number of functions defined which permit a filesystem to
1054manipulate dentries:
1055
1056  dget: open a new handle for an existing dentry (this just increments
1057        the usage count)
1058
1059  dput: close a handle for a dentry (decrements the usage count). If
1060        the usage count drops to 0, and the dentry is still in its
1061        parent's hash, the "d_delete" method is called to check whether
1062        it should be cached. If it should not be cached, or if the dentry
1063        is not hashed, it is deleted. Otherwise cached dentries are put
1064        into an LRU list to be reclaimed on memory shortage.
1065
1066  d_drop: this unhashes a dentry from its parents hash list. A
1067        subsequent call to dput() will deallocate the dentry if its
1068        usage count drops to 0
1069
1070  d_delete: delete a dentry. If there are no other open references to
1071        the dentry then the dentry is turned into a negative dentry
1072        (the d_iput() method is called). If there are other
1073        references, then d_drop() is called instead
1074
1075  d_add: add a dentry to its parents hash list and then calls
1076        d_instantiate()
1077
1078  d_instantiate: add a dentry to the alias hash list for the inode and
1079        updates the "d_inode" member. The "i_count" member in the
1080        inode structure should be set/incremented. If the inode
1081        pointer is NULL, the dentry is called a "negative
1082        dentry". This function is commonly called when an inode is
1083        created for an existing negative dentry
1084
1085  d_lookup: look up a dentry given its parent and path name component
1086        It looks up the child of that given name from the dcache
1087        hash table. If it is found, the reference count is incremented
1088        and the dentry is returned. The caller must use dput()
1089        to free the dentry when it finishes using it.
1090
1091Mount Options
1092=============
1093
1094Parsing options
1095---------------
1096
1097On mount and remount the filesystem is passed a string containing a
1098comma separated list of mount options.  The options can have either of
1099these forms:
1100
1101  option
1102  option=value
1103
1104The <linux/parser.h> header defines an API that helps parse these
1105options.  There are plenty of examples on how to use it in existing
1106filesystems.
1107
1108Showing options
1109---------------
1110
1111If a filesystem accepts mount options, it must define show_options()
1112to show all the currently active options.  The rules are:
1113
1114  - options MUST be shown which are not default or their values differ
1115    from the default
1116
1117  - options MAY be shown which are enabled by default or have their
1118    default value
1119
1120Options used only internally between a mount helper and the kernel
1121(such as file descriptors), or which only have an effect during the
1122mounting (such as ones controlling the creation of a journal) are exempt
1123from the above rules.
1124
1125The underlying reason for the above rules is to make sure, that a
1126mount can be accurately replicated (e.g. umounting and mounting again)
1127based on the information found in /proc/mounts.
1128
1129A simple method of saving options at mount/remount time and showing
1130them is provided with the save_mount_options() and
1131generic_show_options() helper functions.  Please note, that using
1132these may have drawbacks.  For more info see header comments for these
1133functions in fs/namespace.c.
1134
1135Resources
1136=========
1137
1138(Note some of these resources are not up-to-date with the latest kernel
1139 version.)
1140
1141Creating Linux virtual filesystems. 2002
1142    <http://lwn.net/Articles/13325/>
1143
1144The Linux Virtual File-system Layer by Neil Brown. 1999
1145    <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
1146
1147A tour of the Linux VFS by Michael K. Johnson. 1996
1148    <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
1149
1150A small trail through the Linux kernel by Andries Brouwer. 2001
1151    <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>
1152