Re: [PATCH v2] man/man2: introduce man page for file_getattr/file_setattr syscalls

["Darrick J. Wong" <djwong@kernel.org>]

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>