Michael Kerrisk (man-pages) <mtk.manpa...@gmail.com> wrote:
> I was reading your statx(2) man page, and noticed this text:
>
> Do not simply set mask to UINT_MAX as one or more bits may, in the
> future, be used to specify an extension to the buffer.
>
> (Here' 'mask' is the fourth argument to statx())
>
> What is going on here? Why is there not a check in the code to
> give EINVAL if any flag other than those in STATX_ALL (0x00000fffU)
> is specified? (There is a check that gives EINVAL flags in
> STATX__RESERVED (0x80000000U), but STATX_ALL != ~STATX__RESERVED.
Because:
(1) There's no way to find out what mask bits are supported by the kernel,
short of trying them, and all the kernel tells you is that you were wrong
somehow. It's kind of like playing the mastermind game.
(2) What an application sees as STATX_ALL is provided by the header files it
was built against, not the kernel it is being run against. The running
kernel may have a different idea of what STATX_ALL should be. Further,
the running kernel may provide more, or _less_, than an app was lead to
expect.
(3) There's no problem with asking for extra bits, even if the running kernel
does not support them, because the kernel tells you in its response what
fields it actually gave you. If you asked for a field that didn't exist,
the flag will be clear in stx_mask upon return.
One thing the kernel guarantees is at least some support for all fields
governed by STATX_BASIC_STATS, ie. the fields that correspond to those in
the normal stat struct - and that any such field will have a dummy value
emplaced if the field isn't supported (exactly as with stat() now).
This is documented thusly:
.PP
It should be noted that the kernel may return fields that weren't
requested and
may fail to return fields that were requested, depending on what the
backing
filesystem supports. In either case,
.I stx_mask
will not be equal
.IR mask .
.PP
If a filesystem does not support a field or if it has an
unrepresentable value
(for instance, a file with an exotic type), then the mask bit
corresponding to
that field will be cleared in
.I stx_mask
even if the user asked for it and a dummy value will be filled in for
compatibility purposes if one is available (e.g. a dummy uid and gid
may be
specified to mount under some circumstances).
.PP
A filesystem may also fill in fields that the caller didn't ask for if
it has
values for them available at no extra cost. If this happens, the
corresponding
bits will be set in
.IR stx_mask .
.PP
David
