I noticed that vfs.txt looked kinda funky, so I went ahead and reformatted it.
Signed-off-by: Raymond Jennings Cc: Andrew Morton <[email protected]> --- diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 5eb8456..8ddfe06 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -114,12 +114,12 @@ members are defined: struct file_system_type { const char *name; int fs_flags; - struct dentry *(*mount) (struct file_system_type *, int, - const char *, void *); - void (*kill_sb) (struct super_block *); - struct module *owner; - struct file_system_type * next; - struct list_head fs_supers; + struct dentry *(*mount) (struct file_system_type *, int, + const char *, void *); + void (*kill_sb) (struct super_block *); + struct module *owner; + struct file_system_type * next; + struct list_head fs_supers; struct lock_class_key s_lock_key; struct lock_class_key s_umount_key; }; @@ -136,7 +136,7 @@ struct file_system_type { should be shut down owner: for internal VFS use: you should initialize this to THIS_MODULE in - most cases. + most cases. next: for internal VFS use: you should initialize this to NULL @@ -145,7 +145,7 @@ struct file_system_type { The mount() method has the following arguments: struct file_system_type *fs_type: describes the filesystem, partly initialized - by the specific filesystem code + by the specific filesystem code int flags: mount flags @@ -182,12 +182,12 @@ and provides a fill_super() callback instead. The generic variants are: mount_nodev: mount a filesystem that is not backed by a device mount_single: mount a filesystem which shares the instance between - all mounts + all mounts A fill_super() callback implementation has the following arguments: struct super_block *sb: the superblock structure. The callback - must initialize this properly. + must initialize this properly. void *data: arbitrary mount options, usually comes as an ASCII string (see "Mount Options" section) @@ -208,26 +208,26 @@ This describes how the VFS can manipulate the superblock of your filesystem. As of kernel 2.6.22, the following members are defined: struct super_operations { - struct inode *(*alloc_inode)(struct super_block *sb); - void (*destroy_inode)(struct inode *); - - void (*dirty_inode) (struct inode *, int flags); - int (*write_inode) (struct inode *, int); - void (*drop_inode) (struct inode *); - void (*delete_inode) (struct inode *); - void (*put_super) (struct super_block *); - int (*sync_fs)(struct super_block *sb, int wait); - int (*freeze_fs) (struct super_block *); - int (*unfreeze_fs) (struct super_block *); - int (*statfs) (struct dentry *, struct kstatfs *); - int (*remount_fs) (struct super_block *, int *, char *); - void (*clear_inode) (struct inode *); - void (*umount_begin) (struct super_block *); - - int (*show_options)(struct seq_file *, struct dentry *); - - ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); - ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); + struct inode *(*alloc_inode)(struct super_block *sb); + void (*destroy_inode)(struct inode *); + + void (*dirty_inode) (struct inode *, int flags); + int (*write_inode) (struct inode *, int); + void (*drop_inode) (struct inode *); + void (*delete_inode) (struct inode *); + void (*put_super) (struct super_block *); + int (*sync_fs)(struct super_block *sb, int wait); + int (*freeze_fs) (struct super_block *); + int (*unfreeze_fs) (struct super_block *); + int (*statfs) (struct dentry *, struct kstatfs *); + int (*remount_fs) (struct super_block *, int *, char *); + void (*clear_inode) (struct inode *); + void (*umount_begin) (struct super_block *); + + int (*show_options)(struct seq_file *, struct dentry *); + + ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); + ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); int (*nr_cached_objects)(struct super_block *); void (*free_cached_objects)(struct super_block *, int); }; @@ -238,14 +238,14 @@ only called from a process context (i.e. not from an interrupt handler or bottom half). alloc_inode: this method is called by alloc_inode() to allocate memory - for struct inode and initialize it. If this function is not - defined, a simple 'struct inode' is allocated. Normally - alloc_inode will be used to allocate a larger structure which - contains a 'struct inode' embedded within it. + for struct inode and initialize it. If this function is not + defined, a simple 'struct inode' is allocated. Normally + alloc_inode will be used to allocate a larger structure which + contains a 'struct inode' embedded within it. destroy_inode: this method is called by destroy_inode() to release - resources allocated for struct inode. It is only required if - ->alloc_inode was defined and simply undoes anything done by + resources allocated for struct inode. It is only required if + ->alloc_inode was defined and simply undoes anything done by ->alloc_inode. dirty_inode: this method is called by the VFS to mark an inode dirty. @@ -273,15 +273,15 @@ or bottom half). (i.e. unmount). This is called with the superblock lock held sync_fs: called when VFS is writing out all dirty data associated with - a superblock. The second parameter indicates whether the method + a superblock. The second parameter indicates whether the method should wait until the write out has been completed. Optional. freeze_fs: called when VFS is locking a filesystem and - forcing it into a consistent state. This method is currently - used by the Logical Volume Manager (LVM). + forcing it into a consistent state. This method is currently + used by the Logical Volume Manager (LVM). unfreeze_fs: called when VFS is unlocking a filesystem and making it writable - again. + again. statfs: called when the VFS needs to get filesystem statistics. @@ -346,9 +346,9 @@ struct inode_operations { int (*rmdir) (struct inode *,struct dentry *); int (*mknod) (struct inode *,struct dentry *,umode_t,dev_t); int (*rename) (struct inode *, struct dentry *, - struct inode *, struct dentry *); + struct inode *, struct dentry *); int (*rename2) (struct inode *, struct dentry *, - struct inode *, struct dentry *, unsigned int); + struct inode *, struct dentry *, unsigned int); int (*readlink) (struct dentry *, char __user *,int); const char *(*follow_link) (struct dentry *, void **); void (*put_link) (struct inode *, void *); @@ -362,7 +362,7 @@ struct inode_operations { int (*removexattr) (struct dentry *, const char *); void (*update_time)(struct inode *, struct timespec *, int); int (*atomic_open)(struct inode *, struct dentry *, struct file *, - unsigned open_flag, umode_t create_mode, int *opened); + unsigned open_flag, umode_t create_mode, int *opened); int (*tmpfile) (struct inode *, struct dentry *, umode_t); int (*dentry_open)(struct dentry *, struct file *, const struct cred *); }; @@ -450,7 +450,7 @@ otherwise noted. cookie isn't NULL. permission: called by the VFS to check for access rights on a POSIX-like - filesystem. + filesystem. May be called in rcu-walk mode (mask & MAY_NOT_BLOCK). If in rcu-walk mode, the filesystem must check the permission without blocking or @@ -460,33 +460,33 @@ otherwise noted. -ECHILD and it will be called again in ref-walk mode. setattr: called by the VFS to set attributes for a file. This method - is called by chmod(2) and related system calls. + is called by chmod(2) and related system calls. getattr: called by the VFS to get attributes of a file. This method - is called by stat(2) and related system calls. + is called by stat(2) and related system calls. setxattr: called by the VFS to set an extended attribute for a file. - Extended attribute is a name:value pair associated with an - inode. This method is called by setxattr(2) system call. + Extended attribute is a name:value pair associated with an + inode. This method is called by setxattr(2) system call. getxattr: called by the VFS to retrieve the value of an extended - attribute name. This method is called by getxattr(2) function - call. + attribute name. This method is called by getxattr(2) function + call. listxattr: called by the VFS to list all extended attributes for a - given file. This method is called by listxattr(2) system call. + given file. This method is called by listxattr(2) system call. removexattr: called by the VFS to remove an extended attribute from - a file. This method is called by removexattr(2) system call. + a file. This method is called by removexattr(2) system call. update_time: called by the VFS to update a specific time or the i_version of - an inode. If this is not defined the VFS will update the inode itself - and call mark_inode_dirty_sync. + an inode. If this is not defined the VFS will update the inode itself + and call mark_inode_dirty_sync. atomic_open: called on the last component of an open. Using this optional - method the filesystem can look up, possibly create and open the file in - one atomic operation. If it cannot perform this (e.g. the file type - turned out to be wrong) it may signal this by returning 1 instead of + method the filesystem can look up, possibly create and open the file in + one atomic operation. If it cannot perform this (e.g. the file type + turned out to be wrong) it may signal this by returning 1 instead of usual 0 or -ve . This method is only called if the last component is negative or needs lookup. Cached positive dentries are still handled by f_op->open(). If the file was created, the FILE_CREATED flag should be @@ -581,13 +581,13 @@ struct address_space_operations { int (*writepages)(struct address_space *, struct writeback_control *); int (*set_page_dirty)(struct page *page); int (*readpages)(struct file *filp, struct address_space *mapping, - struct list_head *pages, unsigned nr_pages); + struct list_head *pages, unsigned nr_pages); int (*write_begin)(struct file *, struct address_space *mapping, - loff_t pos, unsigned len, unsigned flags, - struct page **pagep, void **fsdata); + loff_t pos, unsigned len, unsigned flags, + struct page **pagep, void **fsdata); int (*write_end)(struct file *, struct address_space *mapping, - loff_t pos, unsigned len, unsigned copied, - struct page *page, void *fsdata); + loff_t pos, unsigned len, unsigned copied, + struct page *page, void *fsdata); sector_t (*bmap)(struct address_space *, sector_t); void (*invalidatepage) (struct page *, unsigned int, unsigned int); int (*releasepage) (struct page *, int); @@ -597,7 +597,7 @@ struct address_space_operations { int (*migratepage) (struct page *, struct page *); int (*launder_page) (struct page *); int (*is_partially_uptodate) (struct page *, unsigned long, - unsigned long); + unsigned long); void (*is_dirty_writeback) (struct page *, bool *, bool *); int (*error_remove_page) (struct mapping *mapping, struct page *page); int (*swap_activate)(struct file *); @@ -605,54 +605,54 @@ struct address_space_operations { }; writepage: called by the VM to write a dirty page to backing store. - This may happen for data integrity reasons (i.e. 'sync'), or - to free up memory (flush). The difference can be seen in - wbc->sync_mode. - The PG_Dirty flag has been cleared and PageLocked is true. - writepage should start writeout, should set PG_Writeback, - and should make sure the page is unlocked, either synchronously - or asynchronously when the write operation completes. - - If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to - try too hard if there are problems, and may choose to write out - other pages from the mapping if that is easier (e.g. due to - internal dependencies). If it chooses not to start writeout, it - should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep - calling ->writepage on that page. - - See the file "Locking" for more details. + This may happen for data integrity reasons (i.e. 'sync'), or + to free up memory (flush). The difference can be seen in + wbc->sync_mode. + The PG_Dirty flag has been cleared and PageLocked is true. + writepage should start writeout, should set PG_Writeback, + and should make sure the page is unlocked, either synchronously + or asynchronously when the write operation completes. + + If wbc->sync_mode is WB_SYNC_NONE, ->writepage doesn't have to + try too hard if there are problems, and may choose to write out + other pages from the mapping if that is easier (e.g. due to + internal dependencies). If it chooses not to start writeout, it + should return AOP_WRITEPAGE_ACTIVATE so that the VM will not keep + calling ->writepage on that page. + + See the file "Locking" for more details. readpage: called by the VM to read a page from backing store. - The page will be Locked when readpage is called, and should be - unlocked and marked uptodate once the read completes. - If ->readpage discovers that it needs to unlock the page for - some reason, it can do so, and then return AOP_TRUNCATED_PAGE. - In this case, the page will be relocated, relocked and if - that all succeeds, ->readpage will be called again. + The page will be Locked when readpage is called, and should be + unlocked and marked uptodate once the read completes. + If ->readpage discovers that it needs to unlock the page for + some reason, it can do so, and then return AOP_TRUNCATED_PAGE. + In this case, the page will be relocated, relocked and if + that all succeeds, ->readpage will be called again. writepages: called by the VM to write out pages associated with the - address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then - the writeback_control will specify a range of pages that must be - written out. If it is WBC_SYNC_NONE, then a nr_to_write is given + address_space object. If wbc->sync_mode is WBC_SYNC_ALL, then + the writeback_control will specify a range of pages that must be + written out. If it is WBC_SYNC_NONE, then a nr_to_write is given and that many pages should be written if possible. If no ->writepages is given, then mpage_writepages is used - instead. This will choose pages from the address space that are - tagged as DIRTY and will pass them to ->writepage. + instead. This will choose pages from the address space that are + tagged as DIRTY and will pass them to ->writepage. set_page_dirty: called by the VM to set a page dirty. - This is particularly needed if an address space attaches - private data to a page, and that data needs to be updated when - a page is dirtied. This is called, for example, when a memory + This is particularly needed if an address space attaches + private data to a page, and that data needs to be updated when + a page is dirtied. This is called, for example, when a memory mapped page gets modified. If defined, it should set the PageDirty flag, and the - PAGECACHE_TAG_DIRTY tag in the radix tree. + PAGECACHE_TAG_DIRTY tag in the radix tree. readpages: called by the VM to read pages associated with the address_space - object. This is essentially just a vector version of - readpage. Instead of just one page, several pages are - requested. + object. This is essentially just a vector version of + readpage. Instead of just one page, several pages are + requested. readpages is only used for read-ahead, so read errors are - ignored. If anything goes wrong, feel free to give up. + ignored. If anything goes wrong, feel free to give up. write_begin: Called by the generic buffered write code to ask the filesystem to @@ -663,7 +663,7 @@ struct address_space_operations { storage, then those blocks should be pre-read (if they haven't been read already) so that the updated blocks can be written out properly. - The filesystem must return the locked pagecache page for the specified + The filesystem must return the locked pagecache page for the specified offset, in *pagep, for the caller to write into. It must be able to cope with short writes (where the length passed to @@ -672,30 +672,30 @@ struct address_space_operations { flags is a field for AOP_FLAG_xxx flags, described in include/linux/fs.h. - A void * may be returned in fsdata, which then gets passed into - write_end. + A void * may be returned in fsdata, which then gets passed into + write_end. - Returns 0 on success; < 0 on failure (which is the error code), in + Returns 0 on success; < 0 on failure (which is the error code), in which case write_end is not called. write_end: After a successful write_begin, and data copy, write_end must - be called. len is the original len passed to write_begin, and copied - is the amount that was able to be copied (copied == len is always true + be called. len is the original len passed to write_begin, and copied + is the amount that was able to be copied (copied == len is always true if write_begin was called with the AOP_FLAG_UNINTERRUPTIBLE flag). - The filesystem must take care of unlocking the page and releasing it - refcount, and updating i_size. + The filesystem must take care of unlocking the page and releasing it + refcount, and updating i_size. - Returns < 0 on failure, otherwise the number of bytes (<= 'copied') - that were able to be copied into pagecache. + Returns < 0 on failure, otherwise the number of bytes (<= 'copied') + that were able to be copied into pagecache. bmap: called by the VFS to map a logical block offset within object to - physical block number. This method is used by the FIBMAP - ioctl and for working with swap-files. To be able to swap to - a file, the file must have a stable mapping to a block - device. The swap system does not go through the filesystem - but instead uses bmap to find out where the blocks in the file - are and uses those addresses directly. + physical block number. This method is used by the FIBMAP + ioctl and for working with swap-files. To be able to swap to + a file, the file must have a stable mapping to a block + device. The swap system does not go through the filesystem + but instead uses bmap to find out where the blocks in the file + are and uses those addresses directly. dentry_open: *WARNING: probably going away soon, do not use!* This is an alternative to f_op->open(), the difference is that this method may open @@ -717,46 +717,46 @@ struct address_space_operations { release MUST succeed. releasepage: releasepage is called on PagePrivate pages to indicate - that the page should be freed if possible. ->releasepage - should remove any private data from the page and clear the - PagePrivate flag. If releasepage() fails for some reason, it must + that the page should be freed if possible. ->releasepage + should remove any private data from the page and clear the + PagePrivate flag. If releasepage() fails for some reason, it must indicate failure with a 0 return value. releasepage() is used in two distinct though related cases. The first is when the VM finds a clean page with no active users and - wants to make it a free page. If ->releasepage succeeds, the - page will be removed from the address_space and become free. + wants to make it a free page. If ->releasepage succeeds, the + page will be removed from the address_space and become free. The second case is when a request has been made to invalidate - some or all pages in an address_space. This can happen - through the fadvice(POSIX_FADV_DONTNEED) system call or by the - filesystem explicitly requesting it as nfs and 9fs do (when - they believe the cache may be out of date with storage) by - calling invalidate_inode_pages2(). + some or all pages in an address_space. This can happen + through the fadvice(POSIX_FADV_DONTNEED) system call or by the + filesystem explicitly requesting it as nfs and 9fs do (when + they believe the cache may be out of date with storage) by + calling invalidate_inode_pages2(). If the filesystem makes such a call, and needs to be certain - that all pages are invalidated, then its releasepage will - need to ensure this. Possibly it can clear the PageUptodate - bit if it cannot free private data yet. + that all pages are invalidated, then its releasepage will + need to ensure this. Possibly it can clear the PageUptodate + bit if it cannot free private data yet. freepage: freepage is called once the page is no longer visible in - the page cache in order to allow the cleanup of any private + the page cache in order to allow the cleanup of any private data. Since it may be called by the memory reclaimer, it should not assume that the original address_space mapping still exists, and it should not block. direct_IO: called by the generic read/write routines to perform - direct_IO - that is IO requests which bypass the page cache - and transfer data directly between the storage and the - application's address space. + direct_IO - that is IO requests which bypass the page cache + and transfer data directly between the storage and the + application's address space. migrate_page: This is used to compact the physical memory usage. - If the VM wants to relocate a page (maybe off a memory card - that is signalling imminent failure) it will pass a new page + If the VM wants to relocate a page (maybe off a memory card + that is signalling imminent failure) it will pass a new page and an old page to this function. migrate_page should transfer any private data across and update any references - that it has to the page. + that it has to the page. launder_page: Called before freeing a page - it writes back the dirty page. To - prevent redirtying the page, it is kept locked during the whole + prevent redirtying the page, it is kept locked during the whole operation. is_partially_uptodate: Called by the VM when reading a file through the @@ -858,7 +858,7 @@ otherwise noted. unlocked_ioctl: called by the ioctl(2) system call. compat_ioctl: called by the ioctl(2) system call when 32 bit system calls - are used on 64 bit kernels. + are used on 64 bit kernels. mmap: called by the mmap(2) system call @@ -882,7 +882,7 @@ otherwise noted. (non-blocking) mode is enabled for a file lock: called by the fcntl(2) system call for F_GETLK, F_SETLK, and F_SETLKW - commands + commands get_unmapped_area: called by the mmap(2) system call @@ -891,14 +891,14 @@ otherwise noted. flock: called by the flock(2) system call splice_write: called by the VFS to splice data from a pipe to a file. This - method is used by the splice(2) system call + method is used by the splice(2) system call splice_read: called by the VFS to splice data from file to a pipe. This - method is used by the splice(2) system call + method is used by the splice(2) system call setlease: called by the VFS to set or release a file lock lease. setlease - implementations should call generic_setlease to record or remove - the lease in the inode after setting it. + implementations should call generic_setlease to record or remove + the lease in the inode after setting it. fallocate: called by the VFS to preallocate blocks or punch a hole. -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/
