Re: [PATCH 1/2] ctime.3: Use VLA notation for [as]ctime_r() buffer

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

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/