From patchwork Mon Mar 2 11:30:56 2015 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Kinglong Mee X-Patchwork-Id: 5911681 Return-Path: X-Original-To: patchwork-linux-fsdevel@patchwork.kernel.org Delivered-To: patchwork-parsemail@patchwork2.web.kernel.org Received: from mail.kernel.org (mail.kernel.org [198.145.29.136]) by patchwork2.web.kernel.org (Postfix) with ESMTP id 4077DBF440 for ; Mon, 2 Mar 2015 11:31:16 +0000 (UTC) Received: from mail.kernel.org (localhost [127.0.0.1]) by mail.kernel.org (Postfix) with ESMTP id E2E8F2026C for ; Mon, 2 Mar 2015 11:31:14 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.kernel.org (Postfix) with ESMTP id 9279520266 for ; Mon, 2 Mar 2015 11:31:13 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1754197AbbCBLbM (ORCPT ); Mon, 2 Mar 2015 06:31:12 -0500 Received: from mail-pa0-f50.google.com ([209.85.220.50]:42231 "EHLO mail-pa0-f50.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754081AbbCBLbK (ORCPT ); Mon, 2 Mar 2015 06:31:10 -0500 Received: by padfa1 with SMTP id fa1so13497820pad.9 for ; Mon, 02 Mar 2015 03:31:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=message-id:date:from:user-agent:mime-version:to:cc:subject :content-type:content-transfer-encoding; bh=8iZlrvsLYoKu9OPfcaH2CfztACMHgQn3sTabql2Nuys=; b=U2RFCC/3RqrBNght29Wzp5VGHWsTV5mdsNkBTYPWl1EEBWsS59nTQFobX999GkpQ4b GaEn6Aejz+H6Yb7IKoH2zkOAkkDTlQySHteFQzVThjMFY6UVgAjvCEBzjr+9EwlH/WtT 3mLzrjhNnu9y+NkzNrrw2z40qdYufc0LxgGnLWDxyo0PGWDNbSBtRal9uXFtqBw1YnW2 iaIBVybpn1ovYCN+t0WiPTYnlXjCuQOxSj7nnXLuRVdTEk9m+FGTdm3783IQ8T90d1Tw ksNkufIH8k04e5EVIhe+mUNZs/MfiVCCCbGpmXmnXEh3QmQmOMB3P7mbynwLYqMS3iJ2 Nwpw== X-Received: by 10.68.134.37 with SMTP id ph5mr46182525pbb.4.1425295869937; Mon, 02 Mar 2015 03:31:09 -0800 (PST) Received: from [192.168.99.4] ([104.143.41.8]) by mx.google.com with ESMTPSA id ep2sm11629353pbc.78.2015.03.02.03.31.06 (version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 02 Mar 2015 03:31:09 -0800 (PST) Message-ID: <54F449F0.9070503@gmail.com> Date: Mon, 02 Mar 2015 19:30:56 +0800 From: Kinglong Mee User-Agent: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:31.0) Gecko/20100101 Thunderbird/31.5.0 MIME-Version: 1.0 To: Al Viro CC: linux-fsdevel@vger.kernel.org Subject: [PATCH] vfs: update vfs.txt documentation Sender: linux-fsdevel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fsdevel@vger.kernel.org X-Spam-Status: No, score=-6.8 required=5.0 tests=BAYES_00, DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED, FREEMAIL_FROM, RCVD_IN_DNSWL_HI, T_DKIM_INVALID, T_RP_MATCHES_RCVD, UNPARSEABLE_RELAY autolearn=ham version=3.3.1 X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on mail.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 1. fix some typos 2. remove generic_delete_inode description 3. add RENAME_WHITEOUT description 4. add d_prune in dentry_operations Signed-off-by: Kinglong Mee --- Documentation/filesystems/vfs.txt | 74 +++++++++++++++++++-------------------- 1 file changed, 36 insertions(+), 38 deletions(-) diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt index 966b228..bbe7685 100644 --- a/Documentation/filesystems/vfs.txt +++ b/Documentation/filesystems/vfs.txt @@ -262,11 +262,6 @@ or bottom half). want to cache inodes - causing "delete_inode" to always be called regardless of the value of i_nlink) - The "generic_delete_inode()" behavior is equivalent to the - old practice of using "force_delete" in the put_inode() case, - but does not have the races that the "force_delete()" approach - had. - delete_inode: called when the VFS wants to delete an inode put_super: called when the VFS wishes to free the superblock @@ -288,7 +283,7 @@ or bottom half). remount_fs: called when the filesystem is remounted. This is called with the kernel lock held - clear_inode: called then the VFS clears the inode. Optional + clear_inode: called when the VFS clears the inode. Optional umount_begin: called when the VFS is unmounting a filesystem. @@ -303,7 +298,7 @@ or bottom half). filesystem to return the number of freeable cached objects it contains. Optional. - free_cache_objects: called by the sb cache shrinking function for the + free_cached_objects: called by the sb cache shrinking function for the filesystem to scan the number of objects indicated to try to free them. Optional, but any filesystem implementing this method needs to also implement ->nr_cached_objects for it to be called correctly. @@ -386,7 +381,7 @@ otherwise noted. be done on a real error, otherwise creating inodes with system calls like create(2), mknod(2), mkdir(2) and so on will fail. If you wish to overload the dentry methods then you should - initialise the "d_dop" field in the dentry; this is a pointer + initialise the "d_op" field in the dentry; this is a pointer to a struct "dentry_operations". This method is called with the directory inode semaphore held @@ -430,6 +425,9 @@ otherwise noted. (2) RENAME_EXCHANGE: exchange source and target. Both must exist; this is checked by the VFS. Unlike plain rename, source and target may be of different type. + (3) RENAME_WHITEOUT: from 3.18.0, this flag makes rename() + creating a whiteout of source. The whiteout creation is atomic + relative to the rename. readlink: called by the readlink(2) system call. Only required if you want to support reading symbolic links @@ -471,7 +469,7 @@ otherwise noted. attribute name. This method is called by getxattr(2) function call. - listxattr: called by the VFS to list all extended attributes for a + listxattr: called by the VFS to list all extended attributes names for a given file. This method is called by listxattr(2) system call. removexattr: called by the VFS to remove an extended attribute from @@ -494,6 +492,12 @@ otherwise noted. tmpfile: called in the end of O_TMPFILE open(). Optional, equivalent to atomically creating, opening and unlinking a file in given directory. + 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 + a file not necessarily originating from the same filesystem as the one + i_op->open() was called on. It may be useful for stacking filesystems + which want to allow native I/O directly on underlying files. + The Address Space Object ======================== @@ -520,7 +524,7 @@ lru_cache_add and mark_page_active needs to be called whenever the page is used. Pages are normally kept in a radix tree index by ->index. This tree -maintains information about the PG_Dirty and PG_Writeback status of +maintains information about the PG_dirty and PG_writeback status of each page, so that pages with either of these flags can be found quickly. @@ -529,7 +533,7 @@ The Dirty tag is primarily used by mpage_writepages - the default ->writepage on. If mpage_writepages is not used (i.e. the address provides its own ->writepages) , the PAGECACHE_TAG_DIRTY tag is almost unused. write_inode_now and sync_inode do use it (through -__sync_single_inode) to check if ->writepages has been successful in +writeback_single_inode) to check if ->writepages has been successful in writing out the whole address_space. The Writeback tag is used by filemap*wait* and sync_page* functions, @@ -539,7 +543,7 @@ each page that is found to require writeback. An address_space handler may attach extra information to a page, typically using the 'private' field in the 'struct page'. If such -information is attached, the PG_Private flag should be set. This will +information is attached, the PG_private flag should be set. This will cause various VM routines to make extra calls into the address_space handler to deal with that data. @@ -559,11 +563,11 @@ sync_page, and writepages to writeback data to storage. Adding and removing pages to/from an address_space is protected by the inode's i_mutex. -When data is written to a page, the PG_Dirty flag should be set. It +When data is written to a page, the PG_dirty flag should be set. It typically remains set until writepage asks for it to be written. This -should clear PG_Dirty and set PG_Writeback. It can be actually -written at any point after PG_Dirty is clear. Once it is known to be -safe, PG_Writeback is cleared. +should clear PG_dirty and set PG_writeback. It can be actually +written at any point after PG_dirty is clear. Once it is known to be +safe, PG_writeback is cleared. Writeback makes use of a writeback_control structure... @@ -606,8 +610,8 @@ struct address_space_operations { 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, + 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. @@ -695,13 +699,6 @@ struct address_space_operations { 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 - a file not necessarily originating from the same filesystem as the one - i_op->open() was called on. It may be useful for stacking filesystems - which want to allow native I/O directly on underlying files. - - invalidatepage: If a page has PagePrivate set, then invalidatepage will be called when part or all of the page is to be removed from the address space. This generally corresponds to either a @@ -838,14 +835,14 @@ otherwise noted. read: called by read(2) and related system calls - aio_read: vectored, possibly asynchronous read - - read_iter: possibly asynchronous read with iov_iter as destination - write: called by write(2) and related system calls + aio_read: vectored, possibly asynchronous read + aio_write: vectored, possibly asynchronous write + read_iter: possibly asynchronous read with iov_iter as destination + write_iter: possibly asynchronous write with iov_iter as source iterate: called when the VFS needs to read the directory contents @@ -934,6 +931,7 @@ struct dentry_operations { unsigned int, const char *, const struct qstr *); int (*d_delete)(const struct dentry *); void (*d_release)(struct dentry *); + void (*d_prune)(struct dentry *); void (*d_iput)(struct dentry *, struct inode *); char *(*d_dname)(struct dentry *, char *, int); struct vfsmount *(*d_automount)(struct path *); @@ -959,7 +957,7 @@ struct dentry_operations { If a situation is encountered that rcu-walk cannot handle, return -ECHILD and it will be called again in ref-walk mode. - d_weak_revalidate: called when the VFS needs to revalidate a "jumped" dentry. + d_weak_revalidate: called when the VFS needs to revalidate a "jumped" dentry. This is called when a path-walk ends at dentry that was not acquired by doing a lookup in the parent directory. This includes "/", "." and "..", as well as procfs-style symlinks and mountpoint traversal. @@ -1022,6 +1020,14 @@ struct dentry_operations { at the end of the buffer, and returns a pointer to the first char. dynamic_dname() helper function is provided to take care of this. + Example : + + static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) + { + return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", + dentry->d_inode->i_ino); + } + d_automount: called when an automount dentry is to be traversed (optional). This should create a new VFS mount record and return the record to the caller. The caller is supplied with a path parameter giving the @@ -1060,14 +1066,6 @@ struct dentry_operations { This function is only used if DCACHE_MANAGE_TRANSIT is set on the dentry being transited from. -Example : - -static char *pipefs_dname(struct dentry *dent, char *buffer, int buflen) -{ - return dynamic_dname(dentry, buffer, buflen, "pipe:[%lu]", - dentry->d_inode->i_ino); -} - Each dentry has a pointer to its parent dentry, as well as a hash list of child dentries. Child dentries are basically like files in a directory.