| 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 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 6 | Last updated on October 28, 2005 | 
| 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 | 
|  | 75 | called so the specific filesystem implementation can do it's 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 | 
|  | 98 | request is made to mount a device onto a directory in your filespace, | 
|  | 99 | the VFS will call the appropriate get_sb() method for the specific | 
|  | 100 | filesystem. The dentry for the mount point will then be updated to | 
|  | 101 | point to the root inode for the new filesystem. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 102 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 103 | You can see all filesystems that are registered to the kernel in the | 
|  | 104 | file /proc/filesystems. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 105 |  | 
|  | 106 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 107 | struct file_system_type | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 108 | ----------------------- | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 109 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 110 | This describes the filesystem. As of kernel 2.6.13, the following | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 111 | members are defined: | 
|  | 112 |  | 
|  | 113 | struct file_system_type { | 
|  | 114 | const char *name; | 
|  | 115 | int fs_flags; | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 116 | struct super_block *(*get_sb) (struct file_system_type *, int, | 
|  | 117 | const char *, void *); | 
|  | 118 | void (*kill_sb) (struct super_block *); | 
|  | 119 | struct module *owner; | 
|  | 120 | struct file_system_type * next; | 
|  | 121 | struct list_head fs_supers; | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 122 | }; | 
|  | 123 |  | 
|  | 124 | name: the name of the filesystem type, such as "ext2", "iso9660", | 
|  | 125 | "msdos" and so on | 
|  | 126 |  | 
|  | 127 | fs_flags: various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.) | 
|  | 128 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 129 | get_sb: the method to call when a new instance of this | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 130 | filesystem should be mounted | 
|  | 131 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 132 | kill_sb: the method to call when an instance of this filesystem | 
|  | 133 | should be unmounted | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 134 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 135 | owner: for internal VFS use: you should initialize this to THIS_MODULE in | 
|  | 136 | most cases. | 
|  | 137 |  | 
|  | 138 | next: for internal VFS use: you should initialize this to NULL | 
|  | 139 |  | 
|  | 140 | The get_sb() method has the following arguments: | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 141 |  | 
|  | 142 | struct super_block *sb: the superblock structure. This is partially | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 143 | initialized by the VFS and the rest must be initialized by the | 
|  | 144 | get_sb() method | 
|  | 145 |  | 
|  | 146 | int flags: mount flags | 
|  | 147 |  | 
|  | 148 | const char *dev_name: the device name we are mounting. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 149 |  | 
|  | 150 | void *data: arbitrary mount options, usually comes as an ASCII | 
|  | 151 | string | 
|  | 152 |  | 
|  | 153 | int silent: whether or not to be silent on error | 
|  | 154 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 155 | The get_sb() method must determine if the block device specified | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 156 | in the superblock contains a filesystem of the type the method | 
|  | 157 | supports. On success the method returns the superblock pointer, on | 
|  | 158 | failure it returns NULL. | 
|  | 159 |  | 
|  | 160 | The most interesting member of the superblock structure that the | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 161 | get_sb() 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] | 162 | a "struct super_operations" which describes the next level of the | 
|  | 163 | filesystem implementation. | 
|  | 164 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 165 | Usually, a filesystem uses generic one of the generic get_sb() | 
|  | 166 | implementations and provides a fill_super() method instead. The | 
|  | 167 | generic methods are: | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 168 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 169 | get_sb_bdev: mount a filesystem residing on a block device | 
|  | 170 |  | 
|  | 171 | get_sb_nodev: mount a filesystem that is not backed by a device | 
|  | 172 |  | 
|  | 173 | get_sb_single: mount a filesystem which shares the instance between | 
|  | 174 | all mounts | 
|  | 175 |  | 
|  | 176 | A fill_super() method implementation has the following arguments: | 
|  | 177 |  | 
|  | 178 | struct super_block *sb: the superblock structure. The method fill_super() | 
|  | 179 | must initialize this properly. | 
|  | 180 |  | 
|  | 181 | void *data: arbitrary mount options, usually comes as an ASCII | 
|  | 182 | string | 
|  | 183 |  | 
|  | 184 | int silent: whether or not to be silent on error | 
|  | 185 |  | 
|  | 186 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 187 | The Superblock Object | 
|  | 188 | ===================== | 
|  | 189 |  | 
|  | 190 | A superblock object represents a mounted filesystem. | 
|  | 191 |  | 
|  | 192 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 193 | struct super_operations | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 194 | ----------------------- | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 195 |  | 
|  | 196 | This describes how the VFS can manipulate the superblock of your | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 197 | filesystem. As of kernel 2.6.13, the following members are defined: | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 198 |  | 
|  | 199 | struct super_operations { | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 200 | struct inode *(*alloc_inode)(struct super_block *sb); | 
|  | 201 | void (*destroy_inode)(struct inode *); | 
|  | 202 |  | 
|  | 203 | void (*read_inode) (struct inode *); | 
|  | 204 |  | 
|  | 205 | void (*dirty_inode) (struct inode *); | 
|  | 206 | int (*write_inode) (struct inode *, int); | 
|  | 207 | void (*put_inode) (struct inode *); | 
|  | 208 | void (*drop_inode) (struct inode *); | 
|  | 209 | void (*delete_inode) (struct inode *); | 
|  | 210 | void (*put_super) (struct super_block *); | 
|  | 211 | void (*write_super) (struct super_block *); | 
|  | 212 | int (*sync_fs)(struct super_block *sb, int wait); | 
|  | 213 | void (*write_super_lockfs) (struct super_block *); | 
|  | 214 | void (*unlockfs) (struct super_block *); | 
|  | 215 | int (*statfs) (struct super_block *, struct kstatfs *); | 
|  | 216 | int (*remount_fs) (struct super_block *, int *, char *); | 
|  | 217 | void (*clear_inode) (struct inode *); | 
|  | 218 | void (*umount_begin) (struct super_block *); | 
|  | 219 |  | 
|  | 220 | void (*sync_inodes) (struct super_block *sb, | 
|  | 221 | struct writeback_control *wbc); | 
|  | 222 | int (*show_options)(struct seq_file *, struct vfsmount *); | 
|  | 223 |  | 
|  | 224 | ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); | 
|  | 225 | ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 226 | }; | 
|  | 227 |  | 
|  | 228 | All methods are called without any locks being held, unless otherwise | 
|  | 229 | noted. This means that most methods can block safely. All methods are | 
|  | 230 | only called from a process context (i.e. not from an interrupt handler | 
|  | 231 | or bottom half). | 
|  | 232 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 233 | alloc_inode: this method is called by inode_alloc() to allocate memory | 
|  | 234 | for struct inode and initialize it. | 
|  | 235 |  | 
|  | 236 | destroy_inode: this method is called by destroy_inode() to release | 
|  | 237 | resources allocated for struct inode. | 
|  | 238 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 239 | read_inode: this method is called to read a specific inode from the | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 240 | mounted filesystem.  The i_ino member in the struct inode is | 
|  | 241 | initialized by the VFS to indicate which inode to read. Other | 
|  | 242 | members are filled in by this method. | 
|  | 243 |  | 
|  | 244 | You can set this to NULL and use iget5_locked() instead of iget() | 
|  | 245 | to read inodes.  This is necessary for filesystems for which the | 
|  | 246 | inode number is not sufficient to identify an inode. | 
|  | 247 |  | 
|  | 248 | 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] | 249 |  | 
|  | 250 | write_inode: this method is called when the VFS needs to write an | 
|  | 251 | inode to disc.  The second parameter indicates whether the write | 
|  | 252 | should be synchronous or not, not all filesystems check this flag. | 
|  | 253 |  | 
|  | 254 | put_inode: called when the VFS inode is removed from the inode | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 255 | cache. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 256 |  | 
|  | 257 | drop_inode: called when the last access to the inode is dropped, | 
|  | 258 | with the inode_lock spinlock held. | 
|  | 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 |  | 
|  | 275 | write_super: called when the VFS superblock needs to be written to | 
|  | 276 | disc. This method is optional | 
|  | 277 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 278 | sync_fs: called when VFS is writing out all dirty data associated with | 
|  | 279 | a superblock. The second parameter indicates whether the method | 
|  | 280 | should wait until the write out has been completed. Optional. | 
|  | 281 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 282 | write_super_lockfs: called when VFS is locking a filesystem and | 
|  | 283 | forcing it into a consistent state.  This method is currently | 
|  | 284 | used by the Logical Volume Manager (LVM). | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 285 |  | 
|  | 286 | unlockfs: called when VFS is unlocking a filesystem and making it writable | 
|  | 287 | again. | 
|  | 288 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 289 | statfs: called when the VFS needs to get filesystem statistics. This | 
|  | 290 | is called with the kernel lock held | 
|  | 291 |  | 
|  | 292 | remount_fs: called when the filesystem is remounted. This is called | 
|  | 293 | with the kernel lock held | 
|  | 294 |  | 
|  | 295 | clear_inode: called then the VFS clears the inode. Optional | 
|  | 296 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 297 | umount_begin: called when the VFS is unmounting a filesystem. | 
|  | 298 |  | 
|  | 299 | sync_inodes: called when the VFS is writing out dirty data associated with | 
|  | 300 | a superblock. | 
|  | 301 |  | 
|  | 302 | show_options: called by the VFS to show mount options for /proc/<pid>/mounts. | 
|  | 303 |  | 
|  | 304 | quota_read: called by the VFS to read from filesystem quota file. | 
|  | 305 |  | 
|  | 306 | quota_write: called by the VFS to write to filesystem quota file. | 
|  | 307 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 308 | The read_inode() method is responsible for filling in the "i_op" | 
|  | 309 | field. This is a pointer to a "struct inode_operations" which | 
|  | 310 | describes the methods that can be performed on individual inodes. | 
|  | 311 |  | 
|  | 312 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 313 | The Inode Object | 
|  | 314 | ================ | 
|  | 315 |  | 
|  | 316 | An inode object represents an object within the filesystem. | 
|  | 317 |  | 
|  | 318 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 319 | struct inode_operations | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 320 | ----------------------- | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 321 |  | 
|  | 322 | This describes how the VFS can manipulate an inode in your | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 323 | filesystem. As of kernel 2.6.13, the following members are defined: | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 324 |  | 
|  | 325 | struct inode_operations { | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 326 | int (*create) (struct inode *,struct dentry *,int, struct nameidata *); | 
|  | 327 | struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 328 | int (*link) (struct dentry *,struct inode *,struct dentry *); | 
|  | 329 | int (*unlink) (struct inode *,struct dentry *); | 
|  | 330 | int (*symlink) (struct inode *,struct dentry *,const char *); | 
|  | 331 | int (*mkdir) (struct inode *,struct dentry *,int); | 
|  | 332 | int (*rmdir) (struct inode *,struct dentry *); | 
|  | 333 | int (*mknod) (struct inode *,struct dentry *,int,dev_t); | 
|  | 334 | int (*rename) (struct inode *, struct dentry *, | 
|  | 335 | struct inode *, struct dentry *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 336 | int (*readlink) (struct dentry *, char __user *,int); | 
|  | 337 | void * (*follow_link) (struct dentry *, struct nameidata *); | 
|  | 338 | void (*put_link) (struct dentry *, struct nameidata *, void *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 339 | void (*truncate) (struct inode *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 340 | int (*permission) (struct inode *, int, struct nameidata *); | 
|  | 341 | int (*setattr) (struct dentry *, struct iattr *); | 
|  | 342 | int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *); | 
|  | 343 | int (*setxattr) (struct dentry *, const char *,const void *,size_t,int); | 
|  | 344 | ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t); | 
|  | 345 | ssize_t (*listxattr) (struct dentry *, char *, size_t); | 
|  | 346 | int (*removexattr) (struct dentry *, const char *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 347 | }; | 
|  | 348 |  | 
|  | 349 | Again, all methods are called without any locks being held, unless | 
|  | 350 | otherwise noted. | 
|  | 351 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 352 | create: called by the open(2) and creat(2) system calls. Only | 
|  | 353 | required if you want to support regular files. The dentry you | 
|  | 354 | get should not have an inode (i.e. it should be a negative | 
|  | 355 | dentry). Here you will probably call d_instantiate() with the | 
|  | 356 | dentry and the newly created inode | 
|  | 357 |  | 
|  | 358 | lookup: called when the VFS needs to look up an inode in a parent | 
|  | 359 | directory. The name to look for is found in the dentry. This | 
|  | 360 | method must call d_add() to insert the found inode into the | 
|  | 361 | dentry. The "i_count" field in the inode structure should be | 
|  | 362 | incremented. If the named inode does not exist a NULL inode | 
|  | 363 | should be inserted into the dentry (this is called a negative | 
|  | 364 | dentry). Returning an error code from this routine must only | 
|  | 365 | be done on a real error, otherwise creating inodes with system | 
|  | 366 | calls like create(2), mknod(2), mkdir(2) and so on will fail. | 
|  | 367 | If you wish to overload the dentry methods then you should | 
|  | 368 | initialise the "d_dop" field in the dentry; this is a pointer | 
|  | 369 | to a struct "dentry_operations". | 
|  | 370 | This method is called with the directory inode semaphore held | 
|  | 371 |  | 
|  | 372 | link: called by the link(2) system call. Only required if you want | 
|  | 373 | to support hard links. You will probably need to call | 
|  | 374 | d_instantiate() just as you would in the create() method | 
|  | 375 |  | 
|  | 376 | unlink: called by the unlink(2) system call. Only required if you | 
|  | 377 | want to support deleting inodes | 
|  | 378 |  | 
|  | 379 | symlink: called by the symlink(2) system call. Only required if you | 
|  | 380 | want to support symlinks. You will probably need to call | 
|  | 381 | d_instantiate() just as you would in the create() method | 
|  | 382 |  | 
|  | 383 | mkdir: called by the mkdir(2) system call. Only required if you want | 
|  | 384 | to support creating subdirectories. You will probably need to | 
|  | 385 | call d_instantiate() just as you would in the create() method | 
|  | 386 |  | 
|  | 387 | rmdir: called by the rmdir(2) system call. Only required if you want | 
|  | 388 | to support deleting subdirectories | 
|  | 389 |  | 
|  | 390 | mknod: called by the mknod(2) system call to create a device (char, | 
|  | 391 | block) inode or a named pipe (FIFO) or socket. Only required | 
|  | 392 | if you want to support creating these types of inodes. You | 
|  | 393 | will probably need to call d_instantiate() just as you would | 
|  | 394 | in the create() method | 
|  | 395 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 396 | rename: called by the rename(2) system call to rename the object to | 
|  | 397 | have the parent and name given by the second inode and dentry. | 
|  | 398 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 399 | readlink: called by the readlink(2) system call. Only required if | 
|  | 400 | you want to support reading symbolic links | 
|  | 401 |  | 
|  | 402 | follow_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] | 403 | inode it points to.  Only required if you want to support | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 404 | symbolic links.  This method returns a void pointer cookie | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 405 | that is passed to put_link(). | 
|  | 406 |  | 
|  | 407 | put_link: called by the VFS to release resources allocated by | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 408 | follow_link().  The cookie returned by follow_link() is passed | 
|  | 409 | to to this method as the last parameter.  It is used by | 
|  | 410 | filesystems such as NFS where page cache is not stable | 
|  | 411 | (i.e. page that was installed when the symbolic link walk | 
|  | 412 | started might not be in the page cache at the end of the | 
|  | 413 | walk). | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 414 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 415 | truncate: called by the VFS to change the size of a file.  The | 
|  | 416 | i_size field of the inode is set to the desired size by the | 
|  | 417 | VFS before this method is called.  This method is called by | 
|  | 418 | the truncate(2) system call and related functionality. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 419 |  | 
|  | 420 | permission: called by the VFS to check for access rights on a POSIX-like | 
|  | 421 | filesystem. | 
|  | 422 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 423 | setattr: called by the VFS to set attributes for a file. This method | 
|  | 424 | is called by chmod(2) and related system calls. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 425 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 426 | getattr: called by the VFS to get attributes of a file. This method | 
|  | 427 | is called by stat(2) and related system calls. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 428 |  | 
|  | 429 | 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] | 430 | Extended attribute is a name:value pair associated with an | 
|  | 431 | inode. This method is called by setxattr(2) system call. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 432 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 433 | getxattr: called by the VFS to retrieve the value of an extended | 
|  | 434 | attribute name. This method is called by getxattr(2) function | 
|  | 435 | call. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 436 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 437 | listxattr: called by the VFS to list all extended attributes for a | 
|  | 438 | given file. This method is called by listxattr(2) system call. | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 439 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 440 | removexattr: called by the VFS to remove an extended attribute from | 
|  | 441 | a file. This method is called by removexattr(2) system call. | 
|  | 442 |  | 
|  | 443 |  | 
|  | 444 | The Address Space Object | 
|  | 445 | ======================== | 
|  | 446 |  | 
|  | 447 | The address space object is used to identify pages in the page cache. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 448 |  | 
|  | 449 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 450 | struct address_space_operations | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 451 | ------------------------------- | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 452 |  | 
|  | 453 | This describes how the VFS can manipulate mapping of a file to page cache in | 
|  | 454 | your filesystem. As of kernel 2.6.13, the following members are defined: | 
|  | 455 |  | 
|  | 456 | struct address_space_operations { | 
|  | 457 | int (*writepage)(struct page *page, struct writeback_control *wbc); | 
|  | 458 | int (*readpage)(struct file *, struct page *); | 
|  | 459 | int (*sync_page)(struct page *); | 
|  | 460 | int (*writepages)(struct address_space *, struct writeback_control *); | 
|  | 461 | int (*set_page_dirty)(struct page *page); | 
|  | 462 | int (*readpages)(struct file *filp, struct address_space *mapping, | 
|  | 463 | struct list_head *pages, unsigned nr_pages); | 
|  | 464 | int (*prepare_write)(struct file *, struct page *, unsigned, unsigned); | 
|  | 465 | int (*commit_write)(struct file *, struct page *, unsigned, unsigned); | 
|  | 466 | sector_t (*bmap)(struct address_space *, sector_t); | 
|  | 467 | int (*invalidatepage) (struct page *, unsigned long); | 
|  | 468 | int (*releasepage) (struct page *, int); | 
|  | 469 | ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov, | 
|  | 470 | loff_t offset, unsigned long nr_segs); | 
|  | 471 | struct page* (*get_xip_page)(struct address_space *, sector_t, | 
|  | 472 | int); | 
|  | 473 | }; | 
|  | 474 |  | 
|  | 475 | writepage: called by the VM write a dirty page to backing store. | 
|  | 476 |  | 
|  | 477 | readpage: called by the VM to read a page from backing store. | 
|  | 478 |  | 
|  | 479 | sync_page: called by the VM to notify the backing store to perform all | 
|  | 480 | queued I/O operations for a page. I/O operations for other pages | 
|  | 481 | associated with this address_space object may also be performed. | 
|  | 482 |  | 
|  | 483 | writepages: called by the VM to write out pages associated with the | 
|  | 484 | address_space object. | 
|  | 485 |  | 
|  | 486 | set_page_dirty: called by the VM to set a page dirty. | 
|  | 487 |  | 
|  | 488 | readpages: called by the VM to read pages associated with the address_space | 
|  | 489 | object. | 
|  | 490 |  | 
|  | 491 | prepare_write: called by the generic write path in VM to set up a write | 
|  | 492 | request for a page. | 
|  | 493 |  | 
|  | 494 | commit_write: called by the generic write path in VM to write page to | 
|  | 495 | its backing store. | 
|  | 496 |  | 
|  | 497 | bmap: called by the VFS to map a logical block offset within object to | 
|  | 498 | physical block number. This method is use by for the legacy FIBMAP | 
|  | 499 | ioctl. Other uses are discouraged. | 
|  | 500 |  | 
|  | 501 | invalidatepage: called by the VM on truncate to disassociate a page from its | 
|  | 502 | address_space mapping. | 
|  | 503 |  | 
|  | 504 | releasepage: called by the VFS to release filesystem specific metadata from | 
|  | 505 | a page. | 
|  | 506 |  | 
|  | 507 | direct_IO: called by the VM for direct I/O writes and reads. | 
|  | 508 |  | 
|  | 509 | get_xip_page: called by the VM to translate a block number to a page. | 
|  | 510 | The page is valid until the corresponding filesystem is unmounted. | 
|  | 511 | Filesystems that want to use execute-in-place (XIP) need to implement | 
|  | 512 | it.  An example implementation can be found in fs/ext2/xip.c. | 
|  | 513 |  | 
|  | 514 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 515 | The File Object | 
|  | 516 | =============== | 
|  | 517 |  | 
|  | 518 | A file object represents a file opened by a process. | 
|  | 519 |  | 
|  | 520 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 521 | struct file_operations | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 522 | ---------------------- | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 523 |  | 
|  | 524 | This describes how the VFS can manipulate an open file. As of kernel | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 525 | 2.6.13, the following members are defined: | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 526 |  | 
|  | 527 | struct file_operations { | 
|  | 528 | loff_t (*llseek) (struct file *, loff_t, int); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 529 | ssize_t (*read) (struct file *, char __user *, size_t, loff_t *); | 
|  | 530 | ssize_t (*aio_read) (struct kiocb *, char __user *, size_t, loff_t); | 
|  | 531 | ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *); | 
|  | 532 | ssize_t (*aio_write) (struct kiocb *, const char __user *, size_t, loff_t); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 533 | int (*readdir) (struct file *, void *, filldir_t); | 
|  | 534 | unsigned int (*poll) (struct file *, struct poll_table_struct *); | 
|  | 535 | int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 536 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); | 
|  | 537 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 538 | int (*mmap) (struct file *, struct vm_area_struct *); | 
|  | 539 | int (*open) (struct inode *, struct file *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 540 | int (*flush) (struct file *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 541 | int (*release) (struct inode *, struct file *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 542 | int (*fsync) (struct file *, struct dentry *, int datasync); | 
|  | 543 | int (*aio_fsync) (struct kiocb *, int datasync); | 
|  | 544 | int (*fasync) (int, struct file *, int); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 545 | int (*lock) (struct file *, int, struct file_lock *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 546 | ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *); | 
|  | 547 | ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *); | 
|  | 548 | ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *); | 
|  | 549 | ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int); | 
|  | 550 | unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long); | 
|  | 551 | int (*check_flags)(int); | 
|  | 552 | int (*dir_notify)(struct file *filp, unsigned long arg); | 
|  | 553 | int (*flock) (struct file *, int, struct file_lock *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 554 | }; | 
|  | 555 |  | 
|  | 556 | Again, all methods are called without any locks being held, unless | 
|  | 557 | otherwise noted. | 
|  | 558 |  | 
|  | 559 | llseek: called when the VFS needs to move the file position index | 
|  | 560 |  | 
|  | 561 | read: called by read(2) and related system calls | 
|  | 562 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 563 | aio_read: called by io_submit(2) and other asynchronous I/O operations | 
|  | 564 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 565 | write: called by write(2) and related system calls | 
|  | 566 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 567 | aio_write: called by io_submit(2) and other asynchronous I/O operations | 
|  | 568 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 569 | readdir: called when the VFS needs to read the directory contents | 
|  | 570 |  | 
|  | 571 | poll: called by the VFS when a process wants to check if there is | 
|  | 572 | activity on this file and (optionally) go to sleep until there | 
|  | 573 | is activity. Called by the select(2) and poll(2) system calls | 
|  | 574 |  | 
|  | 575 | ioctl: called by the ioctl(2) system call | 
|  | 576 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 577 | unlocked_ioctl: called by the ioctl(2) system call. Filesystems that do not | 
|  | 578 | require the BKL should use this method instead of the ioctl() above. | 
|  | 579 |  | 
|  | 580 | compat_ioctl: called by the ioctl(2) system call when 32 bit system calls | 
|  | 581 | are used on 64 bit kernels. | 
|  | 582 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 583 | mmap: called by the mmap(2) system call | 
|  | 584 |  | 
|  | 585 | 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] | 586 | opens a file, it creates a new "struct file". It then calls the | 
|  | 587 | open method for the newly allocated file structure. You might | 
|  | 588 | think that the open method really belongs in | 
|  | 589 | "struct inode_operations", and you may be right. I think it's | 
|  | 590 | done the way it is because it makes filesystems simpler to | 
|  | 591 | implement. The open() method is a good place to initialize the | 
|  | 592 | "private_data" member in the file structure if you want to point | 
|  | 593 | to a device structure | 
|  | 594 |  | 
|  | 595 | flush: called by the close(2) system call to flush a file | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 596 |  | 
|  | 597 | release: called when the last reference to an open file is closed | 
|  | 598 |  | 
|  | 599 | fsync: called by the fsync(2) system call | 
|  | 600 |  | 
|  | 601 | fasync: called by the fcntl(2) system call when asynchronous | 
|  | 602 | (non-blocking) mode is enabled for a file | 
|  | 603 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 604 | lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW | 
|  | 605 | commands | 
|  | 606 |  | 
|  | 607 | readv: called by the readv(2) system call | 
|  | 608 |  | 
|  | 609 | writev: called by the writev(2) system call | 
|  | 610 |  | 
|  | 611 | sendfile: called by the sendfile(2) system call | 
|  | 612 |  | 
|  | 613 | get_unmapped_area: called by the mmap(2) system call | 
|  | 614 |  | 
|  | 615 | check_flags: called by the fcntl(2) system call for F_SETFL command | 
|  | 616 |  | 
|  | 617 | dir_notify: called by the fcntl(2) system call for F_NOTIFY command | 
|  | 618 |  | 
|  | 619 | flock: called by the flock(2) system call | 
|  | 620 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 621 | Note that the file operations are implemented by the specific | 
|  | 622 | filesystem in which the inode resides. When opening a device node | 
|  | 623 | (character or block special) most filesystems will call special | 
|  | 624 | support routines in the VFS which will locate the required device | 
|  | 625 | driver information. These support routines replace the filesystem file | 
|  | 626 | operations with those for the device driver, and then proceed to call | 
|  | 627 | the new open() method for the file. This is how opening a device file | 
|  | 628 | in the filesystem eventually ends up calling the device driver open() | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 629 | method. | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 630 |  | 
|  | 631 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 632 | Directory Entry Cache (dcache) | 
|  | 633 | ============================== | 
|  | 634 |  | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 635 |  | 
|  | 636 | struct dentry_operations | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 637 | ------------------------ | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 638 |  | 
|  | 639 | This describes how a filesystem can overload the standard dentry | 
|  | 640 | operations. Dentries and the dcache are the domain of the VFS and the | 
|  | 641 | individual filesystem implementations. Device drivers have no business | 
|  | 642 | here. These methods may be set to NULL, as they are either optional or | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 643 | the VFS uses a default. As of kernel 2.6.13, the following members are | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 644 | defined: | 
|  | 645 |  | 
|  | 646 | struct dentry_operations { | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 647 | int (*d_revalidate)(struct dentry *, struct nameidata *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 648 | int (*d_hash) (struct dentry *, struct qstr *); | 
|  | 649 | int (*d_compare) (struct dentry *, struct qstr *, struct qstr *); | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 650 | int (*d_delete)(struct dentry *); | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 651 | void (*d_release)(struct dentry *); | 
|  | 652 | void (*d_iput)(struct dentry *, struct inode *); | 
|  | 653 | }; | 
|  | 654 |  | 
|  | 655 | d_revalidate: called when the VFS needs to revalidate a dentry. This | 
|  | 656 | is called whenever a name look-up finds a dentry in the | 
|  | 657 | dcache. Most filesystems leave this as NULL, because all their | 
|  | 658 | dentries in the dcache are valid | 
|  | 659 |  | 
|  | 660 | d_hash: called when the VFS adds a dentry to the hash table | 
|  | 661 |  | 
|  | 662 | d_compare: called when a dentry should be compared with another | 
|  | 663 |  | 
|  | 664 | d_delete: called when the last reference to a dentry is | 
|  | 665 | deleted. This means no-one is using the dentry, however it is | 
|  | 666 | still valid and in the dcache | 
|  | 667 |  | 
|  | 668 | d_release: called when a dentry is really deallocated | 
|  | 669 |  | 
|  | 670 | d_iput: called when a dentry loses its inode (just prior to its | 
|  | 671 | being deallocated). The default when this is NULL is that the | 
|  | 672 | VFS calls iput(). If you define this method, you must call | 
|  | 673 | iput() yourself | 
|  | 674 |  | 
|  | 675 | Each dentry has a pointer to its parent dentry, as well as a hash list | 
|  | 676 | of child dentries. Child dentries are basically like files in a | 
|  | 677 | directory. | 
|  | 678 |  | 
| Pekka J Enberg | 5ea626a | 2005-09-09 13:10:19 -0700 | [diff] [blame] | 679 |  | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 680 | Directory Entry Cache API | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 681 | -------------------------- | 
|  | 682 |  | 
|  | 683 | There are a number of functions defined which permit a filesystem to | 
|  | 684 | manipulate dentries: | 
|  | 685 |  | 
|  | 686 | dget: open a new handle for an existing dentry (this just increments | 
|  | 687 | the usage count) | 
|  | 688 |  | 
|  | 689 | dput: close a handle for a dentry (decrements the usage count). If | 
|  | 690 | the usage count drops to 0, the "d_delete" method is called | 
|  | 691 | and the dentry is placed on the unused list if the dentry is | 
|  | 692 | still in its parents hash list. Putting the dentry on the | 
|  | 693 | unused list just means that if the system needs some RAM, it | 
|  | 694 | goes through the unused list of dentries and deallocates them. | 
|  | 695 | If the dentry has already been unhashed and the usage count | 
|  | 696 | drops to 0, in this case the dentry is deallocated after the | 
|  | 697 | "d_delete" method is called | 
|  | 698 |  | 
|  | 699 | 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] | 700 | subsequent call to dput() will deallocate the dentry if its | 
| Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 701 | usage count drops to 0 | 
|  | 702 |  | 
|  | 703 | d_delete: delete a dentry. If there are no other open references to | 
|  | 704 | the dentry then the dentry is turned into a negative dentry | 
|  | 705 | (the d_iput() method is called). If there are other | 
|  | 706 | references, then d_drop() is called instead | 
|  | 707 |  | 
|  | 708 | d_add: add a dentry to its parents hash list and then calls | 
|  | 709 | d_instantiate() | 
|  | 710 |  | 
|  | 711 | d_instantiate: add a dentry to the alias hash list for the inode and | 
|  | 712 | updates the "d_inode" member. The "i_count" member in the | 
|  | 713 | inode structure should be set/incremented. If the inode | 
|  | 714 | pointer is NULL, the dentry is called a "negative | 
|  | 715 | dentry". This function is commonly called when an inode is | 
|  | 716 | created for an existing negative dentry | 
|  | 717 |  | 
|  | 718 | d_lookup: look up a dentry given its parent and path name component | 
|  | 719 | It looks up the child of that given name from the dcache | 
|  | 720 | hash table. If it is found, the reference count is incremented | 
|  | 721 | and the dentry is returned. The caller must use d_put() | 
|  | 722 | to free the dentry when it finishes using it. | 
|  | 723 |  | 
| Pekka Enberg | cbf8f0f | 2005-11-07 01:01:09 -0800 | [diff] [blame] | 724 | For further information on dentry locking, please refer to the document | 
|  | 725 | Documentation/filesystems/dentry-locking.txt. | 
| Pekka Enberg | cc7d1f8 | 2005-11-07 01:01:08 -0800 | [diff] [blame] | 726 |  | 
|  | 727 |  | 
|  | 728 | Resources | 
|  | 729 | ========= | 
|  | 730 |  | 
|  | 731 | (Note some of these resources are not up-to-date with the latest kernel | 
|  | 732 | version.) | 
|  | 733 |  | 
|  | 734 | Creating Linux virtual filesystems. 2002 | 
|  | 735 | <http://lwn.net/Articles/13325/> | 
|  | 736 |  | 
|  | 737 | The Linux Virtual File-system Layer by Neil Brown. 1999 | 
|  | 738 | <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> | 
|  | 739 |  | 
|  | 740 | A tour of the Linux VFS by Michael K. Johnson. 1996 | 
|  | 741 | <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> | 
|  | 742 |  | 
|  | 743 | A small trail through the Linux kernel by Andries Brouwer. 2001 | 
|  | 744 | <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> |