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

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

On Thu, 1 Oct 2020 at 11:14, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hi Jonathan,
>
> On 2020-10-01 11:57, Jonathan Wakely wrote:
>  > On Thu, 1 Oct 2020 at 10:26, Alejandro Colomar via Gcc
> <gcc@gcc.gnu.org> wrote:
>  >>
>  >> Hi,
>  >>
>  >> I'm documenting the system data types in the man-pages,
>  >> and I was writing now about these types.
>  >>
>  >> I'm showing below both the rendered output and the source I have
> right now.
>  >>
>  >> Would you add anything to it?
>  >>
>  >> And I have some questions:
>  >>
>  >> Is 'signed __int128' a valid thing,
>  >> and if so is it completely equivalent to '__int128'?
>  >
>  > Yes.
>  >
>  >> Is the GCC version correct?
>  >>
>  >> There's no implementation where 'long long' is 128 bits yet, right?
>  >
>  > Right.
>  >
>  >> Thanks,
>  >>
>  >> Alex
>  >>
>  >> Rendered output:
>  >> [[
>  >> __int128
>  >>         A signed integer type of a fixed width of exactly 128 bits.
>  >>
>  >>         According to GNU, it is supported only for targets which have an
>  >>         integer mode wide enough to hold 128 bits.
>  >
>  > "According to GNU"? Should that be GCC?
>  >
>  > The GNU project doesn't have anything to say about it.
>  >
>  > Maybe just "When using GCC, it is supported only ..."
>
> 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.

>  >
>  >
>  >>
>  >>         Bugs: It is not possible to express an integer constant of  type
>  >>         __int128  in  implementations  where  long long is less than 128
>  >>         bits wide.
>  >>
>  >>         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.




>  >
>  >>
>  >>         Notes: This type is available without including any header.
>  >>
>  >>         See also the intmax_t, intN_t and  unsigned  __int128  types  in
>  >>         this page.
>  >
>  > Why would this type refer to intmax_t?
>  >
>
> Because 'intmax_t' has a bug
> (actually I know GCC rejected the bug report,
> but the problem is still there and users should be informed about this)
> which is related to __int128.
>
> Here is the rendered intmax_t:
>
> intmax_t
>        Include: <stdint.h>.  Alternatively, <inttypes.h>.
>
>        A  signed  integer type capable of representing any value of any
>        signed integer type supported by the implementation.   According
>        to  the C language standard, it shall be capable of storing val-
>        ues in the range [INTMAX_MIN, INTMAX_MAX].
>
>        The macro INTMAX_C() expands its argument to an integer constant
>        of type intmax_t.
>
>        The  length  modifier  for  intmax_t  for  the printf(3) and the
>        scanf(3) families of functions is j; resulting commonly  in  %jd
>        or %ji for printing intmax_t values.
>
>        Bugs:  intmax_t  is not large enough to represent values of type
>        __int128 in implementations where __int128 is defined  and  long
>        long is less than 128 bits wide.

OK, makes sense.