Re: [PATCH v6 2/2] man/man2: introduce man page for file_setattr(2) syscall

[Alejandro Colomar <alx@kernel.org>]

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

> Date: 2026-10-21 16:10:05+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> Add manual pages for file_setattr() syscall.
> 
> Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>

Hi Andrey,

I've applied this patch with some tweaks.  Thanks!


Cheers,
Alex

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

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

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