blob: e56e842847d3ee3e48c79b4099bc0d6040d730a1 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001
Pekka J Enberg5ea626a2005-09-09 13:10:19 -07002 Overview of the Linux Virtual File System
Linus Torvalds1da177e2005-04-16 15:20:36 -07003
Pekka J Enberg5ea626a2005-09-09 13:10:19 -07004 Original author: Richard Gooch <rgooch@atnf.csiro.au>
Linus Torvalds1da177e2005-04-16 15:20:36 -07005
Pekka Enbergcc7d1f82005-11-07 01:01:08 -08006 Last updated on October 28, 2005
Pekka J Enberg5ea626a2005-09-09 13:10:19 -07007
8 Copyright (C) 1999 Richard Gooch
9 Copyright (C) 2005 Pekka Enberg
10
11 This file is released under the GPLv2.
Linus Torvalds1da177e2005-04-16 15:20:36 -070012
13
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080014Introduction
15============
Linus Torvalds1da177e2005-04-16 15:20:36 -070016
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080017The Virtual File System (also known as the Virtual Filesystem Switch)
18is the software layer in the kernel that provides the filesystem
19interface to userspace programs. It also provides an abstraction
20within the kernel which allows different filesystem implementations to
21coexist.
22
23VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so
24on are called from a process context. Filesystem locking is described
25in the document Documentation/filesystems/Locking.
Linus Torvalds1da177e2005-04-16 15:20:36 -070026
27
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080028Directory Entry Cache (dcache)
29------------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -070030
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080031The VFS implements the open(2), stat(2), chmod(2), and similar system
32calls. The pathname argument that is passed to them is used by the VFS
33to search through the directory entry cache (also known as the dentry
34cache or dcache). This provides a very fast look-up mechanism to
35translate a pathname (filename) into a specific dentry. Dentries live
36in RAM and are never saved to disc: they exist only for performance.
37
38The dentry cache is meant to be a view into your entire filespace. As
39most computers cannot fit all dentries in the RAM at the same time,
40some bits of the cache are missing. In order to resolve your pathname
41into a dentry, the VFS may have to resort to creating dentries along
42the way, and then loading the inode. This is done by looking up the
43inode.
Linus Torvalds1da177e2005-04-16 15:20:36 -070044
Pekka J Enberg5ea626a2005-09-09 13:10:19 -070045
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080046The Inode Object
47----------------
Linus Torvalds1da177e2005-04-16 15:20:36 -070048
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080049An individual dentry usually has a pointer to an inode. Inodes are
50filesystem objects such as regular files, directories, FIFOs and other
51beasts. They live either on the disc (for block device filesystems)
52or in the memory (for pseudo filesystems). Inodes that live on the
53disc are copied into the memory when required and changes to the inode
54are written back to disc. A single inode can be pointed to by multiple
55dentries (hard links, for example, do this).
Linus Torvalds1da177e2005-04-16 15:20:36 -070056
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080057To look up an inode requires that the VFS calls the lookup() method of
58the parent directory inode. This method is installed by the specific
59filesystem implementation that the inode lives in. Once the VFS has
60the required dentry (and hence the inode), we can do all those boring
61things like open(2) the file, or stat(2) it to peek at the inode
62data. The stat(2) operation is fairly simple: once the VFS has the
63dentry, it peeks at the inode data and passes some of it back to
64userspace.
Linus Torvalds1da177e2005-04-16 15:20:36 -070065
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080067The File Object
68---------------
Linus Torvalds1da177e2005-04-16 15:20:36 -070069
70Opening a file requires another operation: allocation of a file
71structure (this is the kernel-side implementation of file
Pekka J Enberg5ea626a2005-09-09 13:10:19 -070072descriptors). The freshly allocated file structure is initialized with
Linus Torvalds1da177e2005-04-16 15:20:36 -070073a pointer to the dentry and a set of file operation member functions.
74These are taken from the inode data. The open() file method is then
75called so the specific filesystem implementation can do it's work. You
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080076can see that this is another switch performed by the VFS. The file
77structure is placed into the file descriptor table for the process.
Linus Torvalds1da177e2005-04-16 15:20:36 -070078
79Reading, writing and closing files (and other assorted VFS operations)
80is done by using the userspace file descriptor to grab the appropriate
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080081file structure, and then calling the required file structure method to
82do whatever is required. For as long as the file is open, it keeps the
83dentry in use, which in turn means that the VFS inode is still in use.
Linus Torvalds1da177e2005-04-16 15:20:36 -070084
Pekka J Enberg5ea626a2005-09-09 13:10:19 -070085
86Registering and Mounting a Filesystem
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080087=====================================
Linus Torvalds1da177e2005-04-16 15:20:36 -070088
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080089To register and unregister a filesystem, use the following API
90functions:
Linus Torvalds1da177e2005-04-16 15:20:36 -070091
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080092 #include <linux/fs.h>
Linus Torvalds1da177e2005-04-16 15:20:36 -070093
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080094 extern int register_filesystem(struct file_system_type *);
95 extern int unregister_filesystem(struct file_system_type *);
Linus Torvalds1da177e2005-04-16 15:20:36 -070096
Pekka Enbergcc7d1f82005-11-07 01:01:08 -080097The passed struct file_system_type describes your filesystem. When a
98request is made to mount a device onto a directory in your filespace,
99the VFS will call the appropriate get_sb() method for the specific
100filesystem. The dentry for the mount point will then be updated to
101point to the root inode for the new filesystem.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700102
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800103You can see all filesystems that are registered to the kernel in the
104file /proc/filesystems.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700105
106
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700107struct file_system_type
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800108-----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700109
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700110This describes the filesystem. As of kernel 2.6.13, the following
Linus Torvalds1da177e2005-04-16 15:20:36 -0700111members are defined:
112
113struct file_system_type {
114 const char *name;
115 int fs_flags;
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700116 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 Torvalds1da177e2005-04-16 15:20:36 -0700122};
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 Enberg5ea626a2005-09-09 13:10:19 -0700129 get_sb: the method to call when a new instance of this
Linus Torvalds1da177e2005-04-16 15:20:36 -0700130 filesystem should be mounted
131
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700132 kill_sb: the method to call when an instance of this filesystem
133 should be unmounted
Linus Torvalds1da177e2005-04-16 15:20:36 -0700134
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700135 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
140The get_sb() method has the following arguments:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141
142 struct super_block *sb: the superblock structure. This is partially
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700143 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 Torvalds1da177e2005-04-16 15:20:36 -0700149
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 Enberg5ea626a2005-09-09 13:10:19 -0700155The get_sb() method must determine if the block device specified
Linus Torvalds1da177e2005-04-16 15:20:36 -0700156in the superblock contains a filesystem of the type the method
157supports. On success the method returns the superblock pointer, on
158failure it returns NULL.
159
160The most interesting member of the superblock structure that the
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700161get_sb() method fills in is the "s_op" field. This is a pointer to
Linus Torvalds1da177e2005-04-16 15:20:36 -0700162a "struct super_operations" which describes the next level of the
163filesystem implementation.
164
Jim Cromiee3e1bfe2006-01-03 13:35:41 +0100165Usually, a filesystem uses one of the generic get_sb() implementations
166and provides a fill_super() method instead. The generic methods are:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700167
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700168 get_sb_bdev: mount a filesystem residing on a block device
169
170 get_sb_nodev: mount a filesystem that is not backed by a device
171
172 get_sb_single: mount a filesystem which shares the instance between
173 all mounts
174
175A fill_super() method implementation has the following arguments:
176
177 struct super_block *sb: the superblock structure. The method fill_super()
178 must initialize this properly.
179
180 void *data: arbitrary mount options, usually comes as an ASCII
181 string
182
183 int silent: whether or not to be silent on error
184
185
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800186The Superblock Object
187=====================
188
189A superblock object represents a mounted filesystem.
190
191
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700192struct super_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800193-----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700194
195This describes how the VFS can manipulate the superblock of your
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700196filesystem. As of kernel 2.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700197
198struct super_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700199 struct inode *(*alloc_inode)(struct super_block *sb);
200 void (*destroy_inode)(struct inode *);
201
202 void (*read_inode) (struct inode *);
203
204 void (*dirty_inode) (struct inode *);
205 int (*write_inode) (struct inode *, int);
206 void (*put_inode) (struct inode *);
207 void (*drop_inode) (struct inode *);
208 void (*delete_inode) (struct inode *);
209 void (*put_super) (struct super_block *);
210 void (*write_super) (struct super_block *);
211 int (*sync_fs)(struct super_block *sb, int wait);
212 void (*write_super_lockfs) (struct super_block *);
213 void (*unlockfs) (struct super_block *);
214 int (*statfs) (struct super_block *, struct kstatfs *);
215 int (*remount_fs) (struct super_block *, int *, char *);
216 void (*clear_inode) (struct inode *);
217 void (*umount_begin) (struct super_block *);
218
219 void (*sync_inodes) (struct super_block *sb,
220 struct writeback_control *wbc);
221 int (*show_options)(struct seq_file *, struct vfsmount *);
222
223 ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t);
224 ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700225};
226
227All methods are called without any locks being held, unless otherwise
228noted. This means that most methods can block safely. All methods are
229only called from a process context (i.e. not from an interrupt handler
230or bottom half).
231
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700232 alloc_inode: this method is called by inode_alloc() to allocate memory
233 for struct inode and initialize it.
234
235 destroy_inode: this method is called by destroy_inode() to release
236 resources allocated for struct inode.
237
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238 read_inode: this method is called to read a specific inode from the
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700239 mounted filesystem. The i_ino member in the struct inode is
240 initialized by the VFS to indicate which inode to read. Other
241 members are filled in by this method.
242
243 You can set this to NULL and use iget5_locked() instead of iget()
244 to read inodes. This is necessary for filesystems for which the
245 inode number is not sufficient to identify an inode.
246
247 dirty_inode: this method is called by the VFS to mark an inode dirty.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700248
249 write_inode: this method is called when the VFS needs to write an
250 inode to disc. The second parameter indicates whether the write
251 should be synchronous or not, not all filesystems check this flag.
252
253 put_inode: called when the VFS inode is removed from the inode
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700254 cache.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
256 drop_inode: called when the last access to the inode is dropped,
257 with the inode_lock spinlock held.
258
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700259 This method should be either NULL (normal UNIX filesystem
Linus Torvalds1da177e2005-04-16 15:20:36 -0700260 semantics) or "generic_delete_inode" (for filesystems that do not
261 want to cache inodes - causing "delete_inode" to always be
262 called regardless of the value of i_nlink)
263
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700264 The "generic_delete_inode()" behavior is equivalent to the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700265 old practice of using "force_delete" in the put_inode() case,
266 but does not have the races that the "force_delete()" approach
267 had.
268
269 delete_inode: called when the VFS wants to delete an inode
270
Linus Torvalds1da177e2005-04-16 15:20:36 -0700271 put_super: called when the VFS wishes to free the superblock
272 (i.e. unmount). This is called with the superblock lock held
273
274 write_super: called when the VFS superblock needs to be written to
275 disc. This method is optional
276
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700277 sync_fs: called when VFS is writing out all dirty data associated with
278 a superblock. The second parameter indicates whether the method
279 should wait until the write out has been completed. Optional.
280
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800281 write_super_lockfs: called when VFS is locking a filesystem and
282 forcing it into a consistent state. This method is currently
283 used by the Logical Volume Manager (LVM).
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700284
285 unlockfs: called when VFS is unlocking a filesystem and making it writable
286 again.
287
Linus Torvalds1da177e2005-04-16 15:20:36 -0700288 statfs: called when the VFS needs to get filesystem statistics. This
289 is called with the kernel lock held
290
291 remount_fs: called when the filesystem is remounted. This is called
292 with the kernel lock held
293
294 clear_inode: called then the VFS clears the inode. Optional
295
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700296 umount_begin: called when the VFS is unmounting a filesystem.
297
298 sync_inodes: called when the VFS is writing out dirty data associated with
299 a superblock.
300
301 show_options: called by the VFS to show mount options for /proc/<pid>/mounts.
302
303 quota_read: called by the VFS to read from filesystem quota file.
304
305 quota_write: called by the VFS to write to filesystem quota file.
306
Linus Torvalds1da177e2005-04-16 15:20:36 -0700307The read_inode() method is responsible for filling in the "i_op"
308field. This is a pointer to a "struct inode_operations" which
309describes the methods that can be performed on individual inodes.
310
311
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800312The Inode Object
313================
314
315An inode object represents an object within the filesystem.
316
317
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700318struct inode_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800319-----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700320
321This describes how the VFS can manipulate an inode in your
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700322filesystem. As of kernel 2.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700323
324struct inode_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700325 int (*create) (struct inode *,struct dentry *,int, struct nameidata *);
326 struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700327 int (*link) (struct dentry *,struct inode *,struct dentry *);
328 int (*unlink) (struct inode *,struct dentry *);
329 int (*symlink) (struct inode *,struct dentry *,const char *);
330 int (*mkdir) (struct inode *,struct dentry *,int);
331 int (*rmdir) (struct inode *,struct dentry *);
332 int (*mknod) (struct inode *,struct dentry *,int,dev_t);
333 int (*rename) (struct inode *, struct dentry *,
334 struct inode *, struct dentry *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700335 int (*readlink) (struct dentry *, char __user *,int);
336 void * (*follow_link) (struct dentry *, struct nameidata *);
337 void (*put_link) (struct dentry *, struct nameidata *, void *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700338 void (*truncate) (struct inode *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700339 int (*permission) (struct inode *, int, struct nameidata *);
340 int (*setattr) (struct dentry *, struct iattr *);
341 int (*getattr) (struct vfsmount *mnt, struct dentry *, struct kstat *);
342 int (*setxattr) (struct dentry *, const char *,const void *,size_t,int);
343 ssize_t (*getxattr) (struct dentry *, const char *, void *, size_t);
344 ssize_t (*listxattr) (struct dentry *, char *, size_t);
345 int (*removexattr) (struct dentry *, const char *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700346};
347
348Again, all methods are called without any locks being held, unless
349otherwise noted.
350
Linus Torvalds1da177e2005-04-16 15:20:36 -0700351 create: called by the open(2) and creat(2) system calls. Only
352 required if you want to support regular files. The dentry you
353 get should not have an inode (i.e. it should be a negative
354 dentry). Here you will probably call d_instantiate() with the
355 dentry and the newly created inode
356
357 lookup: called when the VFS needs to look up an inode in a parent
358 directory. The name to look for is found in the dentry. This
359 method must call d_add() to insert the found inode into the
360 dentry. The "i_count" field in the inode structure should be
361 incremented. If the named inode does not exist a NULL inode
362 should be inserted into the dentry (this is called a negative
363 dentry). Returning an error code from this routine must only
364 be done on a real error, otherwise creating inodes with system
365 calls like create(2), mknod(2), mkdir(2) and so on will fail.
366 If you wish to overload the dentry methods then you should
367 initialise the "d_dop" field in the dentry; this is a pointer
368 to a struct "dentry_operations".
369 This method is called with the directory inode semaphore held
370
371 link: called by the link(2) system call. Only required if you want
372 to support hard links. You will probably need to call
373 d_instantiate() just as you would in the create() method
374
375 unlink: called by the unlink(2) system call. Only required if you
376 want to support deleting inodes
377
378 symlink: called by the symlink(2) system call. Only required if you
379 want to support symlinks. You will probably need to call
380 d_instantiate() just as you would in the create() method
381
382 mkdir: called by the mkdir(2) system call. Only required if you want
383 to support creating subdirectories. You will probably need to
384 call d_instantiate() just as you would in the create() method
385
386 rmdir: called by the rmdir(2) system call. Only required if you want
387 to support deleting subdirectories
388
389 mknod: called by the mknod(2) system call to create a device (char,
390 block) inode or a named pipe (FIFO) or socket. Only required
391 if you want to support creating these types of inodes. You
392 will probably need to call d_instantiate() just as you would
393 in the create() method
394
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800395 rename: called by the rename(2) system call to rename the object to
396 have the parent and name given by the second inode and dentry.
397
Linus Torvalds1da177e2005-04-16 15:20:36 -0700398 readlink: called by the readlink(2) system call. Only required if
399 you want to support reading symbolic links
400
401 follow_link: called by the VFS to follow a symbolic link to the
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700402 inode it points to. Only required if you want to support
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800403 symbolic links. This method returns a void pointer cookie
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700404 that is passed to put_link().
405
406 put_link: called by the VFS to release resources allocated by
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800407 follow_link(). The cookie returned by follow_link() is passed
408 to to this method as the last parameter. It is used by
409 filesystems such as NFS where page cache is not stable
410 (i.e. page that was installed when the symbolic link walk
411 started might not be in the page cache at the end of the
412 walk).
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700413
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800414 truncate: called by the VFS to change the size of a file. The
415 i_size field of the inode is set to the desired size by the
416 VFS before this method is called. This method is called by
417 the truncate(2) system call and related functionality.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700418
419 permission: called by the VFS to check for access rights on a POSIX-like
420 filesystem.
421
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800422 setattr: called by the VFS to set attributes for a file. This method
423 is called by chmod(2) and related system calls.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700424
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800425 getattr: called by the VFS to get attributes of a file. This method
426 is called by stat(2) and related system calls.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700427
428 setxattr: called by the VFS to set an extended attribute for a file.
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800429 Extended attribute is a name:value pair associated with an
430 inode. This method is called by setxattr(2) system call.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700431
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800432 getxattr: called by the VFS to retrieve the value of an extended
433 attribute name. This method is called by getxattr(2) function
434 call.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700435
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800436 listxattr: called by the VFS to list all extended attributes for a
437 given file. This method is called by listxattr(2) system call.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700438
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800439 removexattr: called by the VFS to remove an extended attribute from
440 a file. This method is called by removexattr(2) system call.
441
442
443The Address Space Object
444========================
445
446The address space object is used to identify pages in the page cache.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700447
448
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700449struct address_space_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800450-------------------------------
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700451
452This describes how the VFS can manipulate mapping of a file to page cache in
453your filesystem. As of kernel 2.6.13, the following members are defined:
454
455struct address_space_operations {
456 int (*writepage)(struct page *page, struct writeback_control *wbc);
457 int (*readpage)(struct file *, struct page *);
458 int (*sync_page)(struct page *);
459 int (*writepages)(struct address_space *, struct writeback_control *);
460 int (*set_page_dirty)(struct page *page);
461 int (*readpages)(struct file *filp, struct address_space *mapping,
462 struct list_head *pages, unsigned nr_pages);
463 int (*prepare_write)(struct file *, struct page *, unsigned, unsigned);
464 int (*commit_write)(struct file *, struct page *, unsigned, unsigned);
465 sector_t (*bmap)(struct address_space *, sector_t);
466 int (*invalidatepage) (struct page *, unsigned long);
467 int (*releasepage) (struct page *, int);
468 ssize_t (*direct_IO)(int, struct kiocb *, const struct iovec *iov,
469 loff_t offset, unsigned long nr_segs);
470 struct page* (*get_xip_page)(struct address_space *, sector_t,
471 int);
472};
473
474 writepage: called by the VM write a dirty page to backing store.
475
476 readpage: called by the VM to read a page from backing store.
477
478 sync_page: called by the VM to notify the backing store to perform all
479 queued I/O operations for a page. I/O operations for other pages
480 associated with this address_space object may also be performed.
481
482 writepages: called by the VM to write out pages associated with the
483 address_space object.
484
485 set_page_dirty: called by the VM to set a page dirty.
486
487 readpages: called by the VM to read pages associated with the address_space
488 object.
489
490 prepare_write: called by the generic write path in VM to set up a write
491 request for a page.
492
493 commit_write: called by the generic write path in VM to write page to
494 its backing store.
495
496 bmap: called by the VFS to map a logical block offset within object to
497 physical block number. This method is use by for the legacy FIBMAP
498 ioctl. Other uses are discouraged.
499
500 invalidatepage: called by the VM on truncate to disassociate a page from its
501 address_space mapping.
502
503 releasepage: called by the VFS to release filesystem specific metadata from
504 a page.
505
506 direct_IO: called by the VM for direct I/O writes and reads.
507
508 get_xip_page: called by the VM to translate a block number to a page.
509 The page is valid until the corresponding filesystem is unmounted.
510 Filesystems that want to use execute-in-place (XIP) need to implement
511 it. An example implementation can be found in fs/ext2/xip.c.
512
513
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800514The File Object
515===============
516
517A file object represents a file opened by a process.
518
519
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700520struct file_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800521----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700522
523This describes how the VFS can manipulate an open file. As of kernel
Pekka J Enberg5ea626a2005-09-09 13:10:19 -07005242.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700525
526struct file_operations {
527 loff_t (*llseek) (struct file *, loff_t, int);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700528 ssize_t (*read) (struct file *, char __user *, size_t, loff_t *);
529 ssize_t (*aio_read) (struct kiocb *, char __user *, size_t, loff_t);
530 ssize_t (*write) (struct file *, const char __user *, size_t, loff_t *);
531 ssize_t (*aio_write) (struct kiocb *, const char __user *, size_t, loff_t);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700532 int (*readdir) (struct file *, void *, filldir_t);
533 unsigned int (*poll) (struct file *, struct poll_table_struct *);
534 int (*ioctl) (struct inode *, struct file *, unsigned int, unsigned long);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700535 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
536 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700537 int (*mmap) (struct file *, struct vm_area_struct *);
538 int (*open) (struct inode *, struct file *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700539 int (*flush) (struct file *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700540 int (*release) (struct inode *, struct file *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700541 int (*fsync) (struct file *, struct dentry *, int datasync);
542 int (*aio_fsync) (struct kiocb *, int datasync);
543 int (*fasync) (int, struct file *, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700544 int (*lock) (struct file *, int, struct file_lock *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700545 ssize_t (*readv) (struct file *, const struct iovec *, unsigned long, loff_t *);
546 ssize_t (*writev) (struct file *, const struct iovec *, unsigned long, loff_t *);
547 ssize_t (*sendfile) (struct file *, loff_t *, size_t, read_actor_t, void *);
548 ssize_t (*sendpage) (struct file *, struct page *, int, size_t, loff_t *, int);
549 unsigned long (*get_unmapped_area)(struct file *, unsigned long, unsigned long, unsigned long, unsigned long);
550 int (*check_flags)(int);
551 int (*dir_notify)(struct file *filp, unsigned long arg);
552 int (*flock) (struct file *, int, struct file_lock *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700553};
554
555Again, all methods are called without any locks being held, unless
556otherwise noted.
557
558 llseek: called when the VFS needs to move the file position index
559
560 read: called by read(2) and related system calls
561
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700562 aio_read: called by io_submit(2) and other asynchronous I/O operations
563
Linus Torvalds1da177e2005-04-16 15:20:36 -0700564 write: called by write(2) and related system calls
565
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700566 aio_write: called by io_submit(2) and other asynchronous I/O operations
567
Linus Torvalds1da177e2005-04-16 15:20:36 -0700568 readdir: called when the VFS needs to read the directory contents
569
570 poll: called by the VFS when a process wants to check if there is
571 activity on this file and (optionally) go to sleep until there
572 is activity. Called by the select(2) and poll(2) system calls
573
574 ioctl: called by the ioctl(2) system call
575
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700576 unlocked_ioctl: called by the ioctl(2) system call. Filesystems that do not
577 require the BKL should use this method instead of the ioctl() above.
578
579 compat_ioctl: called by the ioctl(2) system call when 32 bit system calls
580 are used on 64 bit kernels.
581
Linus Torvalds1da177e2005-04-16 15:20:36 -0700582 mmap: called by the mmap(2) system call
583
584 open: called by the VFS when an inode should be opened. When the VFS
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700585 opens a file, it creates a new "struct file". It then calls the
586 open method for the newly allocated file structure. You might
587 think that the open method really belongs in
588 "struct inode_operations", and you may be right. I think it's
589 done the way it is because it makes filesystems simpler to
590 implement. The open() method is a good place to initialize the
591 "private_data" member in the file structure if you want to point
592 to a device structure
593
594 flush: called by the close(2) system call to flush a file
Linus Torvalds1da177e2005-04-16 15:20:36 -0700595
596 release: called when the last reference to an open file is closed
597
598 fsync: called by the fsync(2) system call
599
600 fasync: called by the fcntl(2) system call when asynchronous
601 (non-blocking) mode is enabled for a file
602
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700603 lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW
604 commands
605
606 readv: called by the readv(2) system call
607
608 writev: called by the writev(2) system call
609
610 sendfile: called by the sendfile(2) system call
611
612 get_unmapped_area: called by the mmap(2) system call
613
614 check_flags: called by the fcntl(2) system call for F_SETFL command
615
616 dir_notify: called by the fcntl(2) system call for F_NOTIFY command
617
618 flock: called by the flock(2) system call
619
Linus Torvalds1da177e2005-04-16 15:20:36 -0700620Note that the file operations are implemented by the specific
621filesystem in which the inode resides. When opening a device node
622(character or block special) most filesystems will call special
623support routines in the VFS which will locate the required device
624driver information. These support routines replace the filesystem file
625operations with those for the device driver, and then proceed to call
626the new open() method for the file. This is how opening a device file
627in the filesystem eventually ends up calling the device driver open()
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700628method.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700629
630
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700631Directory Entry Cache (dcache)
632==============================
633
Linus Torvalds1da177e2005-04-16 15:20:36 -0700634
635struct dentry_operations
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700636------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700637
638This describes how a filesystem can overload the standard dentry
639operations. Dentries and the dcache are the domain of the VFS and the
640individual filesystem implementations. Device drivers have no business
641here. These methods may be set to NULL, as they are either optional or
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700642the VFS uses a default. As of kernel 2.6.13, the following members are
Linus Torvalds1da177e2005-04-16 15:20:36 -0700643defined:
644
645struct dentry_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700646 int (*d_revalidate)(struct dentry *, struct nameidata *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700647 int (*d_hash) (struct dentry *, struct qstr *);
648 int (*d_compare) (struct dentry *, struct qstr *, struct qstr *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700649 int (*d_delete)(struct dentry *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700650 void (*d_release)(struct dentry *);
651 void (*d_iput)(struct dentry *, struct inode *);
652};
653
654 d_revalidate: called when the VFS needs to revalidate a dentry. This
655 is called whenever a name look-up finds a dentry in the
656 dcache. Most filesystems leave this as NULL, because all their
657 dentries in the dcache are valid
658
659 d_hash: called when the VFS adds a dentry to the hash table
660
661 d_compare: called when a dentry should be compared with another
662
663 d_delete: called when the last reference to a dentry is
664 deleted. This means no-one is using the dentry, however it is
665 still valid and in the dcache
666
667 d_release: called when a dentry is really deallocated
668
669 d_iput: called when a dentry loses its inode (just prior to its
670 being deallocated). The default when this is NULL is that the
671 VFS calls iput(). If you define this method, you must call
672 iput() yourself
673
674Each dentry has a pointer to its parent dentry, as well as a hash list
675of child dentries. Child dentries are basically like files in a
676directory.
677
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700678
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800679Directory Entry Cache API
Linus Torvalds1da177e2005-04-16 15:20:36 -0700680--------------------------
681
682There are a number of functions defined which permit a filesystem to
683manipulate dentries:
684
685 dget: open a new handle for an existing dentry (this just increments
686 the usage count)
687
688 dput: close a handle for a dentry (decrements the usage count). If
689 the usage count drops to 0, the "d_delete" method is called
690 and the dentry is placed on the unused list if the dentry is
691 still in its parents hash list. Putting the dentry on the
692 unused list just means that if the system needs some RAM, it
693 goes through the unused list of dentries and deallocates them.
694 If the dentry has already been unhashed and the usage count
695 drops to 0, in this case the dentry is deallocated after the
696 "d_delete" method is called
697
698 d_drop: this unhashes a dentry from its parents hash list. A
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700699 subsequent call to dput() will deallocate the dentry if its
Linus Torvalds1da177e2005-04-16 15:20:36 -0700700 usage count drops to 0
701
702 d_delete: delete a dentry. If there are no other open references to
703 the dentry then the dentry is turned into a negative dentry
704 (the d_iput() method is called). If there are other
705 references, then d_drop() is called instead
706
707 d_add: add a dentry to its parents hash list and then calls
708 d_instantiate()
709
710 d_instantiate: add a dentry to the alias hash list for the inode and
711 updates the "d_inode" member. The "i_count" member in the
712 inode structure should be set/incremented. If the inode
713 pointer is NULL, the dentry is called a "negative
714 dentry". This function is commonly called when an inode is
715 created for an existing negative dentry
716
717 d_lookup: look up a dentry given its parent and path name component
718 It looks up the child of that given name from the dcache
719 hash table. If it is found, the reference count is incremented
720 and the dentry is returned. The caller must use d_put()
721 to free the dentry when it finishes using it.
722
Pekka Enbergcbf8f0f2005-11-07 01:01:09 -0800723For further information on dentry locking, please refer to the document
724Documentation/filesystems/dentry-locking.txt.
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800725
726
727Resources
728=========
729
730(Note some of these resources are not up-to-date with the latest kernel
731 version.)
732
733Creating Linux virtual filesystems. 2002
734 <http://lwn.net/Articles/13325/>
735
736The Linux Virtual File-system Layer by Neil Brown. 1999
737 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
738
739A tour of the Linux VFS by Michael K. Johnson. 1996
740 <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
741
742A small trail through the Linux kernel by Andries Brouwer. 2001
743 <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>