svn commit: r317681 - head/share/man/man7

[Bruce Evans]

On Tue, 2 May 2017, Konstantin Belousov wrote:

> On Wed, May 03, 2017 at 02:35:17AM +1000, Bruce Evans wrote:
>> On Tue, 2 May 2017, Konstantin Belousov wrote:
>>
>>> Log:
>>>  Document time_t size.
>>>
>>> Modified: head/share/man/man7/arch.7
>>> ==============================================================================
>>> --- head/share/man/man7/arch.7	Tue May  2 14:52:28 2017	(r317680)
>>> +++ head/share/man/man7/arch.7	Tue May  2 14:52:35 2017	(r317681)
>>> @@ -47,27 +47,27 @@ On all supported architectures,
>>> .It float Ta 4
>>> .It double Ta 8
>>> .El
>>> -.Bl -column -offset indent "Sy Architecture" "Sy sizeof(void *)" "Sy sizeof(long double)"
>>> -.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double)
>>> ...
>>> +.Bl -column -offset indent "Sy Architecture" "Sy sizeof(void *)" "Sy sizeof(long double)" "Sy sizeof(time_t)"
>>> +.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double) Ta Sy sizeof(time_t)
>>> +.It amd64       Ta 8 Ta 16 Ta 8
>>> +.It arm         Ta 4 Ta  8 Ta 8
>>
>> Verbose types mess up the formatting of man pages too.
>>
>> The header is obviously too long.  -current man misformats it to 91 columns
>> on 80-column terminals.  FreeBSD-5 man respects COLUMNS, but mangles the
>> header more completely to do this (1).
>
> I removed excessive sizeof(), which fixed width.

Hmm.  It leaves no mention of the scale.  More below.

> diff --git a/share/man/man7/arch.7 b/share/man/man7/arch.7
> index 1ce397a303e..73552d60209 100644
> --- a/share/man/man7/arch.7
> +++ b/share/man/man7/arch.7
> @@ -47,8 +47,10 @@ On all supported architectures,
> .It float Ta 4
> .It double Ta 8
> .El
> -.Bl -column -offset indent "Sy Architecture" "Sy sizeof(void *)" "Sy sizeof(long double)" "Sy sizeof(time_t)"
> -.It Sy Architecture Ta Sy sizeof(void *) Ta Sy sizeof(long double) Ta Sy sizeof(time_t)
> +.Pp
> +Machine-depended type's sizes:
> +.Bl -column -offset indent "Sy Architecture" "Sy void *" "Sy long double" "Sy time_t"
> +.It Sy Architecture Ta Sy void * Ta Sy long double Ta Sy time_t

Remove the buggy Sy's too.

> .It amd64       Ta 8 Ta 16 Ta 8
> .It arm         Ta 4 Ta  8 Ta 8
> .It armeb       Ta 4 Ta  8 Ta 8

It would be good to mention that the type of time_t is signed somewhere.
There is a whole column for the signedess of char in another table.
Signedness can be given consisely using some markup like -8 or 8- for
signed.  The scale (often bytes or bits) could be given similarly.  E.g,
8-B could mean signed 8 bits and 80.b could mean 80 bits floating pint.

The Page Size table says "Page Sizes" redundantly in 1 column but doesn't
gives units, and depends on everyone knowing that 4K is real K and bytes.

The Floating Point table already doesn't say "sizeof()" in the header but
gives a lot of details including units in some cases in the values.  The
long double in the table that you changed would be better placed in the
FP table, except it is short of space too.  The size info for a long double
on {amd64,i386} is in 2 tables in different incomplete forms:
- first table gives sizes {16, 12} with no mention of either sizes or units;
   these are object sizes in bytes
- second table gives values {80, 80} with no mention of sizes but mention of
   bits; these are the unpadded object/register sizes (not really available
   in C), expressed in different units.  This column in the table is mostly
   about the precision.  It says "double precision" in some places, "identical
   to double" in others, and "quad precision" for arm64 and sparc64 ("hard"
   for sparc64 is broken.  sparc64 can have either, but the default is soft
   since hard it is rearely or never implemented in hardware and is emulated
   even more slowly by doing it softly in trap handlers).  The 80's for
   amd64 and i386 are don't give the precision like the others.  The precision
   is 64 bits, and the 80-bit size is not really available in C.

   Better table entries would be something like

       (hard | soft), (8 | 10 | 12 | 16) bytes, (53 | 64 | 113) bit precision

   or for the longest case "hard, 16 bytes, 113 bit precision".  There is
   just enough space for this after removing the Sy's.  I don't like the
   duplication in this.  So better go back to "identical to double" where
   it applies, and apply it more.  Double is described as just hard or soft
   with no mention that the precision is always 53 bits (this should be
   in the ealier table of MI sizes).  Long double is then the same on some
   arches.

arm64 doesn't have an _fpmath.h for it in libc, so I don't see how it
can have the soft quad precision claimed in the table.  Similarly in
msun/arm/Makefile.inc.

riscv has an _fpmath.h stating quad precision, but isn't in any table in
arch.7.  This _fpmath.h seems quite buggy, with inconsistent commenting
out and macros not matching the struct, so I don't see how it can work
either.  msun/riscv/Makefile.inc claims 113 bits, and the struct is
consistent with this,  but the macros consistent with this are commented
out, so I don't see how it can compile.

aarch64 is like riscv except its _fpmath.h seems to be correct.

Bruce