Various pages: SYNOPSIS: Use VLA syntax in function parameters

Various pages: SYNOPSIS: Use VLA syntax in function parameters

The WG14 charter for C23 added one principle to the ones in
previous standards:

[
15.  Application Programming Interfaces (APIs) should be
self-documenting when possible.  In particular, the order of
parameters in function declarations should be arranged such that
the size of an array appears before the array.  The purpose is to
allow Variable-Length Array (VLA) notation to be used. This not
only makes the code's purpose clearer to human readers, but also
makes static analysis easier.  Any new APIs added to the Standard
should take this into consideration.
]

ISO C doesn't allow using VLA syntax when the parameter used for
the size of the array is declared _after_ the parameter that is a
VLa.  That's a minor issue that could be easily changed in the
language without backwards-compatibility issues, and in fact it
seems to have been proposed, and not yet discarded, even if it's
not going to change in C23.

Since the manual pages SYNOPSIS are not bounded by strict C legal
syntax, but we already use some "tricks" to try to convey the most
information to the reader even if it might not be the most legal
syntax, we can also make a small compromise in this case, using
illegal syntax (at least not yet legalized) to add important
information to the function prototypes.

If we're lucky, compiler authors, and maybe even WG14 members, may
be satisfied by the syntax used in these manual pages, and may
decide to implement this feature to the language.

It seems to me a sound syntax that isn't ambiguous, even if it
deviates from the common pattern in C that declarations _always_
come before use.  But it's a reasonable tradeoff.

This change will make the contract between the programmer and the
implementation clearer just by reading a prototype.  For example,

  size_t strlcpy(char *restrict dst, const char *restrict src,
                 size_t size);

    vs

  size_t strlcpy(char dst[restrict .size], const char *restrict src,
                 size_t size);

the second prototype above makes it clear that the 'dst' buffer
will be safe from overflow, but the 'src' one clearly needs to be
NUL-terminated, or it might cause UB, since nothing tells the
function how long it is.

Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2611.htm>
Cc: Ingo Schwarze <schwarze@openbsd.org>
Cc: JeanHeyd Meneide <wg14@soasis.org>
Cc: Martin Uecker <uecker@tugraz.at>
Cc: <gcc@gcc.gnu.org>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>