[PATCH v2] man: document that XFS_IOC_FS[G|S]ETXATTR can not be used on special files

[PATCH v2] man: document that XFS_IOC_FS[G|S]ETXATTR can not be used on special files

[Andrey Albershteyn]

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.

Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
Reviewed-by: Alejandro Colomar <alx@kernel.org>

---
Changes from v1:
- Use semantic newlines
- pathname-based
- RvB
---
 man/man2/ioctl_xfs_fsgetxattr.2 | 23 ++++++++++++++++++++++-
 1 file changed, 22 insertions(+), 1 deletion(-)

diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
index 25a9ba7965d1..db5eb232319e 100644
--- a/man/man2/ioctl_xfs_fsgetxattr.2
+++ b/man/man2/ioctl_xfs_fsgetxattr.2
@@ -238,6 +238,27 @@ 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.
+.P
+For a pathname-based interface 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)
-- 
2.55.0

Re: [PATCH v2] man: document that XFS_IOC_FS[G|S]ETXATTR can not be used on special files

[Alejandro Colomar]

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

Hi Andrey,

> Date: 2026-09-14 12:47:48+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.
> 
> Signed-off-by: Andrey Albershteyn <aalbersh@kernel.org>
> Reviewed-by: Alejandro Colomar <alx@kernel.org>
> 
> ---
> Changes from v1:
> - Use semantic newlines
> - pathname-based
> - RvB
> ---
>  man/man2/ioctl_xfs_fsgetxattr.2 | 23 ++++++++++++++++++++++-
>  1 file changed, 22 insertions(+), 1 deletion(-)
> 
> diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> index 25a9ba7965d1..db5eb232319e 100644
> --- a/man/man2/ioctl_xfs_fsgetxattr.2
> +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> @@ -238,6 +238,27 @@ 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,

I'd break the line before 'FIFOs' too.  Since FIFOs is a member of a
list that follows, it should be treated like the other elements in the
list.

Other than that, LGTM.


Have a lovely day!
Alex

> +sockets,
> +block devices,
> +character devices,
> +and symlinks.
> +.P
> +For a pathname-based interface 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)
> -- 
> 2.55.0
> 

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

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