* [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls @ 2026-09-10 10:41 Andrey Albershteyn 2026-09-10 13:20 ` Alejandro Colomar 0 siblings, 1 reply; 8+ messages in thread From: Andrey Albershteyn @ 2026-09-10 10:41 UTC (permalink / raw) To: Alejandro Colomar, linux-man Cc: Andrey Albershteyn, linux-xfs, linux-fsdevel, Christoph Hellwig, djwong 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 */" +.BR "#include <sys/syscall.h>" " /* " SYS_* " constants */" +.B #include <unistd.h> +.P +.B long syscall(SYS_file_getattr, +.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_getattr (), +use +.BR syscall (2) +instead. +.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, +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. +.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) . +.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 +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 is a bit mask, available flags are: +.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. +.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 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 getting attributes on this type of inode. +.SH HISTORY +.SS Linux 6.17 +This system call is introduced as a more flexible alternative to the +FS_IOC_FSGETXATTR +.BR ioctl (2) +which could work on any type of file. +.SH NOTES +This system call is designed to be extensible. +The +.I size +argument allows userspace applications to indicate +which version of the +.I file_attr +structure they are using, +enabling the kernel to support both old and new versions +of the structure simultaneously. +.P +If +.I size +is smaller than the structure size the kernel expects, +only the fields that fit within +.I size +will be filled in. +If +.I size +is larger than the kernel's structure size, +the extra bytes are zeroed. +.SH EXAMPLES +The program below demonstrates the use of +.BR file_getattr () +to retrieve and display file attributes. +.P +.in +4n +.EX +#include <fcntl.h> +#include <linux/fs.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/syscall.h> +#include <unistd.h> + +#ifndef SYS_file_getattr +#define SYS_file_getattr 467 +#endif + +int +main(int argc, char *argv[]) +{ + struct file_attr fa = { 0 }; + long ret; + + if (argc != 2) { + fprintf(stderr, "Usage: %s <filename>\\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:\\n"); + printf(" xflags: 0x%llx\\n", (unsigned long long)fa.fa_xflags); + 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 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 10:41 [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls Andrey Albershteyn @ 2026-09-10 13:20 ` Alejandro Colomar 2026-09-10 16:12 ` Darrick J. Wong 2026-09-11 11:17 ` Andrey Albershteyn 0 siblings, 2 replies; 8+ messages in thread From: Alejandro Colomar @ 2026-09-10 13:20 UTC (permalink / raw) To: Andrey Albershteyn Cc: linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, djwong, linux-api [-- 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 --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 13:20 ` Alejandro Colomar @ 2026-09-10 16:12 ` Darrick J. Wong 2026-09-10 16:31 ` Alejandro Colomar 2026-09-11 11:17 ` Andrey Albershteyn 1 sibling, 1 reply; 8+ messages in thread From: Darrick J. Wong @ 2026-09-10 16:12 UTC (permalink / raw) To: Alejandro Colomar Cc: Andrey Albershteyn, linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, linux-api 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> ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 16:12 ` Darrick J. Wong @ 2026-09-10 16:31 ` Alejandro Colomar 2026-09-10 16:44 ` Darrick J. Wong 0 siblings, 1 reply; 8+ messages in thread From: Alejandro Colomar @ 2026-09-10 16:31 UTC (permalink / raw) To: Darrick J. Wong Cc: Andrey Albershteyn, linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, linux-api [-- 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 --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 16:31 ` Alejandro Colomar @ 2026-09-10 16:44 ` Darrick J. Wong 2026-09-10 16:50 ` Alejandro Colomar 0 siblings, 1 reply; 8+ messages in thread From: Darrick J. Wong @ 2026-09-10 16:44 UTC (permalink / raw) To: Alejandro Colomar Cc: Andrey Albershteyn, linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, linux-api 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> ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 16:44 ` Darrick J. Wong @ 2026-09-10 16:50 ` Alejandro Colomar 0 siblings, 0 replies; 8+ messages in thread From: Alejandro Colomar @ 2026-09-10 16:50 UTC (permalink / raw) To: Darrick J. Wong Cc: Andrey Albershteyn, linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, linux-api [-- 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 --] ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-10 13:20 ` Alejandro Colomar 2026-09-10 16:12 ` Darrick J. Wong @ 2026-09-11 11:17 ` Andrey Albershteyn 2026-09-11 11:56 ` Alejandro Colomar 1 sibling, 1 reply; 8+ messages in thread From: Andrey Albershteyn @ 2026-09-11 11:17 UTC (permalink / raw) To: Alejandro Colomar Cc: linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, djwong, linux-api 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls 2026-09-11 11:17 ` Andrey Albershteyn @ 2026-09-11 11:56 ` Alejandro Colomar 0 siblings, 0 replies; 8+ messages in thread From: Alejandro Colomar @ 2026-09-11 11:56 UTC (permalink / raw) To: Andrey Albershteyn Cc: linux-man, linux-xfs, linux-fsdevel, Christoph Hellwig, djwong, linux-api, Peter Zijlstra, Ingo Molnar, Arnaldo Carvalho de Melo, Namhyung Kim, Mark Rutland, Alexander Shishkin, Jiri Olsa, Ian Rogers, Adrian Hunter, James Clark, linux-perf-users, linux-kernel [-- 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 --] ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2026-09-11 11:57 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2026-09-10 10:41 [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls Andrey Albershteyn 2026-09-10 13:20 ` Alejandro Colomar 2026-09-10 16:12 ` Darrick J. Wong 2026-09-10 16:31 ` Alejandro Colomar 2026-09-10 16:44 ` Darrick J. Wong 2026-09-10 16:50 ` Alejandro Colomar 2026-09-11 11:17 ` Andrey Albershteyn 2026-09-11 11:56 ` Alejandro Colomar
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).