archive mirror
 help / color / mirror / Atom feed
From: David Howells <>
To: "Michael Kerrisk (man-pages)"
	Alexander Viro
	Jeff Layton <>,
	lkml <>,
	Linux API <>,
	linux-man <>
Subject: Re: Revised statx(2) man page for review [and AT_EMPTY_PATH question]
Date: Wed, 26 Apr 2017 12:35:08 +0100	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

Michael Kerrisk (man-pages) <> wrote:

>        Note: There is no glibc wrapper for renameat2(); see NOTES.

statx, not renameat2.

>                __u64 stx_blocks;      /* Number of 512B blocks allocated */

The following needs to be added in here:

		__u64	stx_attributes_mask; /* Mask to show what's supported in stx_attributes */

This indicates what stx_attributes the VFS and filesystem actually support.

>                __s32 tv_nsec;   /* Nanoseconds before or since tv_sec */

If you're going to do Dmitry's suggestion, then this needs to be __u32 and you
should remove "before or".

>        statx() uses pathname, dirfd, and  flags  identify  the  target
>        file in one of the following ways:

"to identify"

>        A pathname interpreted relative to a directory file descriptor

I think this is too wordy for a heading and it almost seems to merge into the
description paragraph since it almost ends at the same right margin.  How

	A directory-relative pathname

>        By file descriptor
>               If pathname is NULL, then the target  file  is  the  one
>               referred  to  by  the  file descriptor dirfd.  dirfd may
>               refer to any type of file, not just a  directory.   (The
>               AT_EMPTY_PATH  flag  described  below  provides  similar
>               functionality.)
>               ┌───────────────────────────────┐
>               │FIXME                                                │
>               ├───────────────────────────────┤
>               │It appears that there  are  two  different  ways  of │
>               │doing  the  same  thing:  specifying  the file to be │
>               │stat'ed via a file descriptor.  Either,  we  specify │
>               │'pathname'  as  NULL, or we specify 'pathname' as an │
>               │empty string and  include  the  AT_EMPTY_PATH  flag. │
>               │What's  the  rationale  for having two ways of doing │
>               │this?                                                │
>               └───────────────────────────────┘

AT_EMPTY_PATH wasn't there back in 2010.  I could eliminate the:

	statx(fd, NULL, 0, ...);

option in favour of:

	statx(fd, "", AT_EMPTY_PATH, ...);

Any thoughts either way, Al?

It would seem that AT_EMPTY_PATH should be redundant, though, since you can
just set the pathname pointer to NULL.

>        The mask argument to statx() is used to tell the  kernel  which
>        fields  the  caller is interested in.  mask is an ORed combina‐
>        tion of the following constants:
>            STATX_TYPE          Want stx_mode & S_IFMT
>	     ...
>            STATX_ALL           [All currently available fields]
>        Note the kernel does not reject values in mask other  than  the
>        above.   Instead, it simply informs the caller which values are
>        supported by this kernel and filesystem via the  statx.stx_mask
>        field.  Therefore, do not simply set mask to UINT_MAX (all bits
>        set), as one or more bits may, in the future, be used to  spec‐
>        ify an extension to the buffer.

Is it worth mentioning STATX__RESERVED here, I wonder?  It's not something
that you can actually use (you'll get EINVAL if you try), and will be renamed
should it become used.

>        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.

Maybe add "and can be safely ignored" in there somewhere since this seems to
be upsetting people.

>        If a filesystem does not support a field or if it has an unrep‐
>        resentable value (for instance, a file with  an  exotic  type),
>        then  the  mask bit corresponding to that field will be cleared
>        in stx_mask even if the user asked for it  and  a  dummy  value
>        will  be  filled in for compatibility purposes if one is avail‐
>        able (e.g., a dummy UID and GID may be specified to mount under
>        some circumstances).

I don't promise a dummy value for any "extended" field other than zero.

>        Apart from stx_mask (which is described above), the  fields  in
>        the statx structure are:
>        stx_mode
>               The file type and mode.  See inode(7) for details.
>	 ...

Should this list either be in alphabetical order or offset-in-struct order?

This needs to be added:

	      A mask indicating which bits in stx_attributes are supported by
	      the VFS and the filesystem.

>    File attributes
>        The stx_attributes field contains a  set  of  ORed  flags  that
>        indicate additional attributes of the file:

Probably should mention stx_attributes_mask here also.  Perhaps:

       The stx_attributes field contains a set of ORed flags that
       indicate additional attributes of the file.  Note that any
       attribute that is not indicated as supported by
       stx_attributes_mask has no usable value here.  The bits in
       stx_attributes_mask correspond bit-by-bit to stx_attributes.

To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to
More majordomo info at

  parent reply	other threads:[~2017-04-26 11:35 UTC|newest]

Thread overview: 11+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-04-25 11:14 Revised statx(2) man page for review Michael Kerrisk (man-pages)
     [not found] ` <>
2017-04-25 18:50   ` Silvan Jegen
     [not found]     ` <>
2017-04-25 19:40       ` Michael Kerrisk (man-pages)
2017-04-25 20:06   ` Dmitry V. Levin
     [not found]     ` <20170425200656.GA30045-u2l5PoMzF/>
2017-04-26  5:42       ` Michael Kerrisk (man-pages)
     [not found]         ` <>
2017-04-26 10:43           ` G. Branden Robinson
2017-04-26 11:35   ` David Howells [this message]
     [not found]     ` <>
2017-04-26 12:13       ` Revised statx(2) man page for review [and AT_EMPTY_PATH question] Michael Kerrisk (man-pages)
2017-04-26 15:53       ` Al Viro
2017-04-26 15:10     ` David Howells
     [not found]       ` <>
2017-04-26 19:08         ` Michael Kerrisk (man-pages)

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \
    --cc=viro-RmSDqhL/ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).