statx.2: Clarify details of a case where an invalid 'mask' value may be rejected

As reported by Simone:

    I was looking at version from 2017-09-15 but it's the same
    on: http://man7.org/linux/man-pages/man2/statx.2.html
    (2019-03-06)

    There is reported (about the mask argument) after the list
    of constants:

    > Note that the kernel does not reject values in mask other
    > than the above.  Instead, it simply informs the caller which
    > values are sup‐ ported by this kernel and filesystem via the
    > statx.stx_mask field.

    But as reported in the error values, there can be EINVAL if
    mask has a reserved valued, and I found a check against
    STATX__RESERVED in fs/stat.c for this. So if you use a that
    bit (0x80000000U) the kernel will reject the value.

    Probably is better to say that the kernel do not enforce the
    use of only the listed values, but there are anyway reserved
    values so and so you cannot put whatever you want on mask
    (that apply to more values than UINT_MAX).

Reported-by: Simone Piccardi <piccardi@truelite.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/statx.2 b/man2/statx.2
index 49d48daaa78c058e38b46297f9a9b564682a9039..2370aa1d96052b47bd0f7facf31c6b45dbcc71da 100644 (file)
--- a/man2/statx.2
+++ b/man2/statx.2
@@ -265,11 +265,14 @@ STATX_ALL [All currently available fields]
 .TE
 .in
 .PP
-Note that the kernel does
+Note that, in general, the kernel does
 .I not
 reject values in
 .I mask
 other than the above.
+(For an exception, see
+.B EINVAL
+in errors.)
 Instead, it simply informs the caller which values are supported
 by this kernel and filesystem via the
 .I statx.stx_mask
@@ -490,6 +493,9 @@ Invalid flag specified in
 .B EINVAL
 Reserved flag specified in
 .IR mask .
+(Currently, there is one such flag, designated by the constant
+.BR STATX__RESERVED ,
+with the value 0x80000000U.)
 .TP
 .B ELOOP
 Too many symbolic links encountered while traversing the pathname.