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

[Alejandro Colomar <alx@kernel.org>]

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

Hi Andrey,

> Date: 2026-09-29 15:02:31+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> 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.

Is there any difference with openat(2) regarding the handling of 'path'
and 'dirfd'?  If not, we could say:

	The
	.I dirfd
	and
	.I path
	arguments behave in the same way as in
	.BR openat (2).

Is there any small difference, or is it exactly as in openat(2)?

Other than that small doubt:

	Reviewed-by: Alejandro Colomar <alx@kernel.org>


Have a lovely night!
Alex

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

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

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