Re: [PATCH] Various pages: SYNOPSIS: Use VLA syntax in function parameters

[Ingo Schwarze <schwarze@usta.de>]

Hi Alejandro,

Alejandro Colomar wrote on Sat, Aug 27, 2022 at 02:15:32PM +0200:
> On 8/27/22 13:10, Ingo Schwarze wrote:
>> Alejandro Colomar wrote:

>>> -.BI "char *getcwd(char *" buf ", size_t " size );
>>> +.BI "char *getcwd(char " buf [ size "], size_t " size );

>> I dislike this.
>> 
>> Manual pages should show function prototypes as they really are in
>> the header file, or if the header file contains useless fluff like
>> "restrict", a shortened form showing the essence that actually matters
>> for using the API.

> Regarding restrict, it is essential to differentiate memcpy(3) and 
> memmove(3), which are otherwise identical:
> 
>      void *memmove(void *dest, const void *src, size_t n);
> 
>      void *memcpy(void *restrict dest, const void *restrict src,
>                   size_t n);

Actually, the syntax of both is identical, only the semantics differ.

That said, you are right that using memcpy(3) when memmove(3) is
required is a famous and widespread bug.  I doubt putting "restrict"
into the SYNOPSIS will discourage careless programmers from making that
mistake though.

To me, "restrict" feels like a specialized tool for people writing
compiler optimizers, not like something important enough to clutter
API documenation.

> Do you regard the (abused) VLA syntax as something much worse than the 
> use of restrict?  Or are they more or less equivalent to you?

If your implementation really contains "restrict" in the header
file and it's standardized, putting it into the SYNOPSIS seems
acceptable to me.  Not necessary though and maybe somewhat noisy
and distracting.

Putting something that is not in the implementation and/or not
in the standard into the SYNOPSIS seems much worse to me.

And invalid syntax in the SYNOPSIS is even worse than that.
For example, people may attempt to use SYNOPSIS as an example
when designing their own, private function for a similar but
not identical purpose and end up writing non-portable code,
or even code that does not compile anywhere.

They may be wrong if they blame you for that, but i doubt they
will thank you.

>> They should certainly not show something imaginary
>> that does not match reality, and even less so using invalid syntax.

> Well, not that I haven't had those thoughts, but we already use ilegal 
> syntax in some cases for good reasons.  See for example open(2):
> 
>         int open(const char *pathname, int flags);
>         int open(const char *pathname, int flags, mode_t mode);
> 
> Of course, you can't declare two conflicting prototypes like that.

This does not seem quite as horrifying as

  char *getcwd(char buf[size], size_t size);

because at least each of the prototypes is valid.

My main concern about it would be that it is likely to make some people
think (and C++ programmers in particular :-/) that there is type
checking for the third and subsequent arguments, in which case they
will be unpleasantly surprised when accidentally writing something like

  open(pathname, flags, &some_var, mode);

and finding out later that it compiled and ran just fine, but the
resulting file wasn't quite as confidential as they hoped.

Explicitly displaying the ... to indicate the variable number of
arguments, by contrast, makes it very clear that an API is almost
certainly unusually dangerous and needs to be used with especial
diligence.

Either way, certainly not quite as bad as invalid syntax inside
a prototype...

Yours,
  Ingo