Skip to contentSkip to conversation

"VLA" syntax in synopses

DISCUSSION Alejandro Colomar 2 participants 2 messages Sep 6, 2023 1 message not in the archive Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

lore
Share & tools
lore

A message that is not in the archive (sent off-list or not yet received): 20230906150038.783acf81@tauner-t14s

#1 lore raw

Hi Stefan,

Quoted 5 lines · Stefan Tauner

Hi,

last year a new syntax to indicate the (minimum) length of parameter arrays has been introduced to many function synposes with this commit:
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=c64cd13e002561c6802c6a1a1a8a640f034fea70

And these too:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=1eed67e75deff662dffce3195e55e608809eaafd>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=77f31ff920bc0abdf73ee4ece808ba4eeeff90a4>

Quoted 7 lines

The additional information is great but WTF is the "."? I have asked a few C-programming colleagues and skimmed through the c23 draft to no avail. Then I looked up the respective thread on the ML and there seems to be astonishingly little arguing about introducing such a new syntax that is not included in the C language.

Quoted 9 lines

I've been teaching C at university level for almost 10 years and I think the dot is profoundly confusing to most readers and thus is actually harmful in documentation context.
Of course it's not code but "just" documentation but its syntax is so similar that every C coder would be stumbled at least the first time they see it - unlike the case w/o the dot, which is legal C. I'd not add the static keyword though due to brevity but I would have strongly advocated against the dot if I'd have known earlier - but maybe I am alone with that opinion?

Thanks for your feedback!

We discussed the different options, and there seem to be two ways to do
it: legal C, or what we did:

"legal" C:

     char *fgets(char s[restrict size], int size, FILE *restrict stream);

current manual:

     char *fgets(char s[restrict .size], int size, FILE *restrict stream);

The problem with the "legal" syntax, is that it doesn't mean what we want it to mean. Let's compile a couple of files to see.

    $ cat a.c 
    void foo(char s[n], int n);
    $ cc -Wall -Wextra -c a.c 
    a.c:1:17: error: ‘n’ undeclared here (not in a function)
        1 | void foo(char s[n], int n);
          |                 ^
    $ cat b.c 
    int n = 3;
    void foo(char s[n], int n);
    $ cc -Wall -Wextra -c b.c 

So, I we decided to go with an extension to the language, which doesn't mean anything legal yet, and we can give it the precise meaning that we want. This extension is currently not supported by any compiler, but we're discussing the addition to GCC. The conversation was paused for a few months, as I wanted to have more feedback, and time to think, but I'll soon contact GCC developers again to continue the discussion.

Cheers,
Alex

Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
#2 lore raw

[Add an address that doesn't fail]

Quoted 68 lines · Alejandro Colomar

Hi Stefan,

Quoted 5 lines · Stefan Tauner

Hi,

last year a new syntax to indicate the (minimum) length of parameter arrays has been introduced to many function synposes with this commit:
https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=c64cd13e002561c6802c6a1a1a8a640f034fea70

And these too:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=1eed67e75deff662dffce3195e55e608809eaafd>
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/commit/?id=77f31ff920bc0abdf73ee4ece808ba4eeeff90a4>

Quoted 7 lines

The additional information is great but WTF is the "."? I have asked a few C-programming colleagues and skimmed through the c23 draft to no avail. Then I looked up the respective thread on the ML and there seems to be astonishingly little arguing about introducing such a new syntax that is not included in the C language.

Quoted 9 lines

I've been teaching C at university level for almost 10 years and I think the dot is profoundly confusing to most readers and thus is actually harmful in documentation context.
Of course it's not code but "just" documentation but its syntax is so similar that every C coder would be stumbled at least the first time they see it - unlike the case w/o the dot, which is legal C. I'd not add the static keyword though due to brevity but I would have strongly advocated against the dot if I'd have known earlier - but maybe I am alone with that opinion?

Thanks for your feedback!

We discussed the different options, and there seem to be two ways to do
it: legal C, or what we did:

"legal" C:

     char *fgets(char s[restrict size], int size, FILE *restrict stream);

current manual:

     char *fgets(char s[restrict .size], int size, FILE *restrict stream);

The problem with the "legal" syntax, is that it doesn't mean what we want it to mean. Let's compile a couple of files to see.

    $ cat a.c 
    void foo(char s[n], int n);
    $ cc -Wall -Wextra -c a.c 
    a.c:1:17: error: ‘n’ undeclared here (not in a function)
        1 | void foo(char s[n], int n);
          |                 ^
    $ cat b.c 
    int n = 3;
    void foo(char s[n], int n);
    $ cc -Wall -Wextra -c b.c 

So, I we decided to go with an extension to the language, which doesn't mean anything legal yet, and we can give it the precise meaning that we want. This extension is currently not supported by any compiler, but we're discussing the addition to GCC. The conversation was paused for a few months, as I wanted to have more feedback, and time to think, but I'll soon contact GCC developers again to continue the discussion.

Cheers,
Alex

Signature · 2 lines
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5