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