* Re: [PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
@ 2026-09-21 3:51 ` Darrick J. Wong
2026-09-26 13:58 ` Alejandro Colomar
` (4 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Darrick J. Wong @ 2026-09-21 3:51 UTC (permalink / raw)
To: Andrey Albershteyn
Cc: Alejandro Colomar, linux-man, linux-api, linux-xfs, linux-fsdevel,
Christoph Hellwig
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
>
>
^ permalink raw reply [flat|nested] 10+ messages in thread* Re: [PATCH v4] man/man2: introduce man page for file_getattr/file_setattr syscalls
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
2026-09-21 3:51 ` Darrick J. Wong
@ 2026-09-26 13:58 ` Alejandro Colomar
2026-09-29 13:02 ` [PATCH v5 0/3] Introduce man pages for file_getattr() and file_setattr() Andrey Albershteyn
` (3 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Alejandro Colomar @ 2026-09-26 13:58 UTC (permalink / raw)
To: Andrey Albershteyn
Cc: linux-man, linux-api, linux-xfs, linux-fsdevel, Christoph Hellwig,
djwong
[-- 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 --]
^ permalink raw reply [flat|nested] 10+ messages in thread* [PATCH v5 0/3] Introduce man pages for file_getattr() and file_setattr()
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
2026-09-21 3:51 ` Darrick J. Wong
2026-09-26 13:58 ` Alejandro Colomar
@ 2026-09-29 13:02 ` Andrey Albershteyn
2026-09-29 13:02 ` [PATCH v5 1/3] man/man2: introduce man page for struct file_attr Andrey Albershteyn
` (2 subsequent siblings)
5 siblings, 0 replies; 10+ messages in thread
From: Andrey Albershteyn @ 2026-09-29 13:02 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Cc: Andrey Albershteyn, linux-api, linux-xfs, linux-fsdevel,
Christoph Hellwig, djwong
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
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH v5 1/3] man/man2: introduce man page for struct file_attr
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
` (2 preceding siblings ...)
2026-09-29 13:02 ` [PATCH v5 0/3] Introduce man pages for file_getattr() and file_setattr() Andrey Albershteyn
@ 2026-09-29 13:02 ` Andrey Albershteyn
2026-09-29 13:02 ` [PATCH v5 2/3] man/man2: introduce man page for file_getattr(2) syscall Andrey Albershteyn
2026-09-29 13:02 ` [PATCH v5 3/3] man/man2: introduce man page for file_setattr(2) syscall Andrey Albershteyn
5 siblings, 0 replies; 10+ messages in thread
From: Andrey Albershteyn @ 2026-09-29 13:02 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Cc: Andrey Albershteyn, linux-api, linux-xfs, linux-fsdevel,
Christoph Hellwig, djwong
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
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH v5 2/3] man/man2: introduce man page for file_getattr(2) syscall
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
` (3 preceding siblings ...)
2026-09-29 13:02 ` [PATCH v5 1/3] man/man2: introduce man page for struct file_attr Andrey Albershteyn
@ 2026-09-29 13:02 ` Andrey Albershteyn
2026-09-29 13:02 ` [PATCH v5 3/3] man/man2: introduce man page for file_setattr(2) syscall Andrey Albershteyn
5 siblings, 0 replies; 10+ messages in thread
From: Andrey Albershteyn @ 2026-09-29 13:02 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Cc: Andrey Albershteyn, linux-api, linux-xfs, linux-fsdevel,
Christoph Hellwig, djwong
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
^ permalink raw reply related [flat|nested] 10+ messages in thread* [PATCH v5 3/3] man/man2: introduce man page for file_setattr(2) syscall
2026-09-16 11:51 ` [PATCH v4] " Andrey Albershteyn
` (4 preceding siblings ...)
2026-09-29 13:02 ` [PATCH v5 2/3] man/man2: introduce man page for file_getattr(2) syscall Andrey Albershteyn
@ 2026-09-29 13:02 ` Andrey Albershteyn
5 siblings, 0 replies; 10+ messages in thread
From: Andrey Albershteyn @ 2026-09-29 13:02 UTC (permalink / raw)
To: Alejandro Colomar, linux-man
Cc: Andrey Albershteyn, linux-api, linux-xfs, linux-fsdevel,
Christoph Hellwig, djwong
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
^ permalink raw reply related [flat|nested] 10+ messages in thread