[PATCH v3] man/man2: introduce man page for file_getattr/file_setattr syscalls

[PATCH v3] man/man2: introduce man page for file_getattr/file_setattr syscalls

[Andrey Albershteyn]

Add manual pages for file_getattr() and file_setattr() syscalls and
struct file_attr used as input/output argument.

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/

---
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      | 262 +++++++++++++++++++++++++++++
 man/man2/file_setattr.2      | 314 +++++++++++++++++++++++++++++++++++
 man/man2type/file_attr.2type | 187 +++++++++++++++++++++
 3 files changed, 763 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..1168b23c5ce5
--- /dev/null
+++ b/man/man2/file_getattr.2
@@ -0,0 +1,262 @@
+.\" 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 inode attributes
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fcntl.h>" "      /* " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
+.B #include <unistd.h>
+.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
+from 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
+.IR dirfd .
+The special value
+.B AT_FDCWD
+could 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
+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:
+.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 as a more flexible alternative to the
+FS_IOC_FSGETXATTR
+.BR ioctl (2)
+which could work on any type of file.
+.SH NOTES
+This system call is designed to be extensible.
+The
+.I size
+argument allows userspace 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 <fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#ifndef SYS_file_getattr
+#define SYS_file_getattr 467
+#endif
+
+int
+main(int argc, char *argv[])
+{
+    struct file_attr fa = { 0 };
+    long ret;
+
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s <filename>\[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..2b30f25c64de
--- /dev/null
+++ b/man/man2/file_setattr.2
@@ -0,0 +1,314 @@
+.\" 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 inode attributes
+.SH SYNOPSIS
+.nf
+.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* Definition of " FILE_ATTR_* \
+" and " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.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.
+.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.
+.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
+.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.
+.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 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 .
+.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.
+.TP
+.B EROFS
+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.
+.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 <fcntl.h>
+#include <linux/fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#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 = { 0 };
+    int dfd;
+    long ret;
+
+    if (argc != 2) {
+        fprintf(stderr, "Usage: %s <filename>\[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..fd426c19f5f0
--- /dev/null
+++ b/man/man2type/file_attr.2type
@@ -0,0 +1,187 @@
+.\" 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 <linux/fs.h>
+.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 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.
+.SH SEE ALSO
+.BR file_getattr (2),
+.BR file_setattr (2)
-- 
2.55.0

Re: [PATCH v3] man/man2: introduce man page for file_getattr/file_setattr syscalls

[Alejandro Colomar]

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

Hi Andrey,

> Date: 2026-09-14 13:11:05+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> Add manual pages for file_getattr() and file_setattr() syscalls and
> struct file_attr used as input/output argument.
> 
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
> 
> ---
> Changes from v2:
> - a few grammar fixes
> - styling fixes
> - sashiko.dev fixes (wrong AT_FDCWD combined with AT_EMPTY_PATH
>   description, unused "dfd")

I'd appreciate if you didn't use sashiko for manual pages.
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/ai>

> - 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

It'd be very useful to see the range-diff too.
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/range-diff>

And it'd also be good to get the new versions of patches as replies to
the first mail in v1.  That would allow one to find the entire
discussion in one thread, with one subthread.
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/sendmail>

> ---
>  man/man2/file_getattr.2      | 262 +++++++++++++++++++++++++++++
>  man/man2/file_setattr.2      | 314 +++++++++++++++++++++++++++++++++++
>  man/man2type/file_attr.2type | 187 +++++++++++++++++++++
>  3 files changed, 763 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..1168b23c5ce5
> --- /dev/null
> +++ b/man/man2/file_getattr.2
> @@ -0,0 +1,262 @@
> +.\" 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 inode attributes
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/fcntl.h>" "      /* " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> +.B #include <unistd.h>
> +.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
> +from the file.

I liked '... specified by path.'.  This is for example what openat2(2)
says.

Alternatively, we could say 's/the file/the specified 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
> +.IR dirfd .
> +The special value
> +.B AT_FDCWD
> +could be used to refer to the current working directory of the calling process.

s/could/can/

Also, we didn't specify where to pass AT_FDCWD.  We should probably say
something like

	The special
	.I dirfd
	value
	.B 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.
> +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)

I missed this formatting typo:

	.BR file_attr (2type)

> +for more information on versioning.
> +.P
> +Userspace applications should zero-initialize

s/Userspace/User-space/

(reported in v2)

> +.I struct file_attr

For consistency with a few sentences above, let's say:

	... the
	.I file_attr
	structure
	...

Alternatively, 's/struct file_attr/fattr/'.

> +before calling
> +.BR file_getattr ()
> +to ensure that fields not filled in by older kernels
> +will have predictable values.

s/will have predictable values/are cleared/.

> +.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 as a more flexible alternative to the
> +FS_IOC_FSGETXATTR
> +.BR ioctl (2)
> +which could work on any type of file.
> +.SH NOTES
> +This system call is designed to be extensible.
> +The
> +.I size
> +argument allows userspace 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.

Hmmm, this seems to contradict the explanation from above.  I'll quote:

	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.

So, if old kernels zero any bytes between the (small) size supported by
the kernel and the (large) size used by the user, why would the user
need to zero them?  Isn't the kernel doing exactly that?

> +.SH EXAMPLES
> +The program below demonstrates the use of
> +.BR file_getattr ()
> +to retrieve and display file attributes.
> +.P
> +.in +4n
> +.EX
> +#include <fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +
> +#ifndef SYS_file_getattr
> +#define SYS_file_getattr 467
> +#endif
> +
> +int
> +main(int argc, char *argv[])
> +{
> +    struct file_attr fa = { 0 };
> +    long ret;
> +
> +    if (argc != 2) {
> +        fprintf(stderr, "Usage: %s <filename>\[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..2b30f25c64de
> --- /dev/null
> +++ b/man/man2/file_setattr.2
> @@ -0,0 +1,314 @@
> +.\" 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 inode attributes
> +.SH SYNOPSIS
> +.nf
> +.BR "#include <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* Definition of " FILE_ATTR_* \
> +" and " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
> +.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.
> +.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.

How about saying that the parameters 'dirfd', 'path', and 'flags' are
interpreted like in file_getattr(2), and we save some paragraphs?

We'd also save the user from checking whether there's a tiny detail that
differs, or if they are identical.

I have a long term plan of removing a lot of paragraphs in manual pages,
by saying that some syscalls or functions behave exactly like others, at
least for some parameters.

> +.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

s/struct fattr/fattr/

It's the name of the parameter, not the struct tag.

Or alternatively, say 'the file_attr structure'.

> +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)

.BR 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
> +.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.

The wording here should be consistent with the 'get' function, which
doesn't have the parenthetical (or, ideally, de-duplicated, by saying
'flags' is interpreted like in the 'get' function.

> +.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 larger than
> +.BR PAGE_SIZE .
> +.TP
> +.B E2BIG
> +.I size
> +indicates the version which kernel doesn't support (the size is larger than the

s/the version with/a version with the/

> +kernel expects) and new fields are non-zero.

Please break the lines before '(' and after ')'.

> +.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).)

The wording should be consistent with the 'get' function.

Alternatively, we could say this (if we've specified the parameters as
being interpreted as if the 'get' function):

	.TP
	.B EACCESS
	See
	.BR file_setattr (2).

And the same for other errors about path/dirfd/flags that are exactly
as in file_getattr(2).

> +.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 .
> +.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.
> +.TP
> +.B EROFS
> +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.

I think this paragraph could be removed, and only specified in the XFS
manual page.

> +.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 <fcntl.h>
> +#include <linux/fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +
> +#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 = { 0 };
> +    int dfd;
> +    long ret;
> +
> +    if (argc != 2) {
> +        fprintf(stderr, "Usage: %s <filename>\[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..fd426c19f5f0
> --- /dev/null
> +++ b/man/man2type/file_attr.2type
> @@ -0,0 +1,187 @@
> +.\" 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 <linux/fs.h>
> +.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 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.

Why do those macros exist?  I expect users should just use sizeof(),
right?  In fact, the example program doesn't show its use at all.
Should we remove that macro entirely?

> +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.

This implementation detail seems unnecessary for programmers.
'24' is something programmers shouldn't know, IMO.

> +.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.

I'd remove this paragraph.  Users of this API shouldn't need that info.
It's only users of the ioctl that need to be aware of these APIs, and
thus this belongs in the XPF manual pages but not here.

> +.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.


Have a lovely day!
Alex

> +.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)
> -- 
> 2.55.0
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH v3] man/man2: introduce man page for file_getattr/file_setattr syscalls

[Andrey Albershteyn]

Hi Alejandro,

On 2026-09-14 14:43:36, Alejandro Colomar wrote:
> Hi Andrey,
> 
> > Date: 2026-09-14 13:11:05+0200
> > From: Andrey Albershteyn <aalbersh@kernel.org>
> >
> > Add manual pages for file_getattr() and file_setattr() syscalls and
> > struct file_attr used as input/output argument.
> > 
> > Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> > Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
> > 
> > ---
> > Changes from v2:
> > - a few grammar fixes
> > - styling fixes
> > - sashiko.dev fixes (wrong AT_FDCWD combined with AT_EMPTY_PATH
> >   description, unused "dfd")
> 
> I'd appreciate if you didn't use sashiko for manual pages.
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/ai>
> 
> > - 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
> 
> It'd be very useful to see the range-diff too.
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/range-diff>
> 
> And it'd also be good to get the new versions of patches as replies to
> the first mail in v1.  That would allow one to find the entire
> discussion in one thread, with one subthread.
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING.d/patches/sendmail>

ok sure

[...]
> > +If
> > +.I size
> > +is larger than the kernel's structure size,
> > +the extra bytes are zeroed.
> 
> Hmmm, this seems to contradict the explanation from above.  I'll quote:
> 
> 	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.
> 
> So, if old kernels zero any bytes between the (small) size supported by
> the kernel and the (large) size used by the user, why would the user
> need to zero them?  Isn't the kernel doing exactly that?

that's right, I removed this in file_setattr() but probably
forgot to remove it here.

[...]
> > +.SH DESCRIPTION
> > +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.
> 
> How about saying that the parameters 'dirfd', 'path', and 'flags' are
> interpreted like in file_getattr(2), and we save some paragraphs?
> 
> We'd also save the user from checking whether there's a tiny detail that
> differs, or if they are identical.
> 
> I have a long term plan of removing a lot of paragraphs in manual pages,
> by saying that some syscalls or functions behave exactly like others, at
> least for some parameters.

Sounds good, I will reference file_getattr then

[...]
> > +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.
> 
> Why do those macros exist?  I expect users should just use sizeof(),
> right?  In fact, the example program doesn't show its use at all.
> Should we remove that macro entirely?

You're right, this is not necessary, the sizeof() is enough.

> 
> > +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.
> 
> This implementation detail seems unnecessary for programmers.
> '24' is something programmers shouldn't know, IMO.

Yes, I will remove mentions of FILE_ATTR_SIZE_VER0

-- 
- Andrey

[PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls

[Andrey Albershteyn]

Add manual pages for file_getattr() and file_setattr() syscalls and
struct file_attr used as input/output argument.

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/

---
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 <linux/fcntl.h>" "      /* " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
+.B #include <unistd.h>
+.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 <fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#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 <filename>\[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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.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 <fcntl.h>
+#include <linux/fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+#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 <filename>\[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 <linux/fs.h>
+.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 <linux/fcntl.h>" "      /* " 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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
  -.BR "#include <linux/fs.h>" "         /* Definition of " FILE_ATTR_* \
  -" and " FS_XFLAG_* " constants */"
  +.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
   .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
   .B #include <unistd.h>
   .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

Re: [PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls

[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.
> 
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/

Looks good to me still :)
Reviewed-by: "Darrick J. Wong" <djwong@kernel.org>

--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 <linux/fcntl.h>" "      /* " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> +.B #include <unistd.h>
> +.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 <fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +
> +#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 <filename>\[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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
> +.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 <fcntl.h>
> +#include <linux/fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +
> +#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 <filename>\[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 <linux/fs.h>
> +.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 <linux/fcntl.h>" "      /* " 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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
>   -.BR "#include <linux/fs.h>" "         /* Definition of " FILE_ATTR_* \
>   -" and " FS_XFLAG_* " constants */"
>   +.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
>    .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
>    .B #include <unistd.h>
>    .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
> 
> 

Re: [PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls

[Alejandro Colomar]

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

Hi Andrey,

> Date: 2026-09-16 13:51:39+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> Add manual pages for file_getattr() and file_setattr() syscalls and
> struct file_attr used as input/output argument.
> 
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
> 
> ---

Thanks!  It looks quite good.  I have another round of small comments.

> 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 +++++++++++++++++++++

I prefer 3 patches, eacch of which adds one manual page.  That will
make the 'Subject:' of the patch more explicit.

>  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 <linux/fcntl.h>" "      /* " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> +.B #include <unistd.h>
> +.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

+of the file

> +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

s/version/the &/

> +.B file_attr (2type)
> +for more information on versioning.

I would remove the reference to file_attr(2type) here entirely.  The
only thing the user needs to care at this point is that it's used as
a version.  The user will probably read file_attr(2type) for other
reasons, and will find the HISTORY section, but I think it's not
relevant enough at this point to add a sentence referring to it.

On the other hand, I think we should explicitly say that this should
always be specified as sizeof(struct file_attr).

	This size indicates the version of the structure in use,
	and should always be specified as
	.IR \%sizeof(struct\~file_attr) .

> +.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.

s/instead/&,\n/

> +By default, symbolic links are dereferenced.

I think we can get rid of this last sentence.  I seems obvious by the
fact that there's a flag for changing the behavior.

> +.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

s/flag/&s/

> +.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 .

These two are quite distinct errors, so I'd add two separate entries:

	.TP
	.B ENOENT
	A component of
	.I path
	does not exist.
	.TP
	.B ENOENT
	.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.

I'd also split these two, as they're quite distinct.

	.TP
	.B ENOTDIR
	A component of the path prefix of
	.I path
	is not a directory.
	.TP
	.B ENOTDIR
	.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.

We often just say this:

	.SH HISTORY
	Linux 6.17.

That's understood as the version in which it was added.

> +.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

Please wrap the program code with markers so that the build system can
actually build the program (and run linters on it).  Please look at
man2/membarrier.2 for an example of how it's done (it's just a comment
in the manual page's source code).

	$ grep -C2 SRC man2/membarrier.2
	.P
	.in +4n
	.\" SRC BEGIN (membarrier.c)
	.EX
	#include <stdlib.h>
	--
	}
	.EE
	.\" SRC END
	.in
	.P


> +#include <fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +

Blank lines should contain a "dummy" character (to avoid a diagnostic):

	...
	#include <unistd.h>
	\&
	#ifndef SYS_file_getattr
	...

> +#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 <filename>\[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);

We could use ISO C23's "%w64x" for printing a 64-bit integer.  That
avoids a cast.

> +    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);

Since these are u32, it might make more sense to print them with
"%w32u".

> +
> +    /*
> +     * 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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
> +.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
> +.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
> +.B #include <unistd.h>
> +.P
> +.B long syscall(SYS_file_setattr,
> +.BI "               int " dirfd ", const char *" path ,
> +.BI "               struct file_attr *" fattr ", size_t " size ,

I expect in the 'set' version, the 'fattr' argument will be read-only,
right?  Then it should be 'const'.

> +.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 ,

I expect 'fattr' will be read instead of written to.  That's an
important difference to be documented (if I'm assuming correctly).

> +.IR size ,
> +and
> +.I flags
> +arguments behaves in the same way as in

s/behaves/behave/

> +.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.

To simplify:

	.SH HISTORY
	Linux 6.17.

> +.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 <fcntl.h>
> +#include <linux/fcntl.h>
> +#include <linux/fs.h>
> +#include <stdio.h>
> +#include <stdlib.h>
> +#include <string.h>
> +#include <sys/syscall.h>
> +#include <unistd.h>
> +

\&

> +#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 <filename>\[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 <linux/fs.h>
> +.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.

Should we maybe have a reference to any quota pages (e.g., quotactl(2))
instead of just saying quota?

> +.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)


Have a lovely day!
Alex

> 
> 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 <linux/fcntl.h>" "      /* " 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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
>   -.BR "#include <linux/fs.h>" "         /* Definition of " FILE_ATTR_* \
>   -" and " FS_XFLAG_* " constants */"
>   +.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
>    .BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
>    .B #include <unistd.h>
>    .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
> 
> 

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[PATCH v5 0/3] Introduce man pages for file_getattr() and file_setattr()

[Andrey Albershteyn]

Hi folks,

This series introduce 3 man pages for file_getattr() and file_setattr()
syscalls and struct file_attr used as an argument for these syscalls.

Changes from v4:
- Split single patch into 3 separate ones
- Mark examples for linters
- Use special char for empty lines in examples
- Use w64/w32 in printf() in examples
- Use const fattr in file_setattr() definition
- Other minor fixes
- A few fixes found by lint in examples

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

Andrey Albershteyn (3):
  man/man2: introduce man page for struct file_attr
  man/man2: introduce man page for file_getattr(2) syscall
  man/man2: introduce man page for file_setattr(2) syscall

 man/man2/file_getattr.2      | 262 +++++++++++++++++++++++++++++++++++
 man/man2/file_setattr.2      | 183 ++++++++++++++++++++++++
 man/man2type/file_attr.2type | 153 ++++++++++++++++++++
 3 files changed, 598 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

Interdiff against v4:
diff --git a/man/man2/file_getattr.2 b/man/man2/file_getattr.2
index fe804d97976b..e3c86fc45711 100644
--- a/man/man2/file_getattr.2
+++ b/man/man2/file_getattr.2
@@ -21,6 +21,7 @@ file_getattr \- get filesystem file attributes
 The
 .BR file_getattr ()
 system call retrieves filesystem file attributes
+of the file
 specified by path.
 .P
 As with
@@ -56,9 +57,9 @@ 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.
+The size indicates the version of the structure in use,
+and should always be specified as
+.IR sizeof(struct file_attr) .
 .P
 The
 .I flags
@@ -80,8 +81,8 @@ 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.
+instead,
+get attributes of the symbolic link inode itself.
 .SH RETURN VALUE
 On success,
 zero is returned.
@@ -128,7 +129,7 @@ or
 is an invalid pointer.
 .TP
 .B EINVAL
-Unknown flag specified in
+Unknown flags specified in
 .IR flags .
 .TP
 .B EINVAL
@@ -147,8 +148,9 @@ is too long.
 .B ENOENT
 A component of
 .I path
-does not exist,
-or
+does not exist.
+.TP
+.B ENOENT
 .I path
 is an empty string and
 .B AT_EMPTY_PATH
@@ -161,7 +163,9 @@ Insufficient kernel memory was available.
 .B ENOTDIR
 A component of the path prefix of
 .I path
-is not a directory, or
+is not a directory.
+.TP
+.B ENOTDIR
 .I path
 is relative and
 .I dirfd
@@ -170,8 +174,7 @@ is a file descriptor referring to a file other than a directory.
 .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.
+Linux 6.17
 .SH NOTES
 This system call is designed to be extensible.
 The
@@ -199,51 +202,56 @@ The program below demonstrates the use of
 to retrieve and display file attributes.
 .P
 .in +4n
+.\" SRC BEGIN (file_getattr.c)
 .EX
+#define _GNU_SOURCE
 #include <fcntl.h>
 #include <linux/fs.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <sys/syscall.h>
 #include <unistd.h>
-
+\&
 #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 <filename>\[rs]n", argv[0]);
         exit(EXIT_FAILURE);
     }
-
-    ret = syscall(SYS_file_getattr, AT_FDCWD, argv[1], &fa, sizeof(fa), 0);
+\&
+    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);
-
+    printf("  xflags:     0x%w64x\[rs]n", fa.fa_xflags);
+    printf("  extsize:    %w32u\[rs]n", fa.fa_extsize);
+    printf("  nextents:   %w32u\[rs]n", fa.fa_nextents);
+    printf("  projid:     %w32u\[rs]n", fa.fa_projid);
+    printf("  cowextsize: %w32u\[rs]n", fa.fa_cowextsize);
+\&
     /*
-     * Try setting NODUMP flag with chattr +d ./foo to see the difference
+     * 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
+.\" SRC END
 .in
 .SH SEE ALSO
 .BR file_setattr (2),
diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2
index 0389f42afb50..b11c9ff9277f 100644
--- a/man/man2/file_setattr.2
+++ b/man/man2/file_setattr.2
@@ -14,10 +14,9 @@ file_setattr \- set filesystem file attributes
 .P
 .B long syscall(SYS_file_setattr,
 .BI "               int " dirfd ", const char *" path ,
-.BI "               struct file_attr *" fattr ", size_t " size ,
+.BI "               const struct file_attr *" fattr ", size_t " size ,
 .BI "               unsigned int " flags );
 .fi
-.P
 .SH DESCRIPTION
 The
 .BR file_setattr ()
@@ -27,14 +26,16 @@ on the file specified by path.
 The
 .IR dirfd ,
 .IR path ,
-.IR fattr ,
 .IR size ,
 and
 .I flags
-arguments behaves in the same way as in
+arguments behave in the same way as in
 .BR file_getattr (2).
-The only difference is that
-user-space applications should use
+The
+.IR fattr ,
+is read-only argument with
+file attributes to set.
+User-space applications should use
 .BR file_getattr (2)
 to initialize
 .I fattr
@@ -48,7 +49,6 @@ 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:
@@ -71,8 +71,7 @@ to change the file attributes.
 .B EROFS
 The file is on a read-only filesystem.
 .SH HISTORY
-.SS Linux 6.17
-This system call is introduced.
+Linux 6.17
 .SH NOTES
 This system call is designed to be extensible.
 The
@@ -104,71 +103,75 @@ to set the
 flag on a file.
 .P
 .in +4n
+.\" SRC BEGIN (file_setattr.c)
 .EX
+#define _GNU_SOURCE
 #include <fcntl.h>
-#include <linux/fcntl.h>
 #include <linux/fs.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
 #include <sys/syscall.h>
 #include <unistd.h>
-
+\&
 #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 <filename>\[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);
+\&
+    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);
-
+\&
+    printf("Current flags: 0x%w64x\[rs]n", fa.fa_xflags);
+\&
     fa.fa_xflags |= FS_XFLAG_NODUMP;
-
-    ret = syscall(SYS_file_setattr, dfd, "", &fa, sizeof(fa), AT_EMPTY_PATH);
+\&
+    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);
+\&
+    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);
-
+        printf("flags 0x%w64x (NODUMP flag is set)\[rs]n", fa.fa_xflags);
+\&
     exit(EXIT_SUCCESS);
 }
 .EE
+.\" SRC END
 .in
 .SH SEE ALSO
 .BR file_getattr (2),
diff --git a/man/man2type/file_attr.2type b/man/man2type/file_attr.2type
index 221d97b5220d..3a1aabbc9e7d 100644
--- a/man/man2type/file_attr.2type
+++ b/man/man2type/file_attr.2type
@@ -50,7 +50,9 @@ and is ignored by
 .TP
 .I fa_projid
 Project identifier.
-Used by quota systems to group related files.
+Used by quota systems
+.BR quotactl (2)
+to group related files.
 .TP
 .I fa_cowextsize
 Copy-on-Write (CoW) extent size hint in bytes.
-- 
2.55.0

[PATCH v5 1/3] man/man2: introduce man page for struct file_attr

[Andrey Albershteyn]

Add manual pages for struct file_attr used by file_getattr() and
file_setattr() syscalls.

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
---
 man/man2type/file_attr.2type | 153 +++++++++++++++++++++++++++++++++++
 1 file changed, 153 insertions(+)
 create mode 100644 man/man2type/file_attr.2type

diff --git a/man/man2type/file_attr.2type b/man/man2type/file_attr.2type
new file mode 100644
index 000000000000..3a1aabbc9e7d
--- /dev/null
+++ b/man/man2type/file_attr.2type
@@ -0,0 +1,153 @@
+.\" 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 <linux/fs.h>
+.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
+.BR quotactl (2)
+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)
-- 
2.55.0

[PATCH v5 2/3] man/man2: introduce man page for file_getattr(2) syscall

[Andrey Albershteyn]

Add manual page for file_getattr().

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
---
 man/man2/file_getattr.2 | 262 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 262 insertions(+)
 create mode 100644 man/man2/file_getattr.2

diff --git a/man/man2/file_getattr.2 b/man/man2/file_getattr.2
new file mode 100644
index 000000000000..e3c86fc45711
--- /dev/null
+++ b/man/man2/file_getattr.2
@@ -0,0 +1,262 @@
+.\" 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 <linux/fcntl.h>" "      /* " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
+.B #include <unistd.h>
+.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
+of the file
+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 the version of the structure in use,
+and should always be specified as
+.IR sizeof(struct file_attr) .
+.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.
+.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 flags 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.
+.TP
+.B ENOENT
+.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.
+.TP
+.B ENOTDIR
+.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
+Linux 6.17
+.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
+.\" SRC BEGIN (file_getattr.c)
+.EX
+#define _GNU_SOURCE
+#include <fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+\&
+#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 <filename>\[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%w64x\[rs]n", fa.fa_xflags);
+    printf("  extsize:    %w32u\[rs]n", fa.fa_extsize);
+    printf("  nextents:   %w32u\[rs]n", fa.fa_nextents);
+    printf("  projid:     %w32u\[rs]n", fa.fa_projid);
+    printf("  cowextsize: %w32u\[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
+.\" SRC END
+.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)
-- 
2.55.0

[PATCH v5 3/3] man/man2: introduce man page for file_setattr(2) syscall

[Andrey Albershteyn]

Add manual pages for file_setattr() syscall.

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
---
 man/man2/file_setattr.2 | 183 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 183 insertions(+)
 create mode 100644 man/man2/file_setattr.2

diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2
new file mode 100644
index 000000000000..b11c9ff9277f
--- /dev/null
+++ b/man/man2/file_setattr.2
@@ -0,0 +1,183 @@
+.\" 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 <linux/fcntl.h>" "      /* Definition of " AT_* " constants */"
+.BR "#include <linux/fs.h>" "         /* Definition of " FS_XFLAG_* " constants */"
+.BR "#include <sys/syscall.h>" "      /* Definition of " SYS_* " constants */"
+.B #include <unistd.h>
+.P
+.B long syscall(SYS_file_setattr,
+.BI "               int " dirfd ", const char *" path ,
+.BI "               const struct file_attr *" fattr ", size_t " size ,
+.BI "               unsigned int " flags );
+.fi
+.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 size ,
+and
+.I flags
+arguments behave in the same way as in
+.BR file_getattr (2).
+The
+.IR fattr ,
+is read-only argument with
+file attributes to set.
+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
+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
+Linux 6.17
+.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
+.\" SRC BEGIN (file_setattr.c)
+.EX
+#define _GNU_SOURCE
+#include <fcntl.h>
+#include <linux/fs.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+\&
+#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 <filename>\[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%w64x\[rs]n", 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%w64x (NODUMP flag is set)\[rs]n", fa.fa_xflags);
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.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)
-- 
2.55.0