Re: [RFC] man7/system_data_types.7: Document [unsigned] __int128

[Jonathan Wakely <jwakely.gcc@gmail.com>]

On Thu, 1 Oct 2020 at 12:24, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hi Jonathan,
>
> On 2020-10-01 12:50, Jonathan Wakely wrote:
> >> Ok,  I thought that GCC is part of the GNU project, but I don't know how
> >> much...
> >> I'll use "When using GCC," :)
> >
> > It is, but the GNU project is a large organisation, and has nothing to
> > say about non-standard types defined by GCC. Just because GCC is part
> > of a larger proejct, doesn't mean the entire project defines
> > something.
>
>
> Ok.
> >>   >>         Conforming to: GCC 4.6.0 and later.
> >>   >
> >>   > It doesn't conform to anything, shouldn't this say "This type is a GNU
> >>   > extension." or just "This type is an extension." ?
> >>
> >> That's what I had first: "Conforming to: GCC extension"
> >> Then I thought that I could include the version information,
> >> so I changed it to that.
> >>
> >> Maybe "GCC extension (since GCC 4.6.0)" would be better?
> >
> > I don't think that information belongs in the Conforming To section at
> > all. The version that added the type is nothing to do with
> > conformance, because it's an extension and there is nothing to conform
> > to.
> >
> > Look at 'man clock_gettime' for comparison. It has a VERSIONS section
> > and some individual constants are annotated with "(since Linux
> > 2.6.12)". That seems more appropriate for annotating individual types
> > within this man page which are not universally available.
> >
>
>
> Thank you!
>
> Updated:
>
> [[
> __int128
>        A signed integer type of a fixed width of exactly 128 bits.
>
>        When  using  GCC, it is supported only for targets which have an
>        integer mode wide enough to hold 128 bits.

I'm not sure "integer mode" is useful here. It's barely useful in the
GCC docs (it's an internal implementation detail of GCC, so not very
useful for end users). Outside the context of the GCC manual it's even
less likely to mean anything to users of this documentation.

Maybe just "supported only for targets where the compiler is able to
generate efficient code for 128-bit arithmetic" or something like
that. Maybe somebody else can suggest something better.


>
>        Versions: GCC 4.6.0 and later.
>
>        Conforming to: GCC extension.
>
>        Notes: This type is available without including any header.
>
>        Bugs: It is not possible to express an integer constant of  type
>        __int128  in  implementations  where  long long is less than 128
>        bits wide.
>
>        See also the intmax_t, intN_t and  unsigned  __int128  types  in
>        this page.
> ]]
>
> Just one more thing:
> Would you say "GCC extension" or "GNU extension"?

Good question. It's not specific to GCC, because other compilers also
define it, so maybe neither is appropriate.

Maybe openpty(3) is a suitable example to use, it says "CONFORMING TO
These are BSD functions, present in glibc. They are not standardized
in POSIX."

So maybe something like "This is a non-standard extension, present in
GCC. It is not standardized in C or POSIX." Again, maybe somebody else
has a better suggestion.