[PATCH] Documentation/filesystems: fix documentation for ->getattr()

[PATCH] Documentation/filesystems: fix documentation for ->getattr()

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Following the recent merge of statx, correct the documented prototype
for the ->getattr() inode operation, and add an entry to the porting
file.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/filesystems/Locking | 3 +--
 Documentation/filesystems/porting | 6 ++++++
 Documentation/filesystems/vfs.txt | 3 +--
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
index fdcfdd79682a..fe25787ff6d4 100644
--- a/Documentation/filesystems/Locking
+++ b/Documentation/filesystems/Locking
@@ -58,8 +58,7 @@ prototypes:
 	int (*permission) (struct inode *, int, unsigned int);
 	int (*get_acl)(struct inode *, int);
 	int (*setattr) (struct dentry *, struct iattr *);
-	int (*getattr) (const struct path *, struct dentry *, struct kstat *,
-			u32, unsigned int);
+	int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
 	ssize_t (*listxattr) (struct dentry *, char *, size_t);
 	int (*fiemap)(struct inode *, struct fiemap_extent_info *, u64 start, u64 len);
 	void (*update_time)(struct inode *, struct timespec *, int);
diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
index 95280079c0b3..5fb17f49f7a2 100644
--- a/Documentation/filesystems/porting
+++ b/Documentation/filesystems/porting
@@ -600,3 +600,9 @@ in your dentry operations instead.
 [recommended]
 	->readlink is optional for symlinks.  Don't set, unless filesystem needs
 	to fake something for readlink(2).
+--
+[mandatory]
+	->getattr() is now passed a struct path rather than a vfsmount and
+	dentry separately, and it now has request_mask and query_flags arguments
+	to specify the fields and sync type requested by statx.  Filesystems not
+	supporting any statx-specific features may ignore the new arguments.
diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
index 569211703721..94dd27ef4a76 100644
--- a/Documentation/filesystems/vfs.txt
+++ b/Documentation/filesystems/vfs.txt
@@ -382,8 +382,7 @@ struct inode_operations {
 	int (*permission) (struct inode *, int);
 	int (*get_acl)(struct inode *, int);
 	int (*setattr) (struct dentry *, struct iattr *);
-	int (*getattr) (const struct path *, struct dentry *, struct kstat *,
-			u32, unsigned int);
+	int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);
 	ssize_t (*listxattr) (struct dentry *, char *, size_t);
 	void (*update_time)(struct inode *, struct timespec *, int);
 	int (*atomic_open)(struct inode *, struct dentry *, struct file *,
-- 
2.12.0

Re: [PATCH] Documentation/filesystems: fix documentation for ->getattr()

[Andreas Dilger]

[-- Attachment #1: Type: text/plain, Size: 2554 bytes --]

On Mar 10, 2017, at 10:30 PM, Eric Biggers <ebiggers3@gmail.com> wrote:
> 
> From: Eric Biggers <ebiggers@google.com>
> 
> Following the recent merge of statx, correct the documented prototype
> for the ->getattr() inode operation, and add an entry to the porting
> file.
> 
> Signed-off-by: Eric Biggers <ebiggers@google.com>
> ---
> Documentation/filesystems/Locking | 3 +--
> Documentation/filesystems/porting | 6 ++++++
> Documentation/filesystems/vfs.txt | 3 +--
> 3 files changed, 8 insertions(+), 4 deletions(-)
> 
> diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking
> index fdcfdd79682a..fe25787ff6d4 100644
> --- a/Documentation/filesystems/Locking
> +++ b/Documentation/filesystems/Locking
> @@ -58,8 +58,7 @@ prototypes:
> 	int (*permission) (struct inode *, int, unsigned int);
> 	int (*get_acl)(struct inode *, int);
> 	int (*setattr) (struct dentry *, struct iattr *);
> -	int (*getattr) (const struct path *, struct dentry *, struct kstat *,
> -			u32, unsigned int);

IMHO, having the interface documentation with "u32" and "unsigned int" is
not very helpful.  It would be much better if the actual argument names
were given here.  That isn't needed for self-descriptive arguments like
"struct path" and "struct kstat", but it is in this case.

> diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting
> index 95280079c0b3..5fb17f49f7a2 100644
> --- a/Documentation/filesystems/porting
> +++ b/Documentation/filesystems/porting
> @@ -600,3 +600,9 @@ in your dentry operations instead.
> +--
> +[mandatory]
> +	->getattr() is now passed a struct path rather than a vfsmount and
> +	dentry separately, and it now has request_mask and query_flags arguments
> +	to specify the fields and sync type requested by statx.  Filesystems not
> +	supporting any statx-specific features may ignore the new arguments.
> diff --git a/Documentation/filesystems/vfs.txt b/Documentation/filesystems/vfs.txt
> index 569211703721..94dd27ef4a76 100644
> --- a/Documentation/filesystems/vfs.txt
> +++ b/Documentation/filesystems/vfs.txt
> @@ -382,8 +382,7 @@ struct inode_operations {
> 	int (*permission) (struct inode *, int);
> 	int (*get_acl)(struct inode *, int);
> 	int (*setattr) (struct dentry *, struct iattr *);
> -	int (*getattr) (const struct path *, struct dentry *, struct kstat *,
> -			u32, unsigned int);
> +	int (*getattr) (const struct path *, struct kstat *, u32, unsigned int);

Same here...


Cheers, Andreas






[-- Attachment #2: Message signed with OpenPGP --]
[-- Type: application/pgp-signature, Size: 195 bytes --]