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

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

[Alejandro Colomar]

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

Hi Andrey,

> Date: 2026-09-10 12:41:18+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/
> 
> ---
> v2: a few grammar fixes, sashiko.dev fixes (wrong AT_FDCWD combined with
> AT_EMPTY_PATH description, unused "dfd") and dropped requirement to zero
> fattr before using file_setattr().
> ---
>  man/man2/file_getattr.2      | 279 +++++++++++++++++++++++++++++
>  man/man2/file_setattr.2      | 333 +++++++++++++++++++++++++++++++++++
>  man/man2type/file_attr.2type | 187 ++++++++++++++++++++
>  3 files changed, 799 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..2d9a6d338a5e
> --- /dev/null
> +++ b/man/man2/file_getattr.2
> @@ -0,0 +1,279 @@
> +.\" 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>" "         /* struct " file_attr " and " FS_XFLAG_* " constants */"

Most of the time, we don't document in these comments where types come
from.  They are already documented in the man2type manual page for the
type, so this is a bit redundant.  We limit these comments to constants.

(In a few cases, we document the types too, but those are mistakes that
 we should fix.)

> +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> +.B #include <unistd.h>
> +.P
> +.B long syscall(SYS_file_getattr,
> +.BI "               int " dirfd ", const char *" pathname ,

We now use 'path' quite consistently for these parameter names.
See this commit:

	commit a239bc4520d6cb8b4d217510c22eddd7c3fd5d10
	Author: Alejandro Colomar <alx@kernel.org>
	Date:   2025-01-15 20:41:01 +0100

	    man/: Consistently use 'path' for parameters referring to pathnames
	    
	    And use 'pathname' in the descriptions.
	    
	    'pathname' is the POSIXly correct term, and 'path' is a reasonable
	    abbreviation for it in parameter names.
	    
	    Cc: "G. Branden Robinson" <branden@debian.org>
	    Signed-off-by: Alejandro Colomar <alx@kernel.org>

	diff --git a/man/man2/acct.2 b/man/man2/acct.2
	index d2d1be1c4fc6..fe3606c17752 100644
	--- a/man/man2/acct.2
	+++ b/man/man2/acct.2
	@@ -12,7 +12,7 @@ .SH SYNOPSIS
	 .nf
	 .B #include <unistd.h>
	 .P
	-.BI "int acct(const char *_Nullable " filename );
	+.BI "int acct(const char *_Nullable " path );
	 .fi
	 .P
	 .RS -4
	@@ -34,10 +34,10 @@ .SH DESCRIPTION
	 The
	 .BR acct ()
	 system call enables or disables process accounting.
	-If called with the name of an existing file as its argument,
	+If called with the pathname of an existing file as its argument,
	 accounting is turned on,
	-and records for each terminating process are appended to
	-.I filename
	+and records for each terminating process
	+are appended to the file
	 as it terminates.
	 An argument of NULL causes accounting to be turned off.
	 .SH RETURN VALUE
	...

> +.BI "               struct file_attr *" fattr ", size_t " size ,
> +.BI "               unsigned int " flags );
> +.fi
> +.P
> +.IR Note :
> +glibc provides no wrapper for
> +.BR file_getattr (),
> +use
> +.BR syscall (2)
> +instead.

I've been trying to remove this sentence from manual pages.  This note
was originally introduced when manual pages used syntax as if the
wrapper existed, but some years ago we started using syscall()
explicitly, which already clrearly notices this, so this is superfluous.
Let's not add more.  (I'll remove the existing ones eventually.)

> +.SH DESCRIPTION
> +The
> +.BR file_getattr ()
> +system call retrieves filesystem file attributes
> +from the file specified by
> +.IR pathname .
> +.P
> +This system call provides functionality similar to the
> +.B FS_IOC_FSGETXATTR
> +.BR ioctl (2)
> +operation,

Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
manual page?

> +but with the advantage that the file does not need to be opened.
> +By using a pathname,
> +.BR file_getattr ()
> +can retrieve filesystem file attributes
> +from all file types,
> +including special files such as FIFOs, sockets, block devices, character
> +devices, and symlinks, where opening the targeted inode may not be possible.

This seems to be a limitation of FS_IOC_FSGETXATTR(2const), and would be
more appropriately documented in that page (if we add it).  There, I'd
document it in CAVEATS.  Then, file_getattr(2) wouldn't need to mention
this at all, because it's not an issue here.

> +.P
> +As with
> +.BR openat (2),
> +if
> +.I pathname
> +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 pathname
> +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) .

The '(2const)' part shouldn't be in bold.  Thus:

	.BR file_attr (2type).

> +.P
> +The
> +.I size
> +argument specifies the size of the buffer pointed to by
> +.IR fattr .

I'd do: s/buffer/structure/

We say 'size of the buffer' to refer to arrays (and say length,
to not confuse it with the size in bytes).

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

s/Userspace/User-space/

> +.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 is a bit mask, available flags are:

The usual language we use for this is:

	The
	.I flags
	argument contains
	a bitwise OR of zero or more of the following constants:

See for example readv(2).

There are some minor variations of this in other pages, and I should
make them more uniform.

> +.TP
> +.B AT_EMPTY_PATH
> +If
> +.I pathname
> +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 pathname
> +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 pathname .
> +.TP
> +.B EBADF
> +.I pathname
> +is relative but
> +.I dirfd
> +is neither
> +.B AT_FDCWD
> +nor a valid file descriptor.
> +.TP
> +.B EBADF
> +.I pathname
> +is an empty string,
> +.B AT_EMPTY_PATH
> +was specified,
> +but
> +.I dirfd
> +is an invalid file descriptor.

I was wondering: is it valid to specify AT_EMPTY_PATH, use an empty
string, and use AT_FDCWD as the dirfd?  That should act on the current
working directory itself, right?  Or is that not supported?

> +.TP
> +.B EFAULT
> +.I pathname
> +or
> +.I fattr
> +is an invalid pointer.
> +.TP
> +.B EINVAL
> +Invalid flag specified in

s/Invalid/Unknown/

You may have specified a valid flag, but the kernel is old and doesn't
yet know it.

> +.IR flags .
> +.TP
> +.B EINVAL
> +.I size
> +is smaller than
> +.BR FILE_ATTR_SIZE_VER0 .

perf_event_open(2) reports E2BIG for a size smaller than
PERF_ATTR_SIZE_VER0.  This seems unnecessarily inconsistent.  I'm not
sure which I'd say is more appropriate, but I'd expect them to be
consistent.  I mentioned perf_event_open(2) because that's the only page
that has a *_VER0 constant and documents an error if a size is smaller
than it.  There's also mount_setattr(2) which documents
MOUNT_ATTR_SIZE_VER0, but it's not documented in ERRORS.

I think kernel maintainers should have a look at the different APIs that
have such a value, and discuss whether the error codes should be made
uniform retroactively, or whether we should accept the existing
divergence but decide on an error code for new APIs.

I've CCed linux-api@.

> +.TP
> +.B ELOOP
> +Too many symbolic links encountered while resolving
> +.IR pathname .
> +.TP
> +.B ENAMETOOLONG
> +.I pathname
> +is too long.
> +.TP
> +.B ENOENT
> +A component of
> +.I pathname
> +does not exist,
> +or
> +.I pathname
> +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 pathname
> +is not a directory or,

s/or ,/, or/

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

I'd move NOTES to a VERSIONS section (which should go above HISTORY).
I know the existing pages are a bit inconsistent with this, but I'm
trying to minimize use of NOTES, which doesn't say much about its
contents.

> +.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>\\n", argv[0]);

The backslash should be specified as \[rs] (rs means reverse solidus).
Thus:

	... <filename> \[rs]n", ...

> +        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:\\n");
> +    printf("  xflags:     0x%llx\\n", (unsigned long long)fa.fa_xflags);

Please use a space after a cast:  (type) val

See:
	$ cat CONTRIBUTING.d/style/c | sed -n /Spaces/,+7p
	    Spaces
		Treat sizeof() and similar operators as functions, not keywords.
		Use a space after keywords, but not after functions.

		Use a space to separate binary and ternary operators (except
		`.` and `->`), but not to separate unary operators.

		Use a space between a cast and the expression it converts.

> +    printf("  extsize:    %u\\n", fa.fa_extsize);
> +    printf("  nextents:   %u\\n", fa.fa_nextents);
> +    printf("  projid:     %u\\n", fa.fa_projid);
> +    printf("  cowextsize: %u\\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\\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)
> diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2

I'll have a look at the other pages some other time.  I'm going to have
lunch.  :)


Have a lovely day!
Alex

> new file mode 100644
> index 000000000000..c340bdcab065
> --- /dev/null
> +++ b/man/man2/file_setattr.2
> @@ -0,0 +1,333 @@
> +.\" 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 *" pathname ,
> +.BI "               struct file_attr *" fattr ", size_t " size ,
> +.BI "               unsigned int " flags );
> +.fi
> +.P
> +.IR Note :
> +glibc provides no wrapper for
> +.BR file_setattr (),
> +necessitating the use of
> +.BR syscall (2).
> +.SH DESCRIPTION
> +The
> +.BR file_setattr ()
> +system call sets filesystem inode attributes
> +on the file specified by
> +.IR pathname .
> +.P
> +This system call provides functionality similar to the
> +.B FS_IOC_FSSETXATTR
> +.BR ioctl (2)
> +operation,
> +but with the advantage that the file does not need to be opened.
> +By using a pathname instead of requiring an open file descriptor,
> +.BR file_setattr ()
> +can manipulate filesystem inode attributes
> +on all file types,
> +including special files (FIFOs, sockets, block devices, character devices)
> +where opening the file may have side effects or may not be possible.
> +With
> +.BR ioctl (2),
> +it is not always possible to obtain a file descriptor that refers
> +directly to the filesystem inode for special files.
> +.P
> +As with
> +.BR openat (2),
> +if
> +.I pathname
> +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 pathname
> +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).
> +User-space applications should use
> +.B file_getattr(2)
> +to initialize
> +.I struct fattr
> +beforehand.
> +.P
> +The
> +.I size
> +argument specifies the size of the buffer 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 is a bit mask that can include zero or more of the following values:
> +.TP
> +.B AT_EMPTY_PATH
> +If
> +.I pathname
> +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 pathname
> +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 pathname .
> +(See also
> +.BR path_resolution (7).)
> +.TP
> +.B EBADF
> +.I pathname
> +is relative but
> +.I dirfd
> +is neither
> +.B AT_FDCWD
> +nor a valid file descriptor.
> +.TP
> +.B EBADF
> +.I pathname
> +is an empty string,
> +.B AT_EMPTY_PATH
> +was specified in
> +.IR flags ,
> +and
> +.I dirfd
> +is an invalid file descriptor.
> +.TP
> +.B EFAULT
> +.I pathname
> +or
> +.I fattr
> +is an invalid pointer.
> +.TP
> +.B EINVAL
> +Invalid 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 pathname .
> +.TP
> +.B ENAMETOOLONG
> +.I pathname
> +is too long.
> +.TP
> +.B ENOENT
> +A component of
> +.I pathname
> +does not exist,
> +or
> +.I pathname
> +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 pathname
> +is not a directory or,
> +.I pathname
> +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>\\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\\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)\\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)
> 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
> 
> 

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

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

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

[Darrick J. Wong]

On Thu, Sep 10, 2026 at 03:20:25PM +0200, Alejandro Colomar wrote:
> Hi Andrey,
> 
> > Date: 2026-09-10 12:41:18+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/
> > 
> > ---
> > v2: a few grammar fixes, sashiko.dev fixes (wrong AT_FDCWD combined with
> > AT_EMPTY_PATH description, unused "dfd") and dropped requirement to zero
> > fattr before using file_setattr().
> > ---
> >  man/man2/file_getattr.2      | 279 +++++++++++++++++++++++++++++
> >  man/man2/file_setattr.2      | 333 +++++++++++++++++++++++++++++++++++
> >  man/man2type/file_attr.2type | 187 ++++++++++++++++++++
> >  3 files changed, 799 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..2d9a6d338a5e
> > --- /dev/null
> > +++ b/man/man2/file_getattr.2
> > @@ -0,0 +1,279 @@
> > +.\" 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>" "         /* struct " file_attr " and " FS_XFLAG_* " constants */"
> 
> Most of the time, we don't document in these comments where types come
> from.  They are already documented in the man2type manual page for the
> type, so this is a bit redundant.  We limit these comments to constants.
> 
> (In a few cases, we document the types too, but those are mistakes that
>  we should fix.)
> 
> > +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> > +.B #include <unistd.h>
> > +.P
> > +.B long syscall(SYS_file_getattr,
> > +.BI "               int " dirfd ", const char *" pathname ,
> 
> We now use 'path' quite consistently for these parameter names.
> See this commit:
> 
> 	commit a239bc4520d6cb8b4d217510c22eddd7c3fd5d10
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   2025-01-15 20:41:01 +0100
> 
> 	    man/: Consistently use 'path' for parameters referring to pathnames
> 	    
> 	    And use 'pathname' in the descriptions.
> 	    
> 	    'pathname' is the POSIXly correct term, and 'path' is a reasonable
> 	    abbreviation for it in parameter names.
> 	    
> 	    Cc: "G. Branden Robinson" <branden@debian.org>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> 	diff --git a/man/man2/acct.2 b/man/man2/acct.2
> 	index d2d1be1c4fc6..fe3606c17752 100644
> 	--- a/man/man2/acct.2
> 	+++ b/man/man2/acct.2
> 	@@ -12,7 +12,7 @@ .SH SYNOPSIS
> 	 .nf
> 	 .B #include <unistd.h>
> 	 .P
> 	-.BI "int acct(const char *_Nullable " filename );
> 	+.BI "int acct(const char *_Nullable " path );
> 	 .fi
> 	 .P
> 	 .RS -4
> 	@@ -34,10 +34,10 @@ .SH DESCRIPTION
> 	 The
> 	 .BR acct ()
> 	 system call enables or disables process accounting.
> 	-If called with the name of an existing file as its argument,
> 	+If called with the pathname of an existing file as its argument,
> 	 accounting is turned on,
> 	-and records for each terminating process are appended to
> 	-.I filename
> 	+and records for each terminating process
> 	+are appended to the file
> 	 as it terminates.
> 	 An argument of NULL causes accounting to be turned off.
> 	 .SH RETURN VALUE
> 	...
> 
> > +.BI "               struct file_attr *" fattr ", size_t " size ,
> > +.BI "               unsigned int " flags );
> > +.fi
> > +.P
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR file_getattr (),
> > +use
> > +.BR syscall (2)
> > +instead.
> 
> I've been trying to remove this sentence from manual pages.  This note
> was originally introduced when manual pages used syntax as if the
> wrapper existed, but some years ago we started using syscall()
> explicitly, which already clrearly notices this, so this is superfluous.
> Let's not add more.  (I'll remove the existing ones eventually.)
> 
> > +.SH DESCRIPTION
> > +The
> > +.BR file_getattr ()
> > +system call retrieves filesystem file attributes
> > +from the file specified by
> > +.IR pathname .
> > +.P
> > +This system call provides functionality similar to the
> > +.B FS_IOC_FSGETXATTR
> > +.BR ioctl (2)
> > +operation,
> 
> Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
> manual page?

https://www.man7.org/linux/man-pages/man2/ioctl_xfs_fssetxattr.2.html

> > +but with the advantage that the file does not need to be opened.
> > +By using a pathname,
> > +.BR file_getattr ()
> > +can retrieve filesystem file attributes
> > +from all file types,
> > +including special files such as FIFOs, sockets, block devices, character
> > +devices, and symlinks, where opening the targeted inode may not be possible.
> 
> This seems to be a limitation of FS_IOC_FSGETXATTR(2const), and would be
> more appropriately documented in that page (if we add it).  There, I'd
> document it in CAVEATS.  Then, file_getattr(2) wouldn't need to mention
> this at all, because it's not an issue here.

Agreed, that belongs in ioctl_xfs_fssetxattr.2, not here.

--D

> > +.P
> > +As with
> > +.BR openat (2),
> > +if
> > +.I pathname
> > +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 pathname
> > +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) .
> 
> The '(2const)' part shouldn't be in bold.  Thus:
> 
> 	.BR file_attr (2type).
> 
> > +.P
> > +The
> > +.I size
> > +argument specifies the size of the buffer pointed to by
> > +.IR fattr .
> 
> I'd do: s/buffer/structure/
> 
> We say 'size of the buffer' to refer to arrays (and say length,
> to not confuse it with the size in bytes).
> 
> > +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
> 
> s/Userspace/User-space/
> 
> > +.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 is a bit mask, available flags are:
> 
> The usual language we use for this is:
> 
> 	The
> 	.I flags
> 	argument contains
> 	a bitwise OR of zero or more of the following constants:
> 
> See for example readv(2).
> 
> There are some minor variations of this in other pages, and I should
> make them more uniform.
> 
> > +.TP
> > +.B AT_EMPTY_PATH
> > +If
> > +.I pathname
> > +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 pathname
> > +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 pathname .
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is relative but
> > +.I dirfd
> > +is neither
> > +.B AT_FDCWD
> > +nor a valid file descriptor.
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is an empty string,
> > +.B AT_EMPTY_PATH
> > +was specified,
> > +but
> > +.I dirfd
> > +is an invalid file descriptor.
> 
> I was wondering: is it valid to specify AT_EMPTY_PATH, use an empty
> string, and use AT_FDCWD as the dirfd?  That should act on the current
> working directory itself, right?  Or is that not supported?
> 
> > +.TP
> > +.B EFAULT
> > +.I pathname
> > +or
> > +.I fattr
> > +is an invalid pointer.
> > +.TP
> > +.B EINVAL
> > +Invalid flag specified in
> 
> s/Invalid/Unknown/
> 
> You may have specified a valid flag, but the kernel is old and doesn't
> yet know it.
> 
> > +.IR flags .
> > +.TP
> > +.B EINVAL
> > +.I size
> > +is smaller than
> > +.BR FILE_ATTR_SIZE_VER0 .
> 
> perf_event_open(2) reports E2BIG for a size smaller than
> PERF_ATTR_SIZE_VER0.  This seems unnecessarily inconsistent.  I'm not
> sure which I'd say is more appropriate, but I'd expect them to be
> consistent.  I mentioned perf_event_open(2) because that's the only page
> that has a *_VER0 constant and documents an error if a size is smaller
> than it.  There's also mount_setattr(2) which documents
> MOUNT_ATTR_SIZE_VER0, but it's not documented in ERRORS.
> 
> I think kernel maintainers should have a look at the different APIs that
> have such a value, and discuss whether the error codes should be made
> uniform retroactively, or whether we should accept the existing
> divergence but decide on an error code for new APIs.
> 
> I've CCed linux-api@.
> 
> > +.TP
> > +.B ELOOP
> > +Too many symbolic links encountered while resolving
> > +.IR pathname .
> > +.TP
> > +.B ENAMETOOLONG
> > +.I pathname
> > +is too long.
> > +.TP
> > +.B ENOENT
> > +A component of
> > +.I pathname
> > +does not exist,
> > +or
> > +.I pathname
> > +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 pathname
> > +is not a directory or,
> 
> s/or ,/, or/
> 
> > +.I pathname
> > +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.
> 
> I'd move NOTES to a VERSIONS section (which should go above HISTORY).
> I know the existing pages are a bit inconsistent with this, but I'm
> trying to minimize use of NOTES, which doesn't say much about its
> contents.
> 
> > +.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>\\n", argv[0]);
> 
> The backslash should be specified as \[rs] (rs means reverse solidus).
> Thus:
> 
> 	... <filename> \[rs]n", ...
> 
> > +        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:\\n");
> > +    printf("  xflags:     0x%llx\\n", (unsigned long long)fa.fa_xflags);
> 
> Please use a space after a cast:  (type) val
> 
> See:
> 	$ cat CONTRIBUTING.d/style/c | sed -n /Spaces/,+7p
> 	    Spaces
> 		Treat sizeof() and similar operators as functions, not keywords.
> 		Use a space after keywords, but not after functions.
> 
> 		Use a space to separate binary and ternary operators (except
> 		`.` and `->`), but not to separate unary operators.
> 
> 		Use a space between a cast and the expression it converts.
> 
> > +    printf("  extsize:    %u\\n", fa.fa_extsize);
> > +    printf("  nextents:   %u\\n", fa.fa_nextents);
> > +    printf("  projid:     %u\\n", fa.fa_projid);
> > +    printf("  cowextsize: %u\\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\\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)
> > diff --git a/man/man2/file_setattr.2 b/man/man2/file_setattr.2
> 
> I'll have a look at the other pages some other time.  I'm going to have
> lunch.  :)
> 
> 
> Have a lovely day!
> Alex
> 
> > new file mode 100644
> > index 000000000000..c340bdcab065
> > --- /dev/null
> > +++ b/man/man2/file_setattr.2
> > @@ -0,0 +1,333 @@
> > +.\" 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 *" pathname ,
> > +.BI "               struct file_attr *" fattr ", size_t " size ,
> > +.BI "               unsigned int " flags );
> > +.fi
> > +.P
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR file_setattr (),
> > +necessitating the use of
> > +.BR syscall (2).
> > +.SH DESCRIPTION
> > +The
> > +.BR file_setattr ()
> > +system call sets filesystem inode attributes
> > +on the file specified by
> > +.IR pathname .
> > +.P
> > +This system call provides functionality similar to the
> > +.B FS_IOC_FSSETXATTR
> > +.BR ioctl (2)
> > +operation,
> > +but with the advantage that the file does not need to be opened.
> > +By using a pathname instead of requiring an open file descriptor,
> > +.BR file_setattr ()
> > +can manipulate filesystem inode attributes
> > +on all file types,
> > +including special files (FIFOs, sockets, block devices, character devices)
> > +where opening the file may have side effects or may not be possible.
> > +With
> > +.BR ioctl (2),
> > +it is not always possible to obtain a file descriptor that refers
> > +directly to the filesystem inode for special files.
> > +.P
> > +As with
> > +.BR openat (2),
> > +if
> > +.I pathname
> > +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 pathname
> > +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).
> > +User-space applications should use
> > +.B file_getattr(2)
> > +to initialize
> > +.I struct fattr
> > +beforehand.
> > +.P
> > +The
> > +.I size
> > +argument specifies the size of the buffer 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 is a bit mask that can include zero or more of the following values:
> > +.TP
> > +.B AT_EMPTY_PATH
> > +If
> > +.I pathname
> > +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 pathname
> > +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 pathname .
> > +(See also
> > +.BR path_resolution (7).)
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is relative but
> > +.I dirfd
> > +is neither
> > +.B AT_FDCWD
> > +nor a valid file descriptor.
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is an empty string,
> > +.B AT_EMPTY_PATH
> > +was specified in
> > +.IR flags ,
> > +and
> > +.I dirfd
> > +is an invalid file descriptor.
> > +.TP
> > +.B EFAULT
> > +.I pathname
> > +or
> > +.I fattr
> > +is an invalid pointer.
> > +.TP
> > +.B EINVAL
> > +Invalid 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 pathname .
> > +.TP
> > +.B ENAMETOOLONG
> > +.I pathname
> > +is too long.
> > +.TP
> > +.B ENOENT
> > +A component of
> > +.I pathname
> > +does not exist,
> > +or
> > +.I pathname
> > +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 pathname
> > +is not a directory or,
> > +.I pathname
> > +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>\\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\\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)\\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)
> > 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
> > 
> > 
> 
> -- 
> <https://www.alejandro-colomar.es>

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

[Alejandro Colomar]

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

Hi Darrick,

> Date: 2026-09-10 09:12:04-0700
> From: "Darrick J. Wong" <djwong@kernel.org>
>
> On Thu, Sep 10, 2026 at 03:20:25PM +0200, Alejandro Colomar wrote:
> > 
> > > Date: 2026-09-10 12:41:18+0200
> > > From: Andrey Albershteyn <aalbersh@kernel.org>
[...]
> > > +.SH DESCRIPTION
> > > +The
> > > +.BR file_getattr ()
> > > +system call retrieves filesystem file attributes
> > > +from the file specified by
> > > +.IR pathname .
> > > +.P
> > > +This system call provides functionality similar to the
> > > +.B FS_IOC_FSGETXATTR
> > > +.BR ioctl (2)
> > > +operation,
> > 
> > Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
> > manual page?
> 
> https://www.man7.org/linux/man-pages/man2/ioctl_xfs_fssetxattr.2.html

Thanks!  I didn't know that page.

I see the page uses the constants as XFS_ instead of FS_?  I think the
page should have some mention about it, especially since it says non-xfs
filesystems also implement this.  Is it the same as (or related to)
what's mentioned in quotactl(2)?

	NOTES
	   Alternative XFS header
	     Instead of <xfs/xqm.h> one  can  use  <linux/dqblk_xfs.h>,
	     taking into account that there are several naming discrep‐
	     ancies:

	     •  Quota       enabling       flags       (of       format
		XFS_QUOTA_[UGP]DQ_{ACCT,ENFD}) are  defined  without  a
		leading "X", as FS_QUOTA_[UGP]DQ_{ACCT,ENFD}.

	     •  The  same is true for XFS_{USER,GROUP,PROJ}_QUOTA quota
		type     flags,     which      are      defined      as
		FS_{USER,GROUP,PROJ}_QUOTA.

	     •  The  dqblk_xfs.h  header  file  defines its own XQM_US‐
		RQUOTA, XQM_GRPQUOTA, and  XQM_PRJQUOTA  constants  for
		the  available  quota  types,  but their values are the
		same as for constants without the XQM_ prefix.

I think we should probably have a xfs-xqm(2head) manual page documenting
these conventions, I think.

Also, given it doesn't seem exclusive of xfs, should we move the manual
page to the Linux man-pages (from xfsprogs)?

> > > +but with the advantage that the file does not need to be opened.
> > > +By using a pathname,
> > > +.BR file_getattr ()
> > > +can retrieve filesystem file attributes
> > > +from all file types,
> > > +including special files such as FIFOs, sockets, block devices, character
> > > +devices, and symlinks, where opening the targeted inode may not be possible.
> > 
> > This seems to be a limitation of FS_IOC_FSGETXATTR(2const), and would be
> > more appropriately documented in that page (if we add it).  There, I'd
> > document it in CAVEATS.  Then, file_getattr(2) wouldn't need to mention
> > this at all, because it's not an issue here.
> 
> Agreed, that belongs in ioctl_xfs_fssetxattr.2, not here.

Thanks!

> 
> --D

Have a lovely day!
Alex

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

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

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

[Darrick J. Wong]

On Thu, Sep 10, 2026 at 06:31:48PM +0200, Alejandro Colomar wrote:
> Hi Darrick,
> 
> > Date: 2026-09-10 09:12:04-0700
> > From: "Darrick J. Wong" <djwong@kernel.org>
> >
> > On Thu, Sep 10, 2026 at 03:20:25PM +0200, Alejandro Colomar wrote:
> > > 
> > > > Date: 2026-09-10 12:41:18+0200
> > > > From: Andrey Albershteyn <aalbersh@kernel.org>
> [...]
> > > > +.SH DESCRIPTION
> > > > +The
> > > > +.BR file_getattr ()
> > > > +system call retrieves filesystem file attributes
> > > > +from the file specified by
> > > > +.IR pathname .
> > > > +.P
> > > > +This system call provides functionality similar to the
> > > > +.B FS_IOC_FSGETXATTR
> > > > +.BR ioctl (2)
> > > > +operation,
> > > 
> > > Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
> > > manual page?
> > 
> > https://www.man7.org/linux/man-pages/man2/ioctl_xfs_fssetxattr.2.html
> 
> Thanks!  I didn't know that page.
> 
> I see the page uses the constants as XFS_ instead of FS_?  I think the

The sorded history of the xfs(ish) file attributes calls is that they
began their lives as XFS_IOC_FSGETXATTR since they were XFS-specific.
Then we tried to make them "generic" by removing the 'X', and that's how
we got FS_IOC_FSGETXATTR.  Finally Andrey came along and made them
proper syscalls with path-lookup abilities ... but for now they use the
same struct as the old XFS_IOC_FSGETXATTR.

Personally I think we should only document XFS_IOC_FSGETXATTR (in
xfsprogs) and file_getattr (in man-pages).  And leave FS_IOC_FSGETXATTR
unmentioned.

> page should have some mention about it, especially since it says non-xfs
> filesystems also implement this.  Is it the same as (or related to)
> what's mentioned in quotactl(2)?
> 
> 	NOTES
> 	   Alternative XFS header
> 	     Instead of <xfs/xqm.h> one  can  use  <linux/dqblk_xfs.h>,
> 	     taking into account that there are several naming discrep‐
> 	     ancies:
> 
> 	     •  Quota       enabling       flags       (of       format
> 		XFS_QUOTA_[UGP]DQ_{ACCT,ENFD}) are  defined  without  a
> 		leading "X", as FS_QUOTA_[UGP]DQ_{ACCT,ENFD}.
> 
> 	     •  The  same is true for XFS_{USER,GROUP,PROJ}_QUOTA quota
> 		type     flags,     which      are      defined      as
> 		FS_{USER,GROUP,PROJ}_QUOTA.
> 
> 	     •  The  dqblk_xfs.h  header  file  defines its own XQM_US‐
> 		RQUOTA, XQM_GRPQUOTA, and  XQM_PRJQUOTA  constants  for
> 		the  available  quota  types,  but their values are the
> 		same as for constants without the XQM_ prefix.
> 
> I think we should probably have a xfs-xqm(2head) manual page documenting
> these conventions, I think.

quotactl (and xattrs) have a similar weird history of originating in XFS
and later getting yanked into the vfs.  Every time I have to go look up
the quota syscalls I just get a headache. :/

--D

> Also, given it doesn't seem exclusive of xfs, should we move the manual
> page to the Linux man-pages (from xfsprogs)?
> 
> > > > +but with the advantage that the file does not need to be opened.
> > > > +By using a pathname,
> > > > +.BR file_getattr ()
> > > > +can retrieve filesystem file attributes
> > > > +from all file types,
> > > > +including special files such as FIFOs, sockets, block devices, character
> > > > +devices, and symlinks, where opening the targeted inode may not be possible.
> > > 
> > > This seems to be a limitation of FS_IOC_FSGETXATTR(2const), and would be
> > > more appropriately documented in that page (if we add it).  There, I'd
> > > document it in CAVEATS.  Then, file_getattr(2) wouldn't need to mention
> > > this at all, because it's not an issue here.
> > 
> > Agreed, that belongs in ioctl_xfs_fssetxattr.2, not here.
> 
> Thanks!
> 
> > 
> > --D
> 
> Have a lovely day!
> Alex
> 
> -- 
> <https://www.alejandro-colomar.es>

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

[Alejandro Colomar]

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

Hi Darrick,

> Date: 2026-09-10 09:44:28-0700
> From: "Darrick J. Wong" <djwong@kernel.org>
>
[...]
> > > > Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
> > > > manual page?
> > > 
> > > https://www.man7.org/linux/man-pages/man2/ioctl_xfs_fssetxattr.2.html
> > 
> > Thanks!  I didn't know that page.
> > 
> > I see the page uses the constants as XFS_ instead of FS_?  I think the
> 
> The sorded history of the xfs(ish) file attributes calls is that they
> began their lives as XFS_IOC_FSGETXATTR since they were XFS-specific.
> Then we tried to make them "generic" by removing the 'X', and that's how
> we got FS_IOC_FSGETXATTR.  Finally Andrey came along and made them
> proper syscalls with path-lookup abilities ... but for now they use the
> same struct as the old XFS_IOC_FSGETXATTR.
> 
> Personally I think we should only document XFS_IOC_FSGETXATTR (in
> xfsprogs) and file_getattr (in man-pages).  And leave FS_IOC_FSGETXATTR
> unmentioned.
> 
[...]
> 
> quotactl (and xattrs) have a similar weird history of originating in XFS
> and later getting yanked into the vfs.  Every time I have to go look up
> the quota syscalls I just get a headache. :/

Thanks!  That makes sense.  :)


Cheers,
Alex

> 
> --D

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

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

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

[Andrey Albershteyn]

Hi Alejandro,

Thanks for the review, I will apply your suggestions, responses to
some of the questions below:

On 2026-09-10 15:20:25, Alejandro Colomar wrote:
> Hi Andrey,
> 
> > Date: 2026-09-10 12:41:18+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/
> > 
> > ---
> > v2: a few grammar fixes, sashiko.dev fixes (wrong AT_FDCWD combined with
> > AT_EMPTY_PATH description, unused "dfd") and dropped requirement to zero
> > fattr before using file_setattr().
> > ---
> >  man/man2/file_getattr.2      | 279 +++++++++++++++++++++++++++++
> >  man/man2/file_setattr.2      | 333 +++++++++++++++++++++++++++++++++++
> >  man/man2type/file_attr.2type | 187 ++++++++++++++++++++
> >  3 files changed, 799 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..2d9a6d338a5e
> > --- /dev/null
> > +++ b/man/man2/file_getattr.2
> > @@ -0,0 +1,279 @@
> > +.\" 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>" "         /* struct " file_attr " and " FS_XFLAG_* " constants */"
> 
> Most of the time, we don't document in these comments where types come
> from.  They are already documented in the man2type manual page for the
> type, so this is a bit redundant.  We limit these comments to constants.

I will drop the 'struct "file_attr " and ' then

> 
> (In a few cases, we document the types too, but those are mistakes that
>  we should fix.)
> 
> > +.BR "#include <sys/syscall.h>" "      /* " SYS_* " constants */"
> > +.B #include <unistd.h>
> > +.P
> > +.B long syscall(SYS_file_getattr,
> > +.BI "               int " dirfd ", const char *" pathname ,
> 
> We now use 'path' quite consistently for these parameter names.
> See this commit:
> 
> 	commit a239bc4520d6cb8b4d217510c22eddd7c3fd5d10
> 	Author: Alejandro Colomar <alx@kernel.org>
> 	Date:   2025-01-15 20:41:01 +0100
> 
> 	    man/: Consistently use 'path' for parameters referring to pathnames
> 	    
> 	    And use 'pathname' in the descriptions.
> 	    
> 	    'pathname' is the POSIXly correct term, and 'path' is a reasonable
> 	    abbreviation for it in parameter names.
> 	    
> 	    Cc: "G. Branden Robinson" <branden@debian.org>
> 	    Signed-off-by: Alejandro Colomar <alx@kernel.org>
> 
> 	diff --git a/man/man2/acct.2 b/man/man2/acct.2
> 	index d2d1be1c4fc6..fe3606c17752 100644
> 	--- a/man/man2/acct.2
> 	+++ b/man/man2/acct.2
> 	@@ -12,7 +12,7 @@ .SH SYNOPSIS
> 	 .nf
> 	 .B #include <unistd.h>
> 	 .P
> 	-.BI "int acct(const char *_Nullable " filename );
> 	+.BI "int acct(const char *_Nullable " path );
> 	 .fi
> 	 .P
> 	 .RS -4
> 	@@ -34,10 +34,10 @@ .SH DESCRIPTION
> 	 The
> 	 .BR acct ()
> 	 system call enables or disables process accounting.
> 	-If called with the name of an existing file as its argument,
> 	+If called with the pathname of an existing file as its argument,
> 	 accounting is turned on,
> 	-and records for each terminating process are appended to
> 	-.I filename
> 	+and records for each terminating process
> 	+are appended to the file
> 	 as it terminates.
> 	 An argument of NULL causes accounting to be turned off.
> 	 .SH RETURN VALUE
> 	...
> 
> > +.BI "               struct file_attr *" fattr ", size_t " size ,
> > +.BI "               unsigned int " flags );
> > +.fi
> > +.P
> > +.IR Note :
> > +glibc provides no wrapper for
> > +.BR file_getattr (),
> > +use
> > +.BR syscall (2)
> > +instead.
> 
> I've been trying to remove this sentence from manual pages.  This note
> was originally introduced when manual pages used syntax as if the
> wrapper existed, but some years ago we started using syscall()
> explicitly, which already clrearly notices this, so this is superfluous.
> Let's not add more.  (I'll remove the existing ones eventually.)
> 
> > +.SH DESCRIPTION
> > +The
> > +.BR file_getattr ()
> > +system call retrieves filesystem file attributes
> > +from the file specified by
> > +.IR pathname .
> > +.P
> > +This system call provides functionality similar to the
> > +.B FS_IOC_FSGETXATTR
> > +.BR ioctl (2)
> > +operation,
> 
> Should we document FS_IOC_FSGETXATTR in a new FS_IOC_FSGETXATTR(2const)
> manual page?
> 
> > +but with the advantage that the file does not need to be opened.
> > +By using a pathname,
> > +.BR file_getattr ()
> > +can retrieve filesystem file attributes
> > +from all file types,
> > +including special files such as FIFOs, sockets, block devices, character
> > +devices, and symlinks, where opening the targeted inode may not be possible.
> 
> This seems to be a limitation of FS_IOC_FSGETXATTR(2const), and would be
> more appropriately documented in that page (if we add it).  There, I'd
> document it in CAVEATS.  Then, file_getattr(2) wouldn't need to mention
> this at all, because it's not an issue here.
> 
> > +.P
> > +As with
> > +.BR openat (2),
> > +if
> > +.I pathname
> > +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 pathname
> > +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) .
> 
> The '(2const)' part shouldn't be in bold.  Thus:
> 
> 	.BR file_attr (2type).
> 
> > +.P
> > +The
> > +.I size
> > +argument specifies the size of the buffer pointed to by
> > +.IR fattr .
> 
> I'd do: s/buffer/structure/
> 
> We say 'size of the buffer' to refer to arrays (and say length,
> to not confuse it with the size in bytes).
> 
> > +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
> 
> s/Userspace/User-space/
> 
> > +.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 is a bit mask, available flags are:
> 
> The usual language we use for this is:
> 
> 	The
> 	.I flags
> 	argument contains
> 	a bitwise OR of zero or more of the following constants:
> 
> See for example readv(2).

I will use "constants" then (the readv uses "following flags")

> 
> There are some minor variations of this in other pages, and I should
> make them more uniform.
> 
> > +.TP
> > +.B AT_EMPTY_PATH
> > +If
> > +.I pathname
> > +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 pathname
> > +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 pathname .
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is relative but
> > +.I dirfd
> > +is neither
> > +.B AT_FDCWD
> > +nor a valid file descriptor.
> > +.TP
> > +.B EBADF
> > +.I pathname
> > +is an empty string,
> > +.B AT_EMPTY_PATH
> > +was specified,
> > +but
> > +.I dirfd
> > +is an invalid file descriptor.
> 
> I was wondering: is it valid to specify AT_EMPTY_PATH, use an empty
> string, and use AT_FDCWD as the dirfd?  That should act on the current
> working directory itself, right?  Or is that not supported?

Yes, this is valid combination. I can describe this case.

> 
> > +.TP
> > +.B EFAULT
> > +.I pathname
> > +or
> > +.I fattr
> > +is an invalid pointer.
> > +.TP
> > +.B EINVAL
> > +Invalid flag specified in
> 
> s/Invalid/Unknown/
> 
> You may have specified a valid flag, but the kernel is old and doesn't
> yet know it.
> 
> > +.IR flags .
> > +.TP
> > +.B EINVAL
> > +.I size
> > +is smaller than
> > +.BR FILE_ATTR_SIZE_VER0 .
> 
> perf_event_open(2) reports E2BIG for a size smaller than
> PERF_ATTR_SIZE_VER0.  This seems unnecessarily inconsistent.  I'm not
> sure which I'd say is more appropriate, but I'd expect them to be
> consistent.  I mentioned perf_event_open(2) because that's the only page
> that has a *_VER0 constant and documents an error if a size is smaller
> than it.  There's also mount_setattr(2) which documents
> MOUNT_ATTR_SIZE_VER0, but it's not documented in ERRORS.
> 
> I think kernel maintainers should have a look at the different APIs that
> have such a value, and discuss whether the error codes should be made
> uniform retroactively, or whether we should accept the existing
> divergence but decide on an error code for new APIs.
> 
> I've CCed linux-api@.

The MOUNT_ATTR_SIZE_VER0 also returns an EINVAL

I'm in favor of EINVAL as E2BIG is probably a more confusing naming
for the too small argument.

-- 
- Andrey

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

[Alejandro Colomar]

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

[CC += PERFORMANCE EVENTS SUBSYSTEM maintainers]

Hi Andrey,

> Date: 2026-09-11 13:17:12+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> Hi Alejandro,
> 
> Thanks for the review, I will apply your suggestions, responses to
> some of the questions below:
> 
[...]
> > > +The
> > > +.I flags
> > > +argument is a bit mask, available flags are:
> > 
> > The usual language we use for this is:
> > 
> > 	The
> > 	.I flags
> > 	argument contains
> > 	a bitwise OR of zero or more of the following constants:
> > 
> > See for example readv(2).
> 
> I will use "constants" then (the readv uses "following flags")

Ok.

> > There are some minor variations of this in other pages, and I should
> > make them more uniform.
> > 
[...]
> > > +.TP
> > > +.B EBADF
> > > +.I pathname
> > > +is relative but
> > > +.I dirfd
> > > +is neither
> > > +.B AT_FDCWD
> > > +nor a valid file descriptor.
> > > +.TP
> > > +.B EBADF
> > > +.I pathname
> > > +is an empty string,
> > > +.B AT_EMPTY_PATH
> > > +was specified,
> > > +but
> > > +.I dirfd
> > > +is an invalid file descriptor.
> > 
> > I was wondering: is it valid to specify AT_EMPTY_PATH, use an empty
> > string, and use AT_FDCWD as the dirfd?  That should act on the current
> > working directory itself, right?  Or is that not supported?
> 
> Yes, this is valid combination. I can describe this case.

Thanks!  I think using wording similar to the one above would be enough:

	but
	.I dirfd
	is neither
	.B AT_FDCWD
	nor a valid file descriptor.

[...]
> > > +.TP
> > > +.B EINVAL
> > > +.I size
> > > +is smaller than
> > > +.BR FILE_ATTR_SIZE_VER0 .
> > 
> > perf_event_open(2) reports E2BIG for a size smaller than
> > PERF_ATTR_SIZE_VER0.  This seems unnecessarily inconsistent.  I'm not
> > sure which I'd say is more appropriate, but I'd expect them to be
> > consistent.  I mentioned perf_event_open(2) because that's the only page
> > that has a *_VER0 constant and documents an error if a size is smaller
> > than it.  There's also mount_setattr(2) which documents
> > MOUNT_ATTR_SIZE_VER0, but it's not documented in ERRORS.
> > 
> > I think kernel maintainers should have a look at the different APIs that
> > have such a value, and discuss whether the error codes should be made
> > uniform retroactively, or whether we should accept the existing
> > divergence but decide on an error code for new APIs.
> > 
> > I've CCed linux-api@.
> 
> The MOUNT_ATTR_SIZE_VER0 also returns an EINVAL

Thanks!  I'll document that.

> I'm in favor of EINVAL as E2BIG is probably a more confusing naming
> for the too small argument.

I think I agree.

I've CCd the maintainers of perf_event_open(2).  Can perf_event_open(2)
be changed to report EINVAL?  Or is that mistake set in stone?


Have a lovely day!
Alex

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

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