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