From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-alma10-1.taild15c8.ts.net [100.103.45.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id B90F53033DF; Mon, 21 Sep 2026 03:51:26 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=100.103.45.18 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789962688; cv=none; b=Loyjdwm/KMz/g2FBDe0lH3kRozVyu1q7YMpKa7GYpbELm/8ge5IvTUwqijnL8ZKzJ40G02gUjIRtdr5EFu+sh1uuCmMwHnvt/o7etrha9P91xZ0BsmmpVpsSWpO1k7VbXzY5BoJwUMCLH4gauvF95wu9VoGx+DlltA2hOxFuYWU= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789962688; c=relaxed/simple; bh=wXOrMsVmbXco3HExOgaPBQd4T0WtTjMT4CsBnJQFWrA=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=jZ10sP7FMug+5iLqYksDUT7guYDM8IiE3Ci0+zLZErk6+lOUW0aiPsAUVb+X2oGCMrXCXWPRsot78Tlupju95Y7Qa58RUBgETdYklmTbZpaKN28NbXmpCKC1Qj9AOUTHEjMVztkv3L6ySIkkwtkkbhx9Ye731rKWj1rdXCsJmuw= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=O0t+SXBt; arc=none smtp.client-ip=100.103.45.18 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="O0t+SXBt" Received: by smtp.kernel.org (Postfix) with UTF8SMTPSA id 510581F000FF; Mon, 21 Sep 2026 03:51:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kernel.org; s=k20260515; t=1789962686; bh=JiVKPsi63jLWPBHFVsHOJjmAeX9bDFSgfW+In57Jo+s=; h=Date:From:To:Cc:Subject:References:In-Reply-To; b=O0t+SXBtveth50eP/EmwuJdIVLqwmoMyuqqoGug283btNbpSKD6tcdUfsibtJMbRx dMHOUTv7sdrLPECsQfEW7Mzobt7vh8f/UNayn/B1r7hWMiq1jBZTvJ8G9cL3NLRYIk h+GHOYq4PZtmdNaE/6APtJxleaCz7XLSwDXdkuxfr5npd7/CiRCIsFsfX2XEqIkA96 Nis8K1L0Q759/FTdWAOArOqPdK+GATNZ+TezepBbI9fyYJ4LrMKKeccnwtTv/W7qUG yvgLPtlweDUAI93w4o8AwD2xLhkdJa74eNtGNs9IrfgtFEsdarJjtW8yV1yFemPwnR 4pXAnwLv6sM/A== Date: Sun, 20 Sep 2026 20:51:25 -0700 From: "Darrick J. Wong" To: Andrey Albershteyn Cc: Alejandro Colomar , linux-man@vger.kernel.org, linux-api@vger.kernel.org, linux-xfs@vger.kernel.org, linux-fsdevel@vger.kernel.org, Christoph Hellwig Subject: Re: [PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls Message-ID: <20260921035125.GI2705364@frogsfrogsfrogs> References: <20260914111107.1735564-1-aalbersh@kernel.org> <20260916115141.3500780-1-aalbersh@kernel.org> Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20260916115141.3500780-1-aalbersh@kernel.org> On Wed, Sep 16, 2026 at 01:51:39PM +0200, Andrey Albershteyn wrote: > Add manual pages for file_getattr() and file_setattr() syscalls and > struct file_attr used as input/output argument. > > Signed-off-by: Andrey Albershteyn > Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/ Looks good to me still :) Reviewed-by: "Darrick J. Wong" --D > > --- > Changes from v3: > - dropped VERSIONS section in file_attr.2type > - reference arguments and errors from file_setattr to file_getattr > - Minor wording fixes > - Minor formatting fixes > - Removed zero-initialized requirement > - Interdiff with v3 below > > Changes from v2: > - a few grammar fixes > - styling fixes > - sashiko.dev fixes (wrong AT_FDCWD combined with AT_EMPTY_PATH > description, unused "dfd") > - dropped requirement to zero fattr before using file_setattr() > - Pathname -> path > - Dropped description of why FS_IOC_ aren't usable with special files > - Fixed backslashes in the code examples > --- > man/man2/file_getattr.2 | 254 +++++++++++++++++++++++++++++++++++ > man/man2/file_setattr.2 | 180 +++++++++++++++++++++++++ > man/man2type/file_attr.2type | 151 +++++++++++++++++++++ > 3 files changed, 585 insertions(+) > create mode 100644 man/man2/file_getattr.2 > create mode 100644 man/man2/file_setattr.2 > create mode 100644 man/man2type/file_attr.2type > > diff --git a/man/man2/file_getattr.2 b/man/man2/file_getattr.2 > new file mode 100644 > index 000000000000..fe804d97976b > --- /dev/null > +++ b/man/man2/file_getattr.2 > @@ -0,0 +1,254 @@ > +.\" Copyright, the authors of the Linux man-pages project > +.\" > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft > +.\" > +.TH file_getattr 2 (date) "Linux man-pages (unreleased)" > +.SH NAME > +file_getattr \- get filesystem file attributes > +.SH SYNOPSIS > +.nf > +.BR "#include " " /* " AT_* " constants */" > +.BR "#include " " /* " FS_XFLAG_* " constants */" > +.BR "#include " " /* " SYS_* " constants */" > +.B #include > +.P > +.B long syscall(SYS_file_getattr, > +.BI " int " dirfd ", const char *" path , > +.BI " struct file_attr *" fattr ", size_t " size , > +.BI " unsigned int " flags ); > +.fi > +.SH DESCRIPTION > +The > +.BR file_getattr () > +system call retrieves filesystem file attributes > +specified by path. > +.P > +As with > +.BR openat (2), > +if > +.I path > +is relative, > +then it is interpreted relative to the directory > +referred to by the file descriptor > +.IR dirfd . > +The special > +.I dirfd > +value > +.B AT_FDCWD > +can be used to refer to the current working directory of the calling process. > +If > +.I path > +is absolute, > +then > +.I dirfd > +is ignored. > +.P > +The > +.I fattr > +argument is a pointer to a > +.I file_attr > +structure. > +This structure will be filled with file attributes. > +This structure is described in > +.BR file_attr (2type). > +.P > +The > +.I size > +argument specifies the size of the structure pointed to by > +.IR fattr . > +The size indicates version of the structure in use, refer to > +.B file_attr (2type) > +for more information on versioning. > +.P > +The > +.I flags > +argument contains a bitwise OR of zero or more of the following constants: > +.TP > +.B AT_EMPTY_PATH > +If > +.I path > +is an empty string, > +operate on the file referred to by > +.IR dirfd . > +In this case, > +.I dirfd > +can refer to any type of file, > +not just a directory. > +.TP > +.B AT_SYMLINK_NOFOLLOW > +If > +.I path > +is a symbolic link, > +do not dereference it; > +instead get attributes of the symbolic link inode itself. > +By default, symbolic links are dereferenced. > +.SH RETURN VALUE > +On success, > +zero is returned. > +On error, > +\-1 is returned, > +and > +.I errno > +is set to indicate the error. > +.SH ERRORS > +.TP > +.B E2BIG > +.I size > +is too big (larger than > +.BR PAGE_SIZE ). > +.TP > +.B EACCES > +Search permission is denied for one of the directories > +in the path prefix of > +.IR path . > +.TP > +.B EBADF > +.I path > +is relative but > +.I dirfd > +is neither > +.B AT_FDCWD > +nor a valid file descriptor. > +.TP > +.B EBADF > +.I path > +is an empty string, > +.B AT_EMPTY_PATH > +was specified, > +but > +.I dirfd > +is neither > +.B AT_FDCWD > +nor a valid file descriptor. > +.TP > +.B EFAULT > +.I path > +or > +.I fattr > +is an invalid pointer. > +.TP > +.B EINVAL > +Unknown flag specified in > +.IR flags . > +.TP > +.B EINVAL > +.I size > +is smaller than > +.BR FILE_ATTR_SIZE_VER0 . > +.TP > +.B ELOOP > +Too many symbolic links encountered while resolving > +.IR path . > +.TP > +.B ENAMETOOLONG > +.I path > +is too long. > +.TP > +.B ENOENT > +A component of > +.I path > +does not exist, > +or > +.I path > +is an empty string and > +.B AT_EMPTY_PATH > +was not specified in > +.IR flags . > +.TP > +.B ENOMEM > +Insufficient kernel memory was available. > +.TP > +.B ENOTDIR > +A component of the path prefix of > +.I path > +is not a directory, or > +.I path > +is relative and > +.I dirfd > +is a file descriptor referring to a file other than a directory. > +.TP > +.B EOPNOTSUPP > +The filesystem does not support getting attributes on this type of inode. > +.SH HISTORY > +.SS Linux 6.17 > +This system call is introduced. > +.SH NOTES > +This system call is designed to be extensible. > +The > +.I size > +argument allows user-space applications to indicate > +which version of the > +.I file_attr > +structure they are using, > +enabling the kernel to support both old and new versions > +of the structure simultaneously. > +.P > +If > +.I size > +is smaller than the structure size the kernel expects, > +only the fields that fit within > +.I size > +will be filled in. > +If > +.I size > +is larger than the kernel's structure size, > +the extra bytes are zeroed. > +.SH EXAMPLES > +The program below demonstrates the use of > +.BR file_getattr () > +to retrieve and display file attributes. > +.P > +.in +4n > +.EX > +#include > +#include > +#include > +#include > +#include > +#include > + > +#ifndef SYS_file_getattr > +#define SYS_file_getattr 467 > +#endif > + > +int > +main(int argc, char *argv[]) > +{ > + struct file_attr fa; > + long ret; > + > + if (argc != 2) { > + fprintf(stderr, "Usage: %s \[rs]n", argv[0]); > + exit(EXIT_FAILURE); > + } > + > + ret = syscall(SYS_file_getattr, AT_FDCWD, argv[1], &fa, sizeof(fa), 0); > + if (ret == \-1) { > + perror("file_getattr"); > + exit(EXIT_FAILURE); > + } > + > + printf("File attributes:\[rs]n"); > + printf(" xflags: 0x%llx\[rs]n", (unsigned long long) fa.fa_xflags); > + printf(" extsize: %u\[rs]n", fa.fa_extsize); > + printf(" nextents: %u\[rs]n", fa.fa_nextents); > + printf(" projid: %u\[rs]n", fa.fa_projid); > + printf(" cowextsize: %u\[rs]n", fa.fa_cowextsize); > + > + /* > + * Try setting NODUMP flag with chattr +d ./foo to see the difference > + */ > + if (fa.fa_xflags & FS_XFLAG_NODUMP) > + printf(" NODUMP flag is set\[rs]n"); > + > + exit(EXIT_SUCCESS); > +} > +.EE > +.in > +.SH SEE ALSO > +.BR file_setattr (2), > +.BR file_attr (2type), > +.BR ioctl (2), > +.BR ioctl_fs (2), > +.BR openat (2), > +.BR ioctl_xfs_fssetxattr (2) > diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2 > new file mode 100644 > index 000000000000..0389f42afb50 > --- /dev/null > +++ b/man/man2/file_setattr.2 > @@ -0,0 +1,180 @@ > +.\" Copyright, the authors of the Linux man-pages project > +.\" > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft > +.\" > +.TH file_setattr 2 (date) "Linux man-pages (unreleased)" > +.SH NAME > +file_setattr \- set filesystem file attributes > +.SH SYNOPSIS > +.nf > +.BR "#include " " /* Definition of " AT_* " constants */" > +.BR "#include " " /* Definition of " FS_XFLAG_* " constants */" > +.BR "#include " " /* Definition of " SYS_* " constants */" > +.B #include > +.P > +.B long syscall(SYS_file_setattr, > +.BI " int " dirfd ", const char *" path , > +.BI " struct file_attr *" fattr ", size_t " size , > +.BI " unsigned int " flags ); > +.fi > +.P > +.SH DESCRIPTION > +The > +.BR file_setattr () > +system call sets filesystem file attributes > +on the file specified by path. > +.P > +The > +.IR dirfd , > +.IR path , > +.IR fattr , > +.IR size , > +and > +.I flags > +arguments behaves in the same way as in > +.BR file_getattr (2). > +The only difference is that > +user-space applications should use > +.BR file_getattr (2) > +to initialize > +.I fattr > +argument beforehand. > +.SH RETURN VALUE > +On success, > +zero is returned. > +On error, > +\-1 is returned, > +and > +.I errno > +is set to indicate the error. > +.SH ERRORS > +.P > +The errors are the same as returned by > +.BR file_getattr (2) > +with the addition of following ones: > +.TP > +.B E2BIG > +.I size > +indicates a version which the kernel doesn't support > +(the size is larger than the kernel expects) > +and new fields are non-zero. > +.TP > +.B EINVAL > +Invalid combination of parameters provided in > +.I fattr > +for this type of file or filesystem. > +.TP > +.B EPERM > +The caller does not have the necessary permissions > +to change the file attributes. > +.TP > +.B EROFS > +The file is on a read-only filesystem. > +.SH HISTORY > +.SS Linux 6.17 > +This system call is introduced. > +.SH NOTES > +This system call is designed to be extensible. > +The > +.I size > +argument allows user-space applications to indicate > +which version of the > +.I file_attr > +structure they are using, > +enabling the kernel to support both old and new versions > +of the structure simultaneously. > +.P > +If > +.I size > +is smaller than the structure size the kernel expects, > +the kernel treats the missing fields as having zero values > +(which is a no-op). > +If > +.I size > +is larger than expected, > +the kernel checks that all unknown (to the kernel) fields are zero; > +if not, > +the call fails with > +.BR E2BIG . > +.SH EXAMPLES > +The program below demonstrates the use of > +.BR file_setattr () > +to set the > +.B FS_XFLAG_NODUMP > +flag on a file. > +.P > +.in +4n > +.EX > +#include > +#include > +#include > +#include > +#include > +#include > +#include > +#include > + > +#ifndef SYS_file_getattr > +#define SYS_file_getattr 467 > +#endif > + > +#ifndef SYS_file_setattr > +#define SYS_file_setattr 468 > +#endif > + > +int > +main(int argc, char *argv[]) > +{ > + struct file_attr fa; > + int dfd; > + long ret; > + > + if (argc != 2) { > + fprintf(stderr, "Usage: %s \[rs]n", argv[0]); > + exit(EXIT_FAILURE); > + } > + > + dfd = open(argv[1], O_RDONLY); > + if (dfd == \-1) { > + perror("open"); > + exit(EXIT_FAILURE); > + } > + > + ret = syscall(SYS_file_getattr, dfd, "", &fa, sizeof(fa), AT_EMPTY_PATH); > + if (ret == \-1) { > + perror("file_getattr"); > + exit(EXIT_FAILURE); > + } > + > + printf("Current flags: 0x%llx\[rs]n", (unsigned long long) fa.fa_xflags); > + > + fa.fa_xflags |= FS_XFLAG_NODUMP; > + > + ret = syscall(SYS_file_setattr, dfd, "", &fa, sizeof(fa), AT_EMPTY_PATH); > + if (ret == \-1) { > + perror("file_setattr"); > + exit(EXIT_FAILURE); > + } > + > + ret = syscall(SYS_file_getattr, dfd, "", &fa, sizeof(fa), AT_EMPTY_PATH); > + if (ret == \-1) { > + perror("file_getattr"); > + exit(EXIT_FAILURE); > + } > + > + if (fa.fa_xflags & FS_XFLAG_NODUMP) > + printf("flags 0x%llx (NODUMP flag is set)\[rs]n", > + (unsigned long long) fa.fa_xflags); > + > + exit(EXIT_SUCCESS); > +} > +.EE > +.in > +.SH SEE ALSO > +.BR file_getattr (2), > +.BR ioctl (2), > +.BR ioctl_fs (2), > +.BR openat (2), > +.BR file_attr (2type), > +.BR path_resolution (7), > +.BR ioctl_xfs_fssetxattr (2) > diff --git a/man/man2type/file_attr.2type b/man/man2type/file_attr.2type > new file mode 100644 > index 000000000000..221d97b5220d > --- /dev/null > +++ b/man/man2type/file_attr.2type > @@ -0,0 +1,151 @@ > +.\" Copyright, the authors of the Linux man-pages project > +.\" > +.\" SPDX-License-Identifier: Linux-man-pages-copyleft > +.\" > +.TH file_attr 2type (date) "Linux man-pages (unreleased)" > +.SH NAME > +file_attr \- describe filesystem file attributes to get or set > +.SH SYNOPSIS > +.EX > +.B #include > +.P > +.B struct file_attr { > +.BR " u64 fa_xflags;" " /* Extended flags */" > +.BR " u32 fa_extsize;" " /* Extent size hint */" > +.BR " u32 fa_nextents;" " /* Number of extents (read-only) */" > +.BR " u32 fa_projid;" " /* Project identifier */" > +.BR " u32 fa_cowextsize;" " /* CoW extent size hint */" > +.B }; > +.EE > +.SH DESCRIPTION > +Describes filesystem file attributes > +for use with the > +.BR file_getattr (2) > +and > +.BR file_setattr (2) > +system calls. > +.P > +The fields are as follows: > +.TP > +.I fa_xflags > +This field contains file attribute flags. > +It is a bit mask consisting of zero or more of the > +.B FS_XFLAG_* > +flags. > +Refer to the section > +.B FLAGS > +below for a list of all flags. > +.TP > +.I fa_extsize > +Extent size allocator hint in bytes. > +This value suggests a preferred extent size > +for new allocations to this file. > +.TP > +.I fa_nextents > +Number of data extents in the file (read-only). > +This field is filled in by > +.BR file_getattr (2) > +and is ignored by > +.BR file_setattr (2). > +.TP > +.I fa_projid > +Project identifier. > +Used by quota systems to group related files. > +.TP > +.I fa_cowextsize > +Copy-on-Write (CoW) extent size hint in bytes. > +This value suggests a preferred extent size > +for CoW operations. > +.SH FLAGS > +Flags can be: > +.RS > +.TP > +.B FS_XFLAG_REALTIME > +Data is stored in a realtime volume. > +.TP > +.B FS_XFLAG_IMMUTABLE > +File cannot be modified. > +.TP > +.B FS_XFLAG_APPEND > +All writes must append to the end of the file. > +.TP > +.B FS_XFLAG_SYNC > +All writes are synchronous. > +.TP > +.B FS_XFLAG_NOATIME > +Do not update file access time on reads. > +.TP > +.B FS_XFLAG_NODUMP > +Do not include file in backups. > +.TP > +.B FS_XFLAG_DAX > +Use Direct Access (DAX) for I/O operations. > +.TP > +.B FS_XFLAG_NODEFRAG > +Exclude this file from defragmentation operations. > +.TP > +.B FS_XFLAG_FILESTREAM > +Use filestream allocator for this file. > +.TP > +.B FS_XFLAG_EXTSIZE > +Use the extent size hint from the > +.I fa_extsize > +field. > +.TP > +.B FS_XFLAG_COWEXTSIZE > +Use the CoW extent size hint from the > +.I fa_cowextsize > +field. > +.RE > +.P > +Directory only flags: > +.RS > +.TP > +.B FS_XFLAG_RTINHERIT > +New files created in this directory inherit the realtime flag. > +.TP > +.B FS_XFLAG_NOSYMLINKS > +Disallow creation of symbolic links in this directory. > +.TP > +.B FS_XFLAG_EXTSZINHERIT > +New files created in this directory inherit the extent size hint. > +.TP > +.B FS_XFLAG_PROJINHERIT > +New files created in this directory inherit the project identifier. > +.RE > +.P > +The following flags are read-only: > +.RS > +.TP > +.B FS_XFLAG_PREALLOC > +File has preallocated extents. > +.TP > +.B FS_XFLAG_HASATTR > +File has extended attributes. > +.TP > +.B FS_XFLAG_VERITY > +File has fs-verity enabled. > +.TP > +.B FS_XFLAG_CASEFOLD > +The filesystem performs case-insensitive lookups (file and directory name > +comparisons ignore case). > +.TP > +.B FS_XFLAG_CASENONPRESERVING > +The filesystem does not preserve the case of file and directory names. > +.RE > +.P > +Not all filesystems support all flags. > +Setting unsupported flags may result in an > +.B EINVAL > +or > +.B EOPNOTSUPP > +error. > +.SH HISTORY > +.SS Linux v6.17 > +This structure is introduced. > +.SS Linux v7.2 > +The FS_XFLAG_CASEFOLD and FS_XFLAG_CASENONPRESERVING are introduced to enable > +upper layers, such as NFSD, to retrieve case sensitivity information. > +.SH SEE ALSO > +.BR file_getattr (2), > +.BR file_setattr (2) > > Interdiff against v3: > diff --git a/man/man2/file_getattr.2 b/man/man2/file_getattr.2 > index 1168b23c5ce5..fe804d97976b 100644 > --- a/man/man2/file_getattr.2 > +++ b/man/man2/file_getattr.2 > @@ -4,7 +4,7 @@ > .\" > .TH file_getattr 2 (date) "Linux man-pages (unreleased)" > .SH NAME > -file_getattr \- get filesystem inode attributes > +file_getattr \- get filesystem file attributes > .SH SYNOPSIS > .nf > .BR "#include " " /* " AT_* " constants */" > @@ -21,7 +21,7 @@ file_getattr \- get filesystem inode attributes > The > .BR file_getattr () > system call retrieves filesystem file attributes > -from the file. > +specified by path. > .P > As with > .BR openat (2), > @@ -31,9 +31,11 @@ is relative, > then it is interpreted relative to the directory > referred to by the file descriptor > .IR dirfd . > -The special value > +The special > +.I dirfd > +value > .B AT_FDCWD > -could be used to refer to the current working directory of the calling process. > +can be used to refer to the current working directory of the calling process. > If > .I path > is absolute, > @@ -55,16 +57,9 @@ The > argument specifies the size of the structure pointed to by > .IR fattr . > The size indicates version of the structure in use, refer to > -.B file_attr(2type) > +.B file_attr (2type) > for more information on versioning. > .P > -Userspace applications should zero-initialize > -.I struct file_attr > -before calling > -.BR file_getattr () > -to ensure that fields not filled in by older kernels > -will have predictable values. > -.P > The > .I flags > argument contains a bitwise OR of zero or more of the following constants: > @@ -176,15 +171,12 @@ is a file descriptor referring to a file other than a directory. > The filesystem does not support getting attributes on this type of inode. > .SH HISTORY > .SS Linux 6.17 > -This system call is introduced as a more flexible alternative to the > -FS_IOC_FSGETXATTR > -.BR ioctl (2) > -which could work on any type of file. > +This system call is introduced. > .SH NOTES > This system call is designed to be extensible. > The > .I size > -argument allows userspace applications to indicate > +argument allows user-space applications to indicate > which version of the > .I file_attr > structure they are using, > @@ -222,7 +214,7 @@ to retrieve and display file attributes. > int > main(int argc, char *argv[]) > { > - struct file_attr fa = { 0 }; > + struct file_attr fa; > long ret; > > if (argc != 2) { > diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2 > index 2b30f25c64de..0389f42afb50 100644 > --- a/man/man2/file_setattr.2 > +++ b/man/man2/file_setattr.2 > @@ -4,12 +4,11 @@ > .\" > .TH file_setattr 2 (date) "Linux man-pages (unreleased)" > .SH NAME > -file_setattr \- set filesystem inode attributes > +file_setattr \- set filesystem file attributes > .SH SYNOPSIS > .nf > .BR "#include " " /* Definition of " AT_* " constants */" > -.BR "#include " " /* Definition of " FILE_ATTR_* \ > -" and " FS_XFLAG_* " constants */" > +.BR "#include " " /* Definition of " FS_XFLAG_* " constants */" > .BR "#include " " /* Definition of " SYS_* " constants */" > .B #include > .P > @@ -23,77 +22,23 @@ file_setattr \- set filesystem inode attributes > The > .BR file_setattr () > system call sets filesystem file attributes > -on the file. > -.P > -As with > -.BR openat (2), > -if > -.I path > -is relative, > -then it is interpreted relative to the directory > -referred to by the file descriptor > -.I dirfd > -(or the current working directory of the calling process, > -if > -.I dirfd > -is the special value > -.BR AT_FDCWD ). > -If > -.I path > -is absolute, > -then > -.I dirfd > -is ignored. > -.P > -The > -.I fattr > -argument is a pointer to a > -.I file_attr > -structure, > -which specifies the attributes to set on the file. > -This structure is described in > -.BR file_attr (2type). > -Userspace applications should use > -.B file_getattr(2) > -to initialize > -.I struct fattr > -beforehand. > -.P > -The > -.I size > -argument specifies the size of the structure pointed to by > -.IR fattr . > -The size indicates version of the structure in use, refer to > -.B file_attr(2type) > -for more information on versioning. > +on the file specified by path. > .P > The > +.IR dirfd , > +.IR path , > +.IR fattr , > +.IR size , > +and > .I flags > -argument contains a bitwise OR of zero or more of the following constants: > -.TP > -.B AT_EMPTY_PATH > -If > -.I path > -is an empty string, > -operate on the file referred to by > -.I dirfd > -(which may have been obtained using the > -.BR open (2) > -.B O_PATH > -flag). > -In this case, > -.I dirfd > -can refer to any type of file, > -not just a directory. > -.TP > -.B AT_SYMLINK_NOFOLLOW > -If > -.I path > -is a symbolic link, > -do not dereference it: > -instead set attributes on the symbolic link itself. > -By default (i.e., if this flag is not specified), > -symbolic links are dereferenced. > +arguments behaves in the same way as in > +.BR file_getattr (2). > +The only difference is that > +user-space applications should use > +.BR file_getattr (2) > +to initialize > +.I fattr > +argument beforehand. > .SH RETURN VALUE > On success, > zero is returned. > @@ -103,98 +48,22 @@ and > .I errno > is set to indicate the error. > .SH ERRORS > +.P > +The errors are the same as returned by > +.BR file_getattr (2) > +with the addition of following ones: > .TP > .B E2BIG > .I size > -is larger than > -.BR PAGE_SIZE . > -.TP > -.B E2BIG > -.I size > -indicates the version which kernel doesn't support (the size is larger than the > -kernel expects) and new fields are non-zero. > -.TP > -.B EACCES > -Search permission is denied for one of the directories > -in the path prefix of > -.IR path . > -(See also > -.BR path_resolution (7).) > -.TP > -.B EBADF > -.I path > -is relative but > -.I dirfd > -is neither > -.B AT_FDCWD > -nor a valid file descriptor. > -.TP > -.B EBADF > -.I path > -is an empty string, > -.B AT_EMPTY_PATH > -was specified in > -.IR flags , > -and > -.I dirfd > -is neither > -.B AT_FDCWD > -nor a valid file descriptor. > -.TP > -.B EFAULT > -.I path > -or > -.I fattr > -is an invalid pointer. > -.TP > -.B EINVAL > -Unknown flag specified in > -.IR flags . > -.TP > -.B EINVAL > -.I size > -is smaller than > -.BR FILE_ATTR_SIZE_VER0 . > +indicates a version which the kernel doesn't support > +(the size is larger than the kernel expects) > +and new fields are non-zero. > .TP > .B EINVAL > Invalid combination of parameters provided in > .I fattr > for this type of file or filesystem. > .TP > -.B ELOOP > -Too many symbolic links encountered while resolving > -.IR path . > -.TP > -.B ENAMETOOLONG > -.I path > -is too long. > -.TP > -.B ENOENT > -A component of > -.I path > -does not exist, > -or > -.I path > -is an empty string and > -.B AT_EMPTY_PATH > -was not specified in > -.IR flags . > -.TP > -.B ENOMEM > -Insufficient kernel memory was available. > -.TP > -.B ENOTDIR > -A component of the path prefix of > -.I path > -is not a directory, or > -.I path > -is relative and > -.I dirfd > -is a file descriptor referring to a file other than a directory. > -.TP > -.B EOPNOTSUPP > -The filesystem does not support setting attributes on this type of inode. > -.TP > .B EPERM > The caller does not have the necessary permissions > to change the file attributes. > @@ -203,10 +72,7 @@ to change the file attributes. > The file is on a read-only filesystem. > .SH HISTORY > .SS Linux 6.17 > -This system call is introduced as a more flexible alternative to the > -FS_IOC_FSSETXATTR > -.BR ioctl (2) > -which could work on any type of files. > +This system call is introduced. > .SH NOTES > This system call is designed to be extensible. > The > @@ -259,7 +125,7 @@ flag on a file. > int > main(int argc, char *argv[]) > { > - struct file_attr fa = { 0 }; > + struct file_attr fa; > int dfd; > long ret; > > diff --git a/man/man2type/file_attr.2type b/man/man2type/file_attr.2type > index fd426c19f5f0..221d97b5220d 100644 > --- a/man/man2type/file_attr.2type > +++ b/man/man2type/file_attr.2type > @@ -140,45 +140,9 @@ Setting unsupported flags may result in an > or > .B EOPNOTSUPP > error. > -.SH VERSIONS > -.SS Structure size > -The structure size is defined by > -.B FILE_ATTR_SIZE_VER* > -which is also a version of the structure being used. > -The > -.I size > -parameter passed to > -.BR file_getattr (2) > -and > -.BR file_setattr (2) > -indicates the version of > -.I struct file_attr\fP. > -.SS FILE_ATTR_SIZE_VER0 > -Size is 24 bytes. > .SH HISTORY > .SS Linux v6.17 > This structure is introduced. > -The > -.I struct file_attr > -provides similar functionality to > -.I struct fsxattr > -used by the > -.B FS_IOC_FSGETXATTR > -and > -.B FS_IOC_FSSETXATTR > -.BR ioctl (2) > -operations, > -but is designed to be extensible through the > -.I size > -parameter of the system calls. > -.P > -Extra fields may be appended to the structure in future kernel versions. > -The kernel will expect new fields to be zeros > -for older versions of the structure. > -Therefore, a user > -.I must > -zero-fill the structure on initialization to keep compatibility with older > -kernels. > .SS Linux v7.2 > The FS_XFLAG_CASEFOLD and FS_XFLAG_CASENONPRESERVING are introduced to enable > upper layers, such as NFSD, to retrieve case sensitivity information. > -- > 2.55.0 > >