Re: statx manpage

From: Jeff Layton <jlayton@poochiereds.net>
To: Matthew Wilcox <willy@infradead.org>
Cc: David Howells <dhowells@redhat.com>,
	Andreas Dilger <adilger@dilger.ca>,
	Christoph Hellwig <hch@infradead.org>,
	"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>,
	"Darrick J. Wong" <darrick.wong@oracle.com>,
	linux-fsdevel <linux-fsdevel@vger.kernel.org>,
	xfs <linux-xfs@vger.kernel.org>
Subject: Re: statx manpage
Date: Wed, 22 Mar 2017 06:55:09 -0400	[thread overview]
Message-ID: <1490180109.2593.13.camel@poochiereds.net> (raw)
In-Reply-To: <20170320160127.GB31556@bombadil.infradead.org>

On Mon, 2017-03-20 at 09:01 -0700, Matthew Wilcox wrote:
> On Wed, Mar 08, 2017 at 10:26:14AM -0500, Jeff Layton wrote:
> > On Wed, 2017-03-08 at 09:24 +0000, David Howells wrote:
> > > Andreas Dilger <adilger@dilger.ca> wrote:
> > > >    To test whether a path is a regular file (for example), one could write:
> > > >    .nf
> > > >    .in +4n
> > > >    rc = statx(AT_FDCWD, pathname, 0, STATX_TYPE, &stx);
> > > >    if (stx.stx_mask & STATX_TYPE && S_ISREG(sb.stx_mode)) {
> > > >       /* Handle regular file */
> > > >    }
> > > 
> > > Good idea.
> > 
> > Note that & and && have similar precedence, IIRC, so you probably want
> > to wrap that flag check in parenthesis.
> 
> They're actually pretty far apart.  & is priority 8 and && is priority 11.
> But the fact that you thought they were similar shows that most of
> us don't really know what C's operator precedence is (beyond + and *)
> and we should err on the side of clarity by using the unnecessary parens.
> 

Ahh, good to know. My rules are generally: multiplication and division
come before addition and subtraction, and put parenthesis around
everything else. :)

> > If the plan is to eventually (in some far away future) to deprecate
> > stat(), then we probably don't want this manpage to refer to it as a
> > canonical source of information. I say duplicate it here.
> 
> We haven't even deprecated select() in favour of poll() ... indeed,
> pselect() was added.  I can't imagine stat() ever being deprecated.

Ok, deprecated is probably the wrong choice of words. You're correct
that we'll never be able to fully rip it out just due to the volume of
old programs that use it.

My thinking is that statx will come to supplant stat in newer code, and
stat will eventually become a "legacy" syscall. Typically we don't want
to have to refer to "legacy" manpages for canonical info in new
interfaces. If anything we may want to remove that info from stat(2)
manpage and have it refer to statx(2) for it.
-- 
Jeff Layton <jlayton@poochiereds.net>