Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752533AbbHSDPq (ORCPT ); Tue, 18 Aug 2015 23:15:46 -0400 Received: from mail-pd0-f181.google.com ([209.85.192.181]:35346 "EHLO mail-pd0-f181.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1752301AbbHSDPW (ORCPT ); Tue, 18 Aug 2015 23:15:22 -0400 Subject: Re: [PATCH] Clean up whitespace in vfs.txt To: linux-kernel@vger.kernel.org References: <1439199067.21940.6.camel@gmail.com> Cc: Andrew Morton , trivial@kernel.org From: Raymond Jennings Message-ID: <55D3F4C6.1070300@gmail.com> Date: Tue, 18 Aug 2015 20:15:18 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.1.0 MIME-Version: 1.0 In-Reply-To: <1439199067.21940.6.camel@gmail.com> Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 25635 Lines: 556 On 08/10/15 02:31, Raymond Jennings wrote: > I noticed that vfs.txt looked kinda funky, so I went ahead and > reformatted it. > > Signed-off-by: Raymond Jennings > Cc: Andrew Morton > > --- > > 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. Are there any problems with this patch or how I submitted it? I'm still pretty new to the process. -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/