blob: ee4c0a8b8db7a663169fd97c57ce472a1a790398 [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
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700165Usually, a filesystem uses generic one of the generic get_sb()
166implementations and provides a fill_super() method instead. The
167generic methods are:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700168
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700169 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
176A 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 Enbergcc7d1f82005-11-07 01:01:08 -0800187The Superblock Object
188=====================
189
190A superblock object represents a mounted filesystem.
191
192
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700193struct super_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800194-----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700195
196This describes how the VFS can manipulate the superblock of your
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700197filesystem. As of kernel 2.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700198
199struct super_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700200 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 Torvalds1da177e2005-04-16 15:20:36 -0700226};
227
228All methods are called without any locks being held, unless otherwise
229noted. This means that most methods can block safely. All methods are
230only called from a process context (i.e. not from an interrupt handler
231or bottom half).
232
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700233 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 Torvalds1da177e2005-04-16 15:20:36 -0700239 read_inode: this method is called to read a specific inode from the
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700240 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 Torvalds1da177e2005-04-16 15:20:36 -0700249
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 Enberg5ea626a2005-09-09 13:10:19 -0700255 cache.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700256
257 drop_inode: called when the last access to the inode is dropped,
258 with the inode_lock spinlock held.
259
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700260 This method should be either NULL (normal UNIX filesystem
Linus Torvalds1da177e2005-04-16 15:20:36 -0700261 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 Enberg5ea626a2005-09-09 13:10:19 -0700265 The "generic_delete_inode()" behavior is equivalent to the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700266 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 Torvalds1da177e2005-04-16 15:20:36 -0700272 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 Enberg5ea626a2005-09-09 13:10:19 -0700278 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 Enbergcc7d1f82005-11-07 01:01:08 -0800282 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 Enberg5ea626a2005-09-09 13:10:19 -0700285
286 unlockfs: called when VFS is unlocking a filesystem and making it writable
287 again.
288
Linus Torvalds1da177e2005-04-16 15:20:36 -0700289 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 Enberg5ea626a2005-09-09 13:10:19 -0700297 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 Torvalds1da177e2005-04-16 15:20:36 -0700308The read_inode() method is responsible for filling in the "i_op"
309field. This is a pointer to a "struct inode_operations" which
310describes the methods that can be performed on individual inodes.
311
312
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800313The Inode Object
314================
315
316An inode object represents an object within the filesystem.
317
318
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700319struct inode_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800320-----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700321
322This describes how the VFS can manipulate an inode in your
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700323filesystem. As of kernel 2.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700324
325struct inode_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700326 int (*create) (struct inode *,struct dentry *,int, struct nameidata *);
327 struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700328 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 Enberg5ea626a2005-09-09 13:10:19 -0700336 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 Torvalds1da177e2005-04-16 15:20:36 -0700339 void (*truncate) (struct inode *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700340 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 Torvalds1da177e2005-04-16 15:20:36 -0700347};
348
349Again, all methods are called without any locks being held, unless
350otherwise noted.
351
Linus Torvalds1da177e2005-04-16 15:20:36 -0700352 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 Enbergcc7d1f82005-11-07 01:01:08 -0800396 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 Torvalds1da177e2005-04-16 15:20:36 -0700399 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 Enberg5ea626a2005-09-09 13:10:19 -0700403 inode it points to. Only required if you want to support
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800404 symbolic links. This method returns a void pointer cookie
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700405 that is passed to put_link().
406
407 put_link: called by the VFS to release resources allocated by
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800408 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 Enberg5ea626a2005-09-09 13:10:19 -0700414
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800415 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 Enberg5ea626a2005-09-09 13:10:19 -0700419
420 permission: called by the VFS to check for access rights on a POSIX-like
421 filesystem.
422
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800423 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 Enberg5ea626a2005-09-09 13:10:19 -0700425
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800426 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 Enberg5ea626a2005-09-09 13:10:19 -0700428
429 setxattr: called by the VFS to set an extended attribute for a file.
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800430 Extended attribute is a name:value pair associated with an
431 inode. This method is called by setxattr(2) system call.
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700432
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800433 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 Enberg5ea626a2005-09-09 13:10:19 -0700436
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800437 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 Enberg5ea626a2005-09-09 13:10:19 -0700439
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800440 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
444The Address Space Object
445========================
446
447The address space object is used to identify pages in the page cache.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700448
449
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700450struct address_space_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800451-------------------------------
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700452
453This describes how the VFS can manipulate mapping of a file to page cache in
454your filesystem. As of kernel 2.6.13, the following members are defined:
455
456struct 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 Enbergcc7d1f82005-11-07 01:01:08 -0800515The File Object
516===============
517
518A file object represents a file opened by a process.
519
520
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700521struct file_operations
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800522----------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700523
524This describes how the VFS can manipulate an open file. As of kernel
Pekka J Enberg5ea626a2005-09-09 13:10:19 -07005252.6.13, the following members are defined:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700526
527struct file_operations {
528 loff_t (*llseek) (struct file *, loff_t, int);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700529 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 Torvalds1da177e2005-04-16 15:20:36 -0700533 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 Enberg5ea626a2005-09-09 13:10:19 -0700536 long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
537 long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700538 int (*mmap) (struct file *, struct vm_area_struct *);
539 int (*open) (struct inode *, struct file *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700540 int (*flush) (struct file *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700541 int (*release) (struct inode *, struct file *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700542 int (*fsync) (struct file *, struct dentry *, int datasync);
543 int (*aio_fsync) (struct kiocb *, int datasync);
544 int (*fasync) (int, struct file *, int);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700545 int (*lock) (struct file *, int, struct file_lock *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700546 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 Torvalds1da177e2005-04-16 15:20:36 -0700554};
555
556Again, all methods are called without any locks being held, unless
557otherwise 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 Enberg5ea626a2005-09-09 13:10:19 -0700563 aio_read: called by io_submit(2) and other asynchronous I/O operations
564
Linus Torvalds1da177e2005-04-16 15:20:36 -0700565 write: called by write(2) and related system calls
566
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700567 aio_write: called by io_submit(2) and other asynchronous I/O operations
568
Linus Torvalds1da177e2005-04-16 15:20:36 -0700569 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 Enberg5ea626a2005-09-09 13:10:19 -0700577 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 Torvalds1da177e2005-04-16 15:20:36 -0700583 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 Enberg5ea626a2005-09-09 13:10:19 -0700586 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 Torvalds1da177e2005-04-16 15:20:36 -0700596
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 Enberg5ea626a2005-09-09 13:10:19 -0700604 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 Torvalds1da177e2005-04-16 15:20:36 -0700621Note that the file operations are implemented by the specific
622filesystem in which the inode resides. When opening a device node
623(character or block special) most filesystems will call special
624support routines in the VFS which will locate the required device
625driver information. These support routines replace the filesystem file
626operations with those for the device driver, and then proceed to call
627the new open() method for the file. This is how opening a device file
628in the filesystem eventually ends up calling the device driver open()
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700629method.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700630
631
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700632Directory Entry Cache (dcache)
633==============================
634
Linus Torvalds1da177e2005-04-16 15:20:36 -0700635
636struct dentry_operations
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700637------------------------
Linus Torvalds1da177e2005-04-16 15:20:36 -0700638
639This describes how a filesystem can overload the standard dentry
640operations. Dentries and the dcache are the domain of the VFS and the
641individual filesystem implementations. Device drivers have no business
642here. These methods may be set to NULL, as they are either optional or
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700643the VFS uses a default. As of kernel 2.6.13, the following members are
Linus Torvalds1da177e2005-04-16 15:20:36 -0700644defined:
645
646struct dentry_operations {
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700647 int (*d_revalidate)(struct dentry *, struct nameidata *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700648 int (*d_hash) (struct dentry *, struct qstr *);
649 int (*d_compare) (struct dentry *, struct qstr *, struct qstr *);
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700650 int (*d_delete)(struct dentry *);
Linus Torvalds1da177e2005-04-16 15:20:36 -0700651 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
675Each dentry has a pointer to its parent dentry, as well as a hash list
676of child dentries. Child dentries are basically like files in a
677directory.
678
Pekka J Enberg5ea626a2005-09-09 13:10:19 -0700679
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800680Directory Entry Cache API
Linus Torvalds1da177e2005-04-16 15:20:36 -0700681--------------------------
682
683There are a number of functions defined which permit a filesystem to
684manipulate 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 Enberg5ea626a2005-09-09 13:10:19 -0700700 subsequent call to dput() will deallocate the dentry if its
Linus Torvalds1da177e2005-04-16 15:20:36 -0700701 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 Enbergcbf8f0f2005-11-07 01:01:09 -0800724For further information on dentry locking, please refer to the document
725Documentation/filesystems/dentry-locking.txt.
Pekka Enbergcc7d1f82005-11-07 01:01:08 -0800726
727
728Resources
729=========
730
731(Note some of these resources are not up-to-date with the latest kernel
732 version.)
733
734Creating Linux virtual filesystems. 2002
735 <http://lwn.net/Articles/13325/>
736
737The Linux Virtual File-system Layer by Neil Brown. 1999
738 <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html>
739
740A tour of the Linux VFS by Michael K. Johnson. 1996
741 <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html>
742
743A small trail through the Linux kernel by Andries Brouwer. 2001
744 <http://www.win.tue.nl/~aeb/linux/vfs/trail.html>