Documentation/filesystems/vfs.txt: typo fix
[linux-3.10.git] / Documentation / filesystems / vfs.txt
1
2               Overview of the Linux Virtual File System
3
4         Original author: Richard Gooch <rgooch@atnf.csiro.au>
5
6                   Last updated on October 28, 2005
7
8   Copyright (C) 1999 Richard Gooch
9   Copyright (C) 2005 Pekka Enberg
10
11   This file is released under the GPLv2.
12
13
14 Introduction
15 ============
16
17 The Virtual File System (also known as the Virtual Filesystem Switch)
18 is the software layer in the kernel that provides the filesystem
19 interface to userspace programs. It also provides an abstraction
20 within the kernel which allows different filesystem implementations to
21 coexist.
22
23 VFS system calls open(2), stat(2), read(2), write(2), chmod(2) and so
24 on are called from a process context. Filesystem locking is described
25 in the document Documentation/filesystems/Locking.
26
27
28 Directory Entry Cache (dcache)
29 ------------------------------
30
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 ---------------
69
70 Opening a file requires another operation: allocation of a file
71 structure (this is the kernel-side implementation of file
72 descriptors). The freshly allocated file structure is initialized with
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
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.
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
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.
84
85
86 Registering and Mounting a Filesystem
87 =====================================
88
89 To register and unregister a filesystem, use the following API
90 functions:
91
92    #include <linux/fs.h>
93
94    extern int register_filesystem(struct file_system_type *);
95    extern int unregister_filesystem(struct file_system_type *);
96
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.
102
103 You can see all filesystems that are registered to the kernel in the
104 file /proc/filesystems.
105
106
107 struct file_system_type
108 -----------------------
109
110 This describes the filesystem. As of kernel 2.6.13, the following
111 members are defined:
112
113 struct file_system_type {
114         const char *name;
115         int fs_flags;
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;
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
129   get_sb: the method to call when a new instance of this
130         filesystem should be mounted
131
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.
137
138   next: for internal VFS use: you should initialize this to NULL
139
140 The get_sb() method has the following arguments:
141
142   struct super_block *sb: the superblock structure. This is partially
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.
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
155 The get_sb() method must determine if the block device specified
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
161 get_sb() method fills in is the "s_op" field. This is a pointer to
162 a "struct super_operations" which describes the next level of the
163 filesystem implementation.
164
165 Usually, a filesystem uses one of the generic get_sb() implementations
166 and provides a fill_super() method instead. The generic methods are:
167
168   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
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
186 The Superblock Object
187 =====================
188
189 A superblock object represents a mounted filesystem.
190
191
192 struct super_operations
193 -----------------------
194
195 This describes how the VFS can manipulate the superblock of your
196 filesystem. As of kernel 2.6.13, the following members are defined:
197
198 struct super_operations {
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);
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
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
238   read_inode: this method is called to read a specific inode from the
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.
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
254         cache.
255
256   drop_inode: called when the last access to the inode is dropped,
257         with the inode_lock spinlock held.
258
259         This method should be either NULL (normal UNIX filesystem
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
264         The "generic_delete_inode()" behavior is equivalent to the
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
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
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
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).
284
285   unlockfs: called when VFS is unlocking a filesystem and making it writable
286         again.
287
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
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
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
312 The Inode Object
313 ================
314
315 An inode object represents an object within the filesystem.
316
317
318 struct inode_operations
319 -----------------------
320
321 This describes how the VFS can manipulate an inode in your
322 filesystem. As of kernel 2.6.13, the following members are defined:
323
324 struct inode_operations {
325         int (*create) (struct inode *,struct dentry *,int, struct nameidata *);
326         struct dentry * (*lookup) (struct inode *,struct dentry *, struct nameidata *);
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 *);
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 *);
338         void (*truncate) (struct inode *);
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 *);
346 };
347
348 Again, all methods are called without any locks being held, unless
349 otherwise noted.
350
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
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
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
402         inode it points to.  Only required if you want to support
403         symbolic links.  This method returns a void pointer cookie
404         that is passed to put_link().
405
406   put_link: called by the VFS to release resources allocated by
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.
418
419   permission: called by the VFS to check for access rights on a POSIX-like
420         filesystem.
421
422   setattr: called by the VFS to set attributes for a file. This method
423         is called by chmod(2) and related system calls.
424
425   getattr: called by the VFS to get attributes of a file. This method
426         is called by stat(2) and related system calls.
427
428   setxattr: called by the VFS to set an extended attribute for a file.
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.
438
439   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
443 The Address Space Object
444 ========================
445
446 The address space object is used to identify pages in the page cache.
447
448
449 struct address_space_operations
450 -------------------------------
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.
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
514 The File Object
515 ===============
516
517 A file object represents a file opened by a process.
518
519
520 struct file_operations
521 ----------------------
522
523 This describes how the VFS can manipulate an open file. As of kernel
524 2.6.13, the following members are defined:
525
526 struct file_operations {
527         loff_t (*llseek) (struct file *, loff_t, int);
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);
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);
535         long (*unlocked_ioctl) (struct file *, unsigned int, unsigned long);
536         long (*compat_ioctl) (struct file *, unsigned int, unsigned long);
537         int (*mmap) (struct file *, struct vm_area_struct *);
538         int (*open) (struct inode *, struct file *);
539         int (*flush) (struct file *);
540         int (*release) (struct inode *, struct file *);
541         int (*fsync) (struct file *, struct dentry *, int datasync);
542         int (*aio_fsync) (struct kiocb *, int datasync);
543         int (*fasync) (int, struct file *, int);
544         int (*lock) (struct file *, int, struct file_lock *);
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 *);
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
562   aio_read: called by io_submit(2) and other asynchronous I/O operations
563
564   write: called by write(2) and related system calls
565
566   aio_write: called by io_submit(2) and other asynchronous I/O operations
567
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
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
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
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
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
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
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()
628 method.
629
630
631 Directory Entry Cache (dcache)
632 ==============================
633
634
635 struct dentry_operations
636 ------------------------
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
642 the VFS uses a default. As of kernel 2.6.13, the following members are
643 defined:
644
645 struct dentry_operations {
646         int (*d_revalidate)(struct dentry *, struct nameidata *);
647         int (*d_hash) (struct dentry *, struct qstr *);
648         int (*d_compare) (struct dentry *, struct qstr *, struct qstr *);
649         int (*d_delete)(struct dentry *);
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
678
679 Directory Entry Cache API
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
699         subsequent call to dput() will deallocate the dentry if its
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
723 For further information on dentry locking, please refer to the document
724 Documentation/filesystems/dentry-locking.txt.
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>