Add manual page for file_getattr(). Link: https://lore.kernel.org/all/20250630-xattrat-syscall-v6-0-c4e3bc35227b@kernel.org/ Reviewed-by: Alejandro Colomar Signed-off-by: Andrey Albershteyn --- man/man2/file_getattr.2 | 252 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 man/man2/file_getattr.2 diff --git a/man/man2/file_getattr.2 b/man/man2/file_getattr.2 new file mode 100644 index 000000000000..9963eeaa7caf --- /dev/null +++ b/man/man2/file_getattr.2 @@ -0,0 +1,252 @@ +.\" Copyright, the authors of the Linux man-pages project +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH file_getattr 2 (date) "Linux man-pages (unreleased)" +.SH NAME +file_getattr \- get filesystem file attributes +.SH SYNOPSIS +.nf +.BR "#include " " /* " AT_* " constants */" +.BR "#include " " /* " FS_XFLAG_* " constants */" +.BR "#include " " /* " SYS_* " constants */" +.B #include +.P +.B long syscall(SYS_file_getattr, +.BI " int " dirfd ", const char *" path , +.BI " struct file_attr *" fattr ", size_t " size , +.BI " unsigned int " flags ); +.fi +.SH DESCRIPTION +The +.BR file_getattr () +system call retrieves filesystem file attributes +of the file +specified by path. +.P +The +.I dirfd +and +.I path +arguments behave in the same way as in +.BR openat (2), +with the difference that +.I path +can be NULL meaning an empty string. +.P +The +.I fattr +argument is a pointer to a +.I file_attr +structure. +This structure will be filled with file attributes. +This structure is described in +.BR file_attr (2type). +.P +The +.I size +argument specifies the size of the structure pointed to by +.IR fattr . +The size indicates the version of the structure in use, +and should always be specified as +.IR sizeof(struct file_attr) . +.P +The +.I flags +argument contains a bitwise OR of zero or more of the following constants: +.TP +.B AT_EMPTY_PATH +If +.I path +is an empty string, +operate on the file referred to by +.IR dirfd . +In this case, +.I dirfd +can refer to any type of file, +not just a directory. +.TP +.B AT_SYMLINK_NOFOLLOW +If +.I path +is a symbolic link, +do not dereference it; +instead, +get attributes of the symbolic link inode itself. +.SH RETURN VALUE +On success, +zero is returned. +On error, +\-1 is returned, +and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B E2BIG +.I size +is too big (larger than +.BR PAGE_SIZE ). +.TP +.B EACCES +Search permission is denied for one of the directories +in the path prefix of +.IR path . +.TP +.B EBADF +.I path +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EBADF +.I path +is an empty string, +.B AT_EMPTY_PATH +was specified, +but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP +.B EFAULT +.I path +or +.I fattr +is an invalid pointer. +.TP +.B EINVAL +Unknown flags specified in +.IR flags . +.TP +.B EINVAL +.I size +is smaller than +.BR FILE_ATTR_SIZE_VER0 . +.TP +.B ELOOP +Too many symbolic links encountered while resolving +.IR path . +.TP +.B ENAMETOOLONG +.I path +is too long. +.TP +.B ENOENT +A component of +.I path +does not exist. +.TP +.B ENOENT +.I path +is an empty string and +.B AT_EMPTY_PATH +was not specified in +.IR flags . +.TP +.B ENOMEM +Insufficient kernel memory was available. +.TP +.B ENOTDIR +A component of the path prefix of +.I path +is not a directory. +.TP +.B ENOTDIR +.I path +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B EOPNOTSUPP +The filesystem does not support getting attributes on this type of inode. +.SH HISTORY +Linux 6.17 +.SH NOTES +This system call is designed to be extensible. +The +.I size +argument allows user-space applications to indicate +which version of the +.I file_attr +structure they are using, +enabling the kernel to support both old and new versions +of the structure simultaneously. +.P +If +.I size +is smaller than the structure size the kernel expects, +only the fields that fit within +.I size +will be filled in. +If +.I size +is larger than the kernel's structure size, +the extra bytes are zeroed. +.SH EXAMPLES +The program below demonstrates the use of +.BR file_getattr () +to retrieve and display file attributes. +.P +.in +4n +.\" SRC BEGIN (file_getattr.c) +.EX +#define _GNU_SOURCE +#include +#include +#include +#include +#include +#include +\& +#ifndef SYS_file_getattr +#define SYS_file_getattr 467 +#endif +\& +int +main(int argc, char *argv[]) +{ + struct file_attr fa; + long ret; +\& + if (argc != 2) { + fprintf(stderr, "Usage: %s \[rs]n", argv[0]); + exit(EXIT_FAILURE); + } +\& + ret = syscall(SYS_file_getattr, AT_FDCWD, argv[1], &fa, + sizeof(fa), 0); + if (ret == \-1) { + perror("file_getattr"); + exit(EXIT_FAILURE); + } +\& + printf("File attributes:\[rs]n"); + printf(" xflags: 0x%w64x\[rs]n", fa.fa_xflags); + printf(" extsize: %w32u\[rs]n", fa.fa_extsize); + printf(" nextents: %w32u\[rs]n", fa.fa_nextents); + printf(" projid: %w32u\[rs]n", fa.fa_projid); + printf(" cowextsize: %w32u\[rs]n", fa.fa_cowextsize); +\& + /* + * Try setting NODUMP flag with chattr +d ./foo to see + * the difference. + */ + if (fa.fa_xflags & FS_XFLAG_NODUMP) + printf(" NODUMP flag is set\[rs]n"); +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.in +.SH SEE ALSO +.BR file_setattr (2), +.BR file_attr (2type), +.BR ioctl (2), +.BR ioctl_fs (2), +.BR openat (2), +.BR ioctl_xfs_fssetxattr (2) -- 2.56.0