RE: [RFC] bpf.2: Use standard types and attributes

[David Laight <David.Laight@ACULAB.COM>]

From: Zack Weinberg
> Sent: 25 April 2021 20:17
> 
> On Sat, Apr 24, 2021 at 4:43 PM David Laight via Libc-alpha
> <libc-alpha@sourceware.org> wrote:
> > From: Alexei Starovoitov
> > > On Fri, Apr 23, 2021 at 4:15 PM Alejandro Colomar <alx.manpages@gmail.com> wrote:
> ...
> > > > Some pages also document attributes, using GNU syntax
> > > > '__attribute__((xxx))'.  Update those to use the shorter and more
> > > > portable C2x syntax, which hasn't been standardized yet, but is
> > > > already implemented in GCC, and available through either --std=c2x
> > > > or any of the --std=gnu... options.
> ..
> > And the code below is no more portable that a #pragma'.
> > It is probably worse than __attribute__((aligned(8)))
> > +            uint64_t [[gnu::aligned(8)]] value;
> > The standards committee are smoking dope again.
> > At least the '__aligned_u64 value;' form stands a reasonable
> > chance of being converted by cpp into whatever your compiler supports.
> 
> Is it actually necessary to mention the alignment overrides at all in
> the manpages?  They are only relevant to people working at the level
> of physical layout of the data in RAM, and those people are probably
> going to have to consult the header file anyway.

Depends, if the man page defines the structure - it needs to
contain its definition.
If theory the man page ought to be the definition, and the code
do what the man page says happens.

An alternative is for the man page to say that the structure
contains some fields - without prescribing the order, or
stopping the implementation adding additional fields (or even
changing the actual numeric type).
This is more common in the standards documents.
IMHO The Linux pages really ought to say how linux does things.
(With notes about portability.)

	David

-
Registered Address Lakeside, Bramley Road, Mount Farm, Milton Keynes, MK1 1PT, UK
Registration No: 1397386 (Wales)