* Re: [PATCH] man: document that XFS_IOC_FS[G|S]ETXATTR can not be used on special files
2026-09-11 11:47 [PATCH] man: document that XFS_IOC_FS[G|S]ETXATTR can not be used on special files Andrey Albershteyn
@ 2026-09-11 12:29 ` Alejandro Colomar
0 siblings, 0 replies; 2+ messages in thread
From: Alejandro Colomar @ 2026-09-11 12:29 UTC (permalink / raw)
To: Andrey Albershteyn; +Cc: linux-xfs, djwong
[-- Attachment #1: Type: text/plain, Size: 2713 bytes --]
Hi Andrey,
> Date: 2026-09-11 13:47:44+0200
> From: Andrey Albershteyn <aalbersh@kernel.org>
>
> Add a CAVEATS section with an note that these ioctls can not be used on
> special files and leave a reference to an alternative pathname based
> syscall interface.
>
Please add:
Cc: Alejandro Colomar <alx@kernel.org>
Cc: "Darrick J. Wong" <djwong@kernel.org>
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> ---
Thanks!
> man/man2/ioctl_xfs_fsgetxattr.2 | 19 ++++++++++++++++++-
> 1 file changed, 18 insertions(+), 1 deletion(-)
>
> diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> index 25a9ba7965d1..5d223138e419 100644
> --- a/man/man2/ioctl_xfs_fsgetxattr.2
> +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> @@ -238,6 +238,23 @@ Caller did not have permission to change the attributes.
> This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> Linux kernel.
> Not all fields may be understood by filesystems other than xfs.
> +.SH CAVEATS
> +The
> +.B XFS_IOC_FSGETXATTR
> +and
> +.B XFS_IOC_FSSETXATTR
> +.BR ioctl (2)
> +operations require the user to open the file, but this may not be possible or
> +lead to side effects on special files such as FIFOs, sockets, block devices,
> +character devices, and symlinks.
I'd recommend that this project should use semantic newlines.
See man-pages(7):
$ MANWIDTH=64 man man-pages | awk '/Use semantic newlines/,/^$/'
Use semantic newlines
In the source of a manual page, new sentences should be
started on new lines, long sentences should be split into
lines at clause breaks (commas, semicolons, colons, and so
on), and long clauses should be split at phrase bound‐
aries. This convention, sometimes known as "semantic new‐
lines", makes it easier to see the effect of patches,
which often operate at the level of individual sentences,
clauses, or phrases.
However, I notice that the project isn't using them, so it's up to them
whether they want it for new documentation. I'd recommend using them.
> +.P
> +For a pathname based interface see
s/pathname based/pathname-based/
See <https://www.grammar-monster.com/lessons/hyphens_in_compound_adjectives.htm>
Also, s/see/see the/
> +.BR file_getattr (2)
> +and
> +.BR file_setattr (2)
> +syscalls.
> .SH SEE ALSO
> .BR ioctl (2),
> -.BR ioctl_iflags (2)
> +.BR ioctl_iflags (2),
> +.BR file_getattr (2),
> +.BR file_setattr (2)
Other than those minor details:
Reviewed-by: Alejandro Colomar <alx@kernel.org>
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] 2+ messages in thread