Re: [PATCH v3 1/3] timespec.3type: tv_nsec is impl-def-type, glibc llong not a bug

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 4649 bytes --]

Hi!

On 1/30/23 19:38, наб wrote:
> Hi!
> 
> On Mon, Jan 30, 2023 at 02:15:50PM +0100, Alejandro Colomar wrote:
>>> Please make it
>>>
>>>     /* see below */ tv_nsec
>>>
>>> or maybe
>>>
>>>     long /* but see below */ tv_nsec
>>>
>>> (given that C23 is not a thing yet).
>> The reason why I seriously considered /*↓*/ is that it is a bit shocking to
>> the reader, which will prompt it to read the rest of the page to see what
>> the hell that is.
>>
>> I'm worried that if we make it `long` plus a comment to see below, many will
>> ignore it.
>>
>> /* see below */ with no mentions to `long` might be a reasonable
>> alternative. Maybe I'd use /* ... */
>>
>> What do y'all think about it?
> Yeah, ellipsis instead of the arrow is editorial IMO,
> and I agree with the consequences of making it type /* comment */;
> I didn't want to go full see below on it because there's three sentences
> on the page, and it'd inflate the type width in the SYNOPSIS considerably.
> 
> We already use /* ... */ for "concrete unspecified type" elsewhere;
> v3 of 1/3 below.
> 
> Best,
> -- >8 --
> n3091 accepts n3066, making it part of the next working draft and C23:
>    https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3091.doc
> 
> Update timespec.3type appropriately, largely mirroring my paper.
> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

I'll apply the following diff to your patch, if you agree:

diff --git a/man3type/timespec.3type b/man3type/timespec.3type
index 9b9e083bb..c3c69cfd2 100644
--- a/man3type/timespec.3type
+++ b/man3type/timespec.3type
@@ -16,7 +16,8 @@ .SH SYNOPSIS
  .PP
  .B struct timespec {
  .BR "    time_t     tv_sec;" "   /* Seconds */"
-.BR "    /* ... */  tv_nsec;" "  /* Nanoseconds [" 0 ", " 999\(aq999\(aq999 "] */"
+.RB "    /* ... */" "  tv_nsec;" \
+"  /* Nanoseconds [" 0 ", " 999\[aq]999\[aq]999 "] */"
  .B };
  .EE
  .SH DESCRIPTION


The /* ... */ should not be formatted, since it's not a literal (if you found it 
formatted anywhere, that's a bug; please report).
\(aq for a separator in numbers hurts (source) readability when used in hex 
numbers, so I prefer using \[aq] everywhere (I'll do a global fix soon).


Cheers,

Alex


> ---
>   man3type/timespec.3type | 49 ++++++++++++++---------------------------
>   1 file changed, 16 insertions(+), 33 deletions(-)
> 
> diff --git a/man3type/timespec.3type b/man3type/timespec.3type
> index 7cd80ce86..9b9e083bb 100644
> --- a/man3type/timespec.3type
> +++ b/man3type/timespec.3type
> @@ -15,15 +15,29 @@ Standard C library
>   .B #include <time.h>
>   .PP
>   .B struct timespec {
> -.BR "    time_t  tv_sec;" "   /* Seconds */"
> -.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> +.BR "    time_t     tv_sec;" "   /* Seconds */"
> +.BR "    /* ... */  tv_nsec;" "  /* Nanoseconds [" 0 ", " 999\(aq999\(aq999 "] */"
>   .B };
>   .EE
>   .SH DESCRIPTION
>   Describes times in seconds and nanoseconds.
> +.PP
> +.I tv_nsec
> +is of an implementation-defined signed type capable of holding the specified range.
> +Under glibc, this is usually
> +.IR long ,
> +and
> +.I long long
> +on X32.
> +It can be safely down-cast to any concrete 32-bit integer type for processing.
>   .SH STANDARDS
>   C11 and later;
>   POSIX.1-2001 and later.
> +.SH VERSIONS
> +Prior to C23,
> +.I tv_nsec
> +was
> +.IR long .
>   .SH NOTES
>   The following headers also provide this type:
>   .IR <aio.h> ,
> @@ -33,37 +47,6 @@ The following headers also provide this type:
>   .IR <sys/select.h> ,
>   and
>   .IR <sys/stat.h> .
> -.SH BUGS
> -Under glibc,
> -.I tv_nsec
> -is the
> -.I syscall
> -long,
> -though this affects only fringe architectures like X32,
> -which is ILP32, but uses the LP64 AMD64 syscall ABI.
> -In reality, the field ends up being defined as:
> -.PP
> -.in +4n
> -.EX
> -#if __x86_64__ && __ILP32__  /* == x32 */
> -    long long  tv_nsec;
> -#else
> -    long       tv_nsec;
> -#endif
> -.EE
> -.in
> -.PP
> -This is a long-standing and long-enshrined glibc bug
> -.UR https://sourceware.org/bugzilla/show_bug.cgi?id=16437
> -.I #16437
> -.UE ,
> -and an incompatible extension to the standards;
> -however, as even a 32-bit
> -.I long
> -can hold the entire
> -.I tv_nsec
> -range,
> -it's always safe to forcibly down-cast it to the standard type.
>   .SH SEE ALSO
>   .BR clock_gettime (2),
>   .BR clock_nanosleep (2),

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]