Commit | Line | Data |
---|---|---|
1da177e4 | 1 | |
5ea626aa | 2 | Overview of the Linux Virtual File System |
1da177e4 | 3 | |
5ea626aa | 4 | Original author: Richard Gooch <rgooch@atnf.csiro.au> |
1da177e4 | 5 | |
cc7d1f8f | 6 | Last updated on October 28, 2005 |
1da177e4 | 7 | |
5ea626aa PE |
8 | Copyright (C) 1999 Richard Gooch |
9 | Copyright (C) 2005 Pekka Enberg | |
1da177e4 | 10 | |
5ea626aa | 11 | This file is released under the GPLv2. |
1da177e4 | 12 | |
1da177e4 | 13 | |
cc7d1f8f PE |
14 | Introduction |
15 | ============ | |
1da177e4 | 16 | |
cc7d1f8f PE |
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. | |
1da177e4 | 22 | |
cc7d1f8f PE |
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. | |
1da177e4 | 26 | |
1da177e4 | 27 | |
cc7d1f8f PE |
28 | Directory Entry Cache (dcache) |
29 | ------------------------------ | |
1da177e4 | 30 | |
cc7d1f8f PE |
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. | |
44 | ||
45 | ||
46 | The Inode Object | |
47 | ---------------- | |
48 | ||
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). | |
56 | ||
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. | |
65 | ||
66 | ||
67 | The File Object | |
68 | --------------- | |
1da177e4 LT |
69 | |
70 | Opening a file requires another operation: allocation of a file | |
71 | structure (this is the kernel-side implementation of file | |
5ea626aa | 72 | descriptors). The freshly allocated file structure is initialized with |
1da177e4 LT |
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 | |
cc7d1f8f PE |
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. | |
1da177e4 LT |
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 | |
cc7d1f8f PE |
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. | |
1da177e4 | 84 | |
5ea626aa PE |
85 | |
86 | Registering and Mounting a Filesystem | |
cc7d1f8f | 87 | ===================================== |
1da177e4 | 88 | |
cc7d1f8f PE |
89 | To register and unregister a filesystem, use the following API |
90 | functions: | |
1da177e4 | 91 | |
cc7d1f8f | 92 | #include <linux/fs.h> |
1da177e4 | 93 | |
cc7d1f8f PE |
94 | extern int register_filesystem(struct file_system_type *); |
95 | extern int unregister_filesystem(struct file_system_type *); | |
1da177e4 | 96 | |
cc7d1f8f PE |
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. | |
1da177e4 | 102 | |
cc7d1f8f PE |
103 | You can see all filesystems that are registered to the kernel in the |
104 | file /proc/filesystems. | |
1da177e4 LT |
105 | |
106 | ||
5ea626aa | 107 | struct file_system_type |
cc7d1f8f | 108 | ----------------------- |
1da177e4 | 109 | |
5ea626aa | 110 | This describes the filesystem. As of kernel 2.6.13, the following |
1da177e4 LT |
111 | members are defined: |
112 | ||
113 | struct file_system_type { | |
114 | const char *name; | |
115 | int fs_flags; | |
5ea626aa PE |
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; | |
1da177e4 LT |
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 | ||
5ea626aa | 129 | get_sb: the method to call when a new instance of this |
1da177e4 LT |
130 | filesystem should be mounted |
131 | ||
5ea626aa PE |
132 | kill_sb: the method to call when an instance of this filesystem |
133 | should be unmounted | |
134 | ||
135 | owner: for internal VFS use: you should initialize this to THIS_MODULE in | |
136 | most cases. | |
1da177e4 | 137 | |
5ea626aa PE |
138 | next: for internal VFS use: you should initialize this to NULL |
139 | ||
140 | The get_sb() method has the following arguments: | |
1da177e4 LT |
141 | |
142 | struct super_block *sb: the superblock structure. This is partially | |
5ea626aa PE |
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. | |
1da177e4 LT |
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 | ||
5ea626aa | 155 | The get_sb() method must determine if the block device specified |
1da177e4 LT |
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 | |
5ea626aa | 161 | get_sb() method fills in is the "s_op" field. This is a pointer to |
1da177e4 LT |
162 | a "struct super_operations" which describes the next level of the |
163 | filesystem implementation. | |
164 | ||
e3e1bfe4 JC |
165 | Usually, a filesystem uses one of the generic get_sb() implementations |
166 | and provides a fill_super() method instead. The generic methods are: | |
5ea626aa PE |
167 | |
168 | get_sb_bdev: mount a filesystem residing on a block device | |
1da177e4 | 169 | |
5ea626aa PE |
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 | ||
175 | A 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 | ||
cc7d1f8f PE |
186 | The Superblock Object |
187 | ===================== | |
188 | ||
189 | A superblock object represents a mounted filesystem. | |
190 | ||
191 | ||
5ea626aa | 192 | struct super_operations |
cc7d1f8f | 193 | ----------------------- |
1da177e4 LT |
194 | |
195 | This describes how the VFS can manipulate the superblock of your | |
5ea626aa | 196 | filesystem. As of kernel 2.6.13, the following members are defined: |
1da177e4 LT |
197 | |
198 | struct super_operations { | |
5ea626aa PE |
199 | 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); | |
1da177e4 LT |
225 | }; |
226 | ||
227 | All methods are called without any locks being held, unless otherwise | |
228 | noted. This means that most methods can block safely. All methods are | |
229 | only called from a process context (i.e. not from an interrupt handler | |
230 | or bottom half). | |
231 | ||
5ea626aa PE |
232 | 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 | ||
1da177e4 | 238 | read_inode: this method is called to read a specific inode from the |
5ea626aa PE |
239 | 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. | |
1da177e4 LT |
248 | |
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 | |
5ea626aa | 254 | cache. |
1da177e4 LT |
255 | |
256 | drop_inode: called when the last access to the inode is dropped, | |
257 | with the inode_lock spinlock held. | |
258 | ||
5ea626aa | 259 | This method should be either NULL (normal UNIX filesystem |
1da177e4 LT |
260 | 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 | ||
5ea626aa | 264 | The "generic_delete_inode()" behavior is equivalent to the |
1da177e4 LT |
265 | 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 | ||
1da177e4 LT |
271 | 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 | ||
5ea626aa PE |
277 | 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 | ||
cc7d1f8f PE |
281 | 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). | |
5ea626aa PE |
284 | |
285 | unlockfs: called when VFS is unlocking a filesystem and making it writable | |
286 | again. | |
287 | ||
1da177e4 LT |
288 | 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 | ||
5ea626aa PE |
296 | 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 | ||
1da177e4 LT |
307 | The read_inode() method is responsible for filling in the "i_op" |
308 | field. This is a pointer to a "struct inode_operations" which | |
309 | describes the methods that can be performed on individual inodes. | |
310 | ||
311 | ||
cc7d1f8f PE |
312 | The Inode Object |
313 | ================ | |
314 | ||
315 | An inode object represents an object within the filesystem. | |
316 | ||
317 | ||
5ea626aa | 318 | struct inode_operations |
cc7d1f8f | 319 | ----------------------- |
1da177e4 LT |
320 | |
321 | This describes how the VFS can manipulate an inode in your | |
5ea626aa | 322 | filesystem. As of kernel 2.6.13, the following members are defined: |
1da177e4 LT |
323 | |
324 | struct inode_operations { | |
5ea626aa PE |
325 | int (*create) (struct inode *,struct dentry *,int, struct nameidata *); |
326 | struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *); | |
1da177e4 LT |
327 | 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 *); | |
5ea626aa PE |
335 | int (*readlink) (struct dentry *, char __user *,int); |
336 | void * (*follow_link) (struct dentry *, struct nameidata *); | |
337 | void (*put_link) (struct dentry *, struct nameidata *, void *); | |
1da177e4 | 338 | void (*truncate) (struct inode *); |
5ea626aa PE |
339 | 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 *); | |
1da177e4 LT |
346 | }; |
347 | ||
348 | Again, all methods are called without any locks being held, unless | |
349 | otherwise noted. | |
350 | ||
1da177e4 LT |
351 | 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 | ||
cc7d1f8f PE |
395 | 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 | ||
1da177e4 LT |
398 | 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 | |
5ea626aa | 402 | inode it points to. Only required if you want to support |
cc7d1f8f | 403 | symbolic links. This method returns a void pointer cookie |
5ea626aa PE |
404 | that is passed to put_link(). |
405 | ||
406 | put_link: called by the VFS to release resources allocated by | |
cc7d1f8f PE |
407 | 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). | |
413 | ||
414 | 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. | |
5ea626aa PE |
418 | |
419 | permission: called by the VFS to check for access rights on a POSIX-like | |
420 | filesystem. | |
421 | ||
cc7d1f8f PE |
422 | setattr: called by the VFS to set attributes for a file. This method |
423 | is called by chmod(2) and related system calls. | |
5ea626aa | 424 | |
cc7d1f8f PE |
425 | getattr: called by the VFS to get attributes of a file. This method |
426 | is called by stat(2) and related system calls. | |
5ea626aa PE |
427 | |
428 | setxattr: called by the VFS to set an extended attribute for a file. | |
cc7d1f8f PE |
429 | Extended attribute is a name:value pair associated with an |
430 | inode. This method is called by setxattr(2) system call. | |
431 | ||
432 | 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. | |
435 | ||
436 | listxattr: called by the VFS to list all extended attributes for a | |
437 | given file. This method is called by listxattr(2) system call. | |
5ea626aa | 438 | |
cc7d1f8f PE |
439 | removexattr: called by the VFS to remove an extended attribute from |
440 | a file. This method is called by removexattr(2) system call. | |
5ea626aa | 441 | |
5ea626aa | 442 | |
cc7d1f8f PE |
443 | The Address Space Object |
444 | ======================== | |
445 | ||
446 | The address space object is used to identify pages in the page cache. | |
5ea626aa PE |
447 | |
448 | ||
449 | struct address_space_operations | |
cc7d1f8f | 450 | ------------------------------- |
5ea626aa PE |
451 | |
452 | This describes how the VFS can manipulate mapping of a file to page cache in | |
453 | your filesystem. As of kernel 2.6.13, the following members are defined: | |
454 | ||
455 | struct 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. | |
1da177e4 | 489 | |
5ea626aa PE |
490 | prepare_write: called by the generic write path in VM to set up a write |
491 | request for a page. | |
1da177e4 | 492 | |
5ea626aa PE |
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 | ||
cc7d1f8f PE |
514 | The File Object |
515 | =============== | |
516 | ||
517 | A file object represents a file opened by a process. | |
518 | ||
519 | ||
5ea626aa | 520 | struct file_operations |
cc7d1f8f | 521 | ---------------------- |
1da177e4 LT |
522 | |
523 | This describes how the VFS can manipulate an open file. As of kernel | |
5ea626aa | 524 | 2.6.13, the following members are defined: |
1da177e4 LT |
525 | |
526 | struct file_operations { | |
527 | loff_t (*llseek) (struct file *, loff_t, int); | |
5ea626aa PE |
528 | 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); | |
1da177e4 LT |
532 | 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); | |
5ea626aa PE |
535 | long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long); |
536 | long (*compat_ioctl) (struct file *, unsigned int, unsigned long); | |
1da177e4 LT |
537 | int (*mmap) (struct file *, struct vm_area_struct *); |
538 | int (*open) (struct inode *, struct file *); | |
5ea626aa | 539 | int (*flush) (struct file *); |
1da177e4 | 540 | int (*release) (struct inode *, struct file *); |
5ea626aa PE |
541 | int (*fsync) (struct file *, struct dentry *, int datasync); |
542 | int (*aio_fsync) (struct kiocb *, int datasync); | |
543 | int (*fasync) (int, struct file *, int); | |
1da177e4 | 544 | int (*lock) (struct file *, int, struct file_lock *); |
5ea626aa PE |
545 | 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 *); | |
1da177e4 LT |
553 | }; |
554 | ||
555 | Again, all methods are called without any locks being held, unless | |
556 | otherwise 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 | ||
5ea626aa PE |
562 | aio_read: called by io_submit(2) and other asynchronous I/O operations |
563 | ||
1da177e4 LT |
564 | write: called by write(2) and related system calls |
565 | ||
5ea626aa PE |
566 | aio_write: called by io_submit(2) and other asynchronous I/O operations |
567 | ||
1da177e4 LT |
568 | 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 | ||
5ea626aa PE |
576 | 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 | ||
1da177e4 LT |
582 | mmap: called by the mmap(2) system call |
583 | ||
584 | open: called by the VFS when an inode should be opened. When the VFS | |
5ea626aa PE |
585 | 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 | |
1da177e4 LT |
595 | |
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 | ||
5ea626aa PE |
603 | 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 | ||
1da177e4 LT |
620 | Note that the file operations are implemented by the specific |
621 | filesystem in which the inode resides. When opening a device node | |
622 | (character or block special) most filesystems will call special | |
623 | support routines in the VFS which will locate the required device | |
624 | driver information. These support routines replace the filesystem file | |
625 | operations with those for the device driver, and then proceed to call | |
626 | the new open() method for the file. This is how opening a device file | |
627 | in the filesystem eventually ends up calling the device driver open() | |
5ea626aa | 628 | method. |
1da177e4 LT |
629 | |
630 | ||
5ea626aa PE |
631 | Directory Entry Cache (dcache) |
632 | ============================== | |
633 | ||
1da177e4 LT |
634 | |
635 | struct dentry_operations | |
5ea626aa | 636 | ------------------------ |
1da177e4 LT |
637 | |
638 | This describes how a filesystem can overload the standard dentry | |
639 | operations. Dentries and the dcache are the domain of the VFS and the | |
640 | individual filesystem implementations. Device drivers have no business | |
641 | here. These methods may be set to NULL, as they are either optional or | |
5ea626aa | 642 | the VFS uses a default. As of kernel 2.6.13, the following members are |
1da177e4 LT |
643 | defined: |
644 | ||
645 | struct dentry_operations { | |
5ea626aa | 646 | int (*d_revalidate)(struct dentry *, struct nameidata *); |
1da177e4 LT |
647 | int (*d_hash) (struct dentry *, struct qstr *); |
648 | int (*d_compare) (struct dentry *, struct qstr *, struct qstr *); | |
5ea626aa | 649 | int (*d_delete)(struct dentry *); |
1da177e4 LT |
650 | 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 | ||
674 | Each dentry has a pointer to its parent dentry, as well as a hash list | |
675 | of child dentries. Child dentries are basically like files in a | |
676 | directory. | |
677 | ||
5ea626aa | 678 | |
cc7d1f8f | 679 | Directory Entry Cache API |
1da177e4 LT |
680 | -------------------------- |
681 | ||
682 | There are a number of functions defined which permit a filesystem to | |
683 | manipulate 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 | |
5ea626aa | 699 | subsequent call to dput() will deallocate the dentry if its |
1da177e4 LT |
700 | 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 | ||
cbf8f0f3 PE |
723 | For further information on dentry locking, please refer to the document |
724 | Documentation/filesystems/dentry-locking.txt. | |
cc7d1f8f PE |
725 | |
726 | ||
727 | Resources | |
728 | ========= | |
729 | ||
730 | (Note some of these resources are not up-to-date with the latest kernel | |
731 | version.) | |
732 | ||
733 | Creating Linux virtual filesystems. 2002 | |
734 | <http://lwn.net/Articles/13325/> | |
735 | ||
736 | The Linux Virtual File-system Layer by Neil Brown. 1999 | |
737 | <http://www.cse.unsw.edu.au/~neilb/oss/linux-commentary/vfs.html> | |
738 | ||
739 | A tour of the Linux VFS by Michael K. Johnson. 1996 | |
740 | <http://www.tldp.org/LDP/khg/HyperNews/get/fs/vfstour.html> | |
741 | ||
742 | A small trail through the Linux kernel by Andries Brouwer. 2001 | |
743 | <http://www.win.tue.nl/~aeb/linux/vfs/trail.html> |