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 24A933242D4; Sun, 11 Oct 2026 17:07:19 +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=1791738441; cv=none; b=uoTQgjxxbRwihvpH68Ob0mRmGIyl3O8PTKF7cbRj2f3Dq3vjsfxTCthI1Gu2v9ea3lJJ4q+1IgnXnm+XBT19B90ZoBQP7ZluwkiJdAtI45ttTruyMk1uzYb/4nYc67Nbz1AD4DQM/wpaavwYS8UmCS6KolJksXBHE+1wogTBXhY= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1791738441; c=relaxed/simple; bh=akQ3LOumTOoJfAr0OoNG8cHi5aQ7iU3rzvXRr2/27P4=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=jxtmjGwGMe/hDdClUzGS52xFRYrZPD9Jy72Zf1Oy1VZsaLpOQfcmLOTN+ayMmLFxqBDDm2CnVuBIlIfLCQwVAXQKqB/fdeHyovB98wuTINWTr7uFHtkPKmAXfznCeS2mJk4bHAaTG8NAu0aaiR+DXfMO5eaEchkOlPB35P3dOtI= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QPm0Wj4l; 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="QPm0Wj4l" Received: by smtp.kernel.org (Postfix) with ESMTPSA id 204421F0089B; Sun, 11 Oct 2026 17:07:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kernel.org; s=k20260515; t=1791738439; bh=FYEAkuu8Gnu4NuMGEmjWGq3BBa9JYM7W9tPRjEOBbY4=; h=Date:From:To:Cc:Subject:References:In-Reply-To; b=QPm0Wj4lfgMSM38ohHY4bnK6lsQuVkvKr0TA3RtrmV4iAuwWBXMTYcVUrm74o5G9F A2YiqdjvVdx/pXqJaYyN7PvrVWypRsy02pHOWjAOaifW9030y9h7kFO4qO0yMIlptK 530DzWCV32a79OCT+m4k9yrEyUH0Pg+MOZoIcv+9AQJ5jwSF7ZCHziLYkcrhuJFH/v 3Gh5DPbMn8A8Pj+FMPy+4dOOA/fIOFzoKU1OliKN7FqLRt6sCzzMtf5IMJW+sl23LV y7E/UaVgilEQnbPLDRABBd3d8lxCEZ6LbeVjboLQHh4Lo1v4XBJxw4p4Mmywmdjz5f w6rhQ/KlpEj1Q== Date: Sun, 11 Oct 2026 19:07:13 +0200 From: Alejandro Colomar To: "Darrick J. Wong" Cc: Andrey Albershteyn , 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: References: <20260914111107.1735564-1-aalbersh@kernel.org> <20260916115141.3500780-1-aalbersh@kernel.org> <20260921035125.GI2705364@frogsfrogsfrogs> Precedence: bulk X-Mailing-List: linux-api@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha512; protocol="application/pgp-signature"; boundary="qrgzbr6vzasssl62" Content-Disposition: inline In-Reply-To: <20260921035125.GI2705364@frogsfrogsfrogs> --qrgzbr6vzasssl62 Content-Type: text/plain; protected-headers=v1; charset=utf-8 Content-Disposition: inline Content-Transfer-Encoding: quoted-printable From: Alejandro Colomar To: "Darrick J. Wong" Cc: Andrey Albershteyn , 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: References: <20260914111107.1735564-1-aalbersh@kernel.org> <20260916115141.3500780-1-aalbersh@kernel.org> <20260921035125.GI2705364@frogsfrogsfrogs> MIME-Version: 1.0 In-Reply-To: <20260921035125.GI2705364@frogsfrogsfrogs> Hi Darrick, > Date: 2026-09-20 20:51:25-0700 > From: "Darrick J. Wong" > > 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. > >=20 > > Signed-off-by: Andrey Albershteyn > > Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc3= 5227b@kernel.org/ >=20 > Looks good to me still :) > Reviewed-by: "Darrick J. Wong" Thanks! I took your tag for v5, since it hasn't changed significantly. Have a lovely night! Alex >=20 > --D >=20 > >=20 > > --- > > 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 > >=20 > > 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 > >=20 > > 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 p= rocess. > > +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 consta= nts: > > +.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 ino= de. > > +.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 !=3D 2) { > > + fprintf(stderr, "Usage: %s \[rs]n", argv[0]); > > + exit(EXIT_FAILURE); > > + } > > + > > + ret =3D syscall(SYS_file_getattr, AT_FDCWD, argv[1], &fa, sizeof(f= a), 0); > > + if (ret =3D=3D \-1) { > > + perror("file_getattr"); > > + exit(EXIT_FAILURE); > > + } > > + > > + printf("File attributes:\[rs]n"); > > + printf(" xflags: 0x%llx\[rs]n", (unsigned long long) fa.fa_xf= lags); > > + 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 differe= nce > > + */ > > + 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_* " consta= nts */" > > +.BR "#include " " /* Definition of " FS_XFLAG_* " = constants */" > > +.BR "#include " " /* Definition of " SYS_* " const= ants */" > > +.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 !=3D 2) { > > + fprintf(stderr, "Usage: %s \[rs]n", argv[0]); > > + exit(EXIT_FAILURE); > > + } > > + > > + dfd =3D open(argv[1], O_RDONLY); > > + if (dfd =3D=3D \-1) { > > + perror("open"); > > + exit(EXIT_FAILURE); > > + } > > + > > + ret =3D syscall(SYS_file_getattr, dfd, "", &fa, sizeof(fa), AT_EMP= TY_PATH); > > + if (ret =3D=3D \-1) { > > + perror("file_getattr"); > > + exit(EXIT_FAILURE); > > + } > > + > > + printf("Current flags: 0x%llx\[rs]n", (unsigned long long) fa.fa_x= flags); > > + > > + fa.fa_xflags |=3D FS_XFLAG_NODUMP; > > + > > + ret =3D syscall(SYS_file_setattr, dfd, "", &fa, sizeof(fa), AT_EMP= TY_PATH); > > + if (ret =3D=3D \-1) { > > + perror("file_setattr"); > > + exit(EXIT_FAILURE); > > + } > > + > > + ret =3D syscall(SYS_file_getattr, dfd, "", &fa, sizeof(fa), AT_EMP= TY_PATH); > > + if (ret =3D=3D \-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 n= ame > > +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) > >=20 > > 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 calli= ng 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 cons= tants: > > @@ -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 i= node. > > .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 =3D { 0 }; > > + struct file_attr fa; > > long ret; > > =20 > > if (argc !=3D 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_* " cons= tants */" > > -.BR "#include " " /* Definition of " FILE_ATTR_*= \ > > -" and " FS_XFLAG_* " constants */" > > +.BR "#include " " /* Definition of " FS_XFLAG_* = " constants */" > > .BR "#include " " /* Definition of " SYS_* " con= stants */" > > .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 cons= tants: > > -.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 larg= er 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 i= node. > > -.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 =3D { 0 }; > > + struct file_attr fa; > > int dfd; > > long ret; > > =20 > > diff --git a/man/man2type/file_attr.2type b/man/man2type/file_attr.2t= ype > > 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 versi= ons. > > -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. > > --=20 > > 2.55.0 > >=20 > >=20 >=20 --=20 --qrgzbr6vzasssl62 Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCgAdFiEES7Jt9u9GbmlWADAi64mZXMKQwqkFAmrLwkEACgkQ64mZXMKQ wqlJJhAAg+Ho4sFM2/og1RZTdOcppeSWy6vA6gR9Aw51NtWL3UiG0rScnGwrudJV zvOfmWVvQogoeAND+A8eJBLjG61DaBPdRbtpSJF6sMGSF23bD0vQdVC3gyMeu1Vu YS4zC1bQLFOt7umoad/Z0OFDa6MpHw64qpNFtSbA5G8jgNmHwLSlVHqfTnQKTdKo 6/omd5pzVFI//rYTNpsNmjlbRNfMiT87zfAQ3xbGKNyQ9gcXrocGTbAXfuPMiSo9 oQnCzdjlajy0jo2w15UisopYuvnL+Q1zLOpCw7ylSEO3GP2LBgDPIUnFHBS2yNe2 G0U4OIWl4BY8vGEwGLAWcANK+aoupaK18EYNwDT3Z/xpr5+irtPZs9cHoXp9gbVR 1sXLbCmQNl47L8+ikhOzFD0gpgiIkRviUhJE0I+bwzzZ8glmG7J7qk8BTOTn8lh+ mciadUWxSqcD42gaFBBTqaNn/7BJgaXVTe9XdER25CgHb4taVEmQV6sD01/Vj1IX wfHFQI8x0Lf2M4BB1B9nMKhTTMgNfpWvFrPML+2qZaCNl4qXIGPuSbYLQd9Lrp80 rcKrHXHte1Iufh4uRuRhCW+rwA6+sIm2Akj5Cldv0KJfiItzuXcwWFLz900XCm1f j+g7GEyhQ5lRdIounFPEeS8VUhk1oegSdVuI1Og17jpvQ1Tz9LM= =hx5Q -----END PGP SIGNATURE----- --qrgzbr6vzasssl62--