Just forwarding a conversation to the list
On 10/21/21 10:17 AM, Alejandro Colomar (man-pages) wrote:
Hello Jens,
On 10/21/21 9:27 AM, Jₑₙₛ Gustedt wrote:
Hello Alejandro,
On Wed, 20 Oct 2021 22:22:40 +0200, Alejandro Colomar wrote:
As N2417 (part of C2x) suggests. This syntax is very informative,
and also, if used by library implementers, can improve static
analysis.
Since it is backwards compatible with pointer syntax, we can do this.
I understand the intent, but these `_r` interfaces finally went into
the standard without array notation. AFAIR one of the arguments was
that the headers should be usable from C++.
Hmm, I understand. If I may digress, that C/C++ incompatibility has
been the only real pain in reusing my C headers in C++; so much that I
have separate .h and .hxx header files for the same functions.
Eventhough C++ with VLAs would be a bad idea, parameter VLAs are not
really VLAs (in the sense of the same stack problems that alloca() has),
but syntactic sugar for pointers. Would it be too much to ask to get
C++ accept that C feature? Has it been discussed and is there any
consensus that it should not be done? Or is it worth proposing to the
C++ comitee?
So I am not sure if it is consensus to have the documentation have a
different form of the interfaces than the standard(s). I don't know if
you'd also add the attributes that glibc uses to the `printf`
interfaces, for example. >
I am not saying that you shouldn't, in the contrary it is probably a
good idea to list all those semantic restrictions in the documented
interface for which me have syntax. I just want to make sure that
adding such semantic hints to the documentation is consensus and
sufficiently well discussed.
We recently (a few months ago) added 'noreturn' and 'restrict' to the
man-pages prototypes.
My opinion is that we should only add a specific syntax if it adds very
useful information that cannot easily be read from the rest of the
prototype.
noreturn and restrict are examples of that, and I think [static 26] in
the case of these _r functions also are. Or also [[gnu::nonnull]],
which BTW, as N2417 shows implicitly by the use of [static 1], which as
I said in patch 2/2 is confusing, I would like to suggest for the
standard to take it as [[nonnull]], probably for C3X I guess.
However, some attributes are not that useful. I think
[[gnu::fornat(printf, 3, 4)]] wouldn't add much valuable information to
snprintf that isn't already readable from the prototype. It is an
attribute only useful for the compiler/static analyzer, but not very
much for the human (compared to the noise it adds).
What I fear when adding these things is adding too much noise to the
SYNOPSIS.
Ideally, the standard and the man-pages would have the same prototypes.
However, since the standard is not (and cannot be) perfect, when it
has some limitations that it cannot overcome which we can, I'll be happy
to differ from it. nonnull IMO is very useful in the SYNOPSIS, so I'd
like to have it (and I'd also like the standard to have it, but that's
likely to take a decade, if it happens at all). Also, the man-pages
already use array notation in some specific cases (see pipe(2)), and
they are mostly targeted at C programmers, so I think we can safely
assume that a C++ reader will know the limitation of its language, and
be able to translate C to C++ easily. If any glibc programmer has any
concerns regarding that, this is the moment for giving a different
opinion :).
Thanks for your feedback!
Alex
--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/
