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

From: Alejandro Colomar <colomar.6.4.3@gmail.com>
To: Jonathan Wakely <jwakely.gcc@gmail.com>,
	"gcc@gcc.gnu.org" <gcc@gcc.gnu.org>
Cc: linux-man <linux-man@vger.kernel.org>,
	"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>
Subject: Re: [RFC] man7/system_data_types.7: Document [unsigned] __int128
Date: Thu, 1 Oct 2020 12:14:21 +0200	[thread overview]
Message-ID: <5ed7272e-1c81-d1f5-6a54-0fee4270199e@gmail.com> (raw)
In-Reply-To: <CAH6eHdSHEjjjDtBCFO93NXb3bCGtYg6L35injf6pz3bMoL=3Fw@mail.gmail.com>

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," :)

 >
 >
 >>
 >>         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?

 >
 >>
 >>         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.

       Conforming to: C99 and later; POSIX.1-2001 and later.

       See also the uintmax_t type in this page.

Thanks,

Alex