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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 2818 bytes --]

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>
---
This is in many ways a followup to the patchset that originally added
the BUGS sexion to timespec.3type, root msgid of
  <ec1dcc655184f6cdaae40ff8b7970b750434e4ef.1638123425.git.nabijaczleweli@nabijaczleweli.xyz>

For ease of reference, n3066:
  https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3066.pdf
and the relevant part of n3091 (screenshot, it's a .doc):
  https://cohost.org/nabijaczleweli/post/922578-pog-pog

2/3 and 3/3 only span the pages that matched git grep -l tv_nsec,
but that should be most of the relevant ones

 man3type/timespec.3type | 46 +++++++++++++----------------------------
 1 file changed, 14 insertions(+), 32 deletions(-)

diff --git a/man3type/timespec.3type b/man3type/timespec.3type
index 7cd80ce86..ca5533814 100644
--- a/man3type/timespec.3type
+++ b/man3type/timespec.3type
@@ -16,14 +16,27 @@ Standard C library
 .PP
 .B struct timespec {
 .BR "    time_t  tv_sec;" "   /* Seconds */"
-.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
+.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
 .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 safely be down-cast to any concrete 32-bit integer type for processing.
 .SH STANDARDS
 C11 and later;
 POSIX.1-2001 and later.
+Prior to C23
+.I tv_nsec
+was
+.IR long .
 .SH NOTES
 The following headers also provide this type:
 .IR <aio.h> ,
@@ -33,37 +46,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),
-- 
2.30.2


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

[PATCH 2/3] clock_getres.2, clock_getcpuclockid.3, pthread_getcpuclockid.3: fix tv_nsec formatting

[наб]

[-- Attachment #1: Type: text/plain, Size: 2210 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/clock_getres.2          | 8 ++++----
 man3/clock_getcpuclockid.3   | 4 ++--
 man3/pthread_getcpuclockid.3 | 2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 501c878ca..a02bea852 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -467,8 +467,8 @@ displayClock(clockid_t clock, const char *name, bool showRes)
         exit(EXIT_FAILURE);
     }
 
-    printf("%\-15s: %10jd.%03ld (", name,
-           (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+    printf("%\-15s: %10jd.%03d (", name,
+           (intmax_t) ts.tv_sec, (int) ts.tv_nsec / 1000000);
 
     days = ts.tv_sec / SECS_IN_DAY;
     if (days > 0)
@@ -486,8 +486,8 @@ displayClock(clockid_t clock, const char *name, bool showRes)
     }
 
     if (showRes)
-        printf("     resolution: %10jd.%09ld\en",
-               (intmax_t) ts.tv_sec, ts.tv_nsec);
+        printf("     resolution: %10jd.%09d\en",
+               (intmax_t) ts.tv_sec, (int) ts.tv_nsec);
 }
 
 int
diff --git a/man3/clock_getcpuclockid.3 b/man3/clock_getcpuclockid.3
index bcc2d981e..b2f2e356f 100644
--- a/man3/clock_getcpuclockid.3
+++ b/man3/clock_getcpuclockid.3
@@ -146,8 +146,8 @@ main(int argc, char *argv[])
         exit(EXIT_FAILURE);
     }
 
-    printf("CPU\-time clock for PID %s is %jd.%09ld seconds\en",
-           argv[1], (intmax_t) ts.tv_sec, ts.tv_nsec);
+    printf("CPU\-time clock for PID %s is %jd.%09d seconds\en",
+           argv[1], (intmax_t) ts.tv_sec, (int) ts.tv_nsec);
     exit(EXIT_SUCCESS);
 }
 .EE
diff --git a/man3/pthread_getcpuclockid.3 b/man3/pthread_getcpuclockid.3
index 31dd6a6ef..f481522b3 100644
--- a/man3/pthread_getcpuclockid.3
+++ b/man3/pthread_getcpuclockid.3
@@ -132,7 +132,7 @@ pclock(char *msg, clockid_t cid)
     printf("%s", msg);
     if (clock_gettime(cid, &ts) == \-1)
         handle_error("clock_gettime");
-    printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+    printf("%4jd.%03d\en", (intmax_t) ts.tv_sec, (int) ts.tv_nsec / 1000000);
 }
 
 int
-- 
2.30.2


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

[PATCH 3/3] man2/clock_getres.2, man2/clock_nanosleep.2, man2/nanosleep.2, man2/timer_settime.2, man2/timerfd_create.2, man2/utimensat.2, man3/mq_send.3, man3/pthread_tryjoin_np.3, man3/sem_wait.3: standardise on "range [0, 999999999]" for tv_nsec

[наб]

[-- Attachment #1: Type: text/plain, Size: 4099 bytes --]

There were a few wildly different formats
(some of which got the range wrong!),
settle on the sanest one

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/clock_getres.2       | 2 +-
 man2/clock_nanosleep.2    | 2 +-
 man2/nanosleep.2          | 2 +-
 man2/timer_settime.2      | 2 +-
 man2/timerfd_create.2     | 2 +-
 man2/utimensat.2          | 2 +-
 man3/mq_send.3            | 2 +-
 man3/pthread_tryjoin_np.3 | 2 +-
 man3/sem_wait.3           | 2 +-
 9 files changed, 9 insertions(+), 9 deletions(-)

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index a02bea852..dadcd6b52 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -272,7 +272,7 @@ does not refer to a valid instance of a clock object.
 .I tp.tv_sec
 is negative or
 .I tp.tv_nsec
-is outside the range [0..999,999,999].
+is outside the range [0, 999999999].
 .TP
 .B EINVAL
 The
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
index 5afc2025c..5da8d1569 100644
--- a/man2/clock_nanosleep.2
+++ b/man2/clock_nanosleep.2
@@ -158,7 +158,7 @@ The sleep was interrupted by a signal handler; see
 .B EINVAL
 The value in the
 .I tv_nsec
-field was not in the range 0 to 999999999 or
+field was not in the range [0, 999999999] or
 .I tv_sec
 was negative.
 .TP
diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
index a6f9e627f..87ac34d9e 100644
--- a/man2/nanosleep.2
+++ b/man2/nanosleep.2
@@ -106,7 +106,7 @@ again and continue with the pause.
 .B EINVAL
 The value in the
 .I tv_nsec
-field was not in the range 0 to 999999999 or
+field was not in the range [0, 999999999] or
 .I tv_sec
 was negative.
 .SH STANDARDS
diff --git a/man2/timer_settime.2 b/man2/timer_settime.2
index 29d9ed4d2..73beb411c 100644
--- a/man2/timer_settime.2
+++ b/man2/timer_settime.2
@@ -171,7 +171,7 @@ may fail with the following errors:
 .I new_value.it_value
 is negative; or
 .I new_value.it_value.tv_nsec
-is negative or greater than 999,999,999.
+is outside the range [0, 999999999].
 .SH VERSIONS
 These system calls are available since Linux 2.6.
 .SH STANDARDS
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index 5ccc165a3..4c1cc1c35 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -461,7 +461,7 @@ See NOTES.
 .I new_value
 is not properly initialized (one of the
 .I tv_nsec
-falls outside the range zero to 999,999,999).
+falls outside the range [0, 999999999]).
 .TP
 .B EINVAL
 .\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version.
diff --git a/man2/utimensat.2 b/man2/utimensat.2
index 7f43aab7b..1d9206ed0 100644
--- a/man2/utimensat.2
+++ b/man2/utimensat.2
@@ -272,7 +272,7 @@ Invalid value in
 .B EINVAL
 Invalid value in one of the
 .I tv_nsec
-fields (value outside range 0 to 999,999,999, and not
+fields (value outside range [0, 999999999], and not
 .B UTIME_NOW
 or
 .BR UTIME_OMIT );
diff --git a/man3/mq_send.3 b/man3/mq_send.3
index ae0bc74d8..239817849 100644
--- a/man3/mq_send.3
+++ b/man3/mq_send.3
@@ -123,7 +123,7 @@ was invalid, either because
 .I tv_sec
 was less than zero, or because
 .I tv_nsec
-was less than zero or greater than 1000 million.
+was outside the range [0, 999999999].
 .TP
 .B EMSGSIZE
 .I msg_len
diff --git a/man3/pthread_tryjoin_np.3 b/man3/pthread_tryjoin_np.3
index caaaa0707..5f08f1e00 100644
--- a/man3/pthread_tryjoin_np.3
+++ b/man3/pthread_tryjoin_np.3
@@ -82,7 +82,7 @@ value is invalid
 .RI ( tv_sec
 is less than 0 or
 .I tv_nsec
-is greater than 1e9).
+is outside the range [0, 999999999]).
 .TP
 .B ETIMEDOUT
 The call timed out before
diff --git a/man3/sem_wait.3 b/man3/sem_wait.3
index 788d687a7..07107426a 100644
--- a/man3/sem_wait.3
+++ b/man3/sem_wait.3
@@ -104,7 +104,7 @@ is not a valid semaphore.
 .RB ( sem_timedwait ())
 The value of
 .I abs_timeout.tv_nsecs
-is less than 0, or greater than or equal to 1000 million.
+is outside the range [0, 999999999].
 .TP
 .B ETIMEDOUT
 .RB ( sem_timedwait ())
-- 
2.30.2

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

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

[Alejandro Colomar]

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

Hey наб!

On 1/28/23 15:17, наб wrote:
> 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.
Nice! :-)

> 
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
> ---
> This is in many ways a followup to the patchset that originally added
> the BUGS sexion to timespec.3type, root msgid of
>    <ec1dcc655184f6cdaae40ff8b7970b750434e4ef.1638123425.git.nabijaczleweli@nabijaczleweli.xyz>
> 
> For ease of reference, n3066:
>    https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3066.pdf
> and the relevant part of n3091 (screenshot, it's a .doc):
>    https://cohost.org/nabijaczleweli/post/922578-pog-pog

What happened in the end with nsec_t?  Was it rejected, or are they still 
considering it?

> 
> 2/3 and 3/3 only span the pages that matched git grep -l tv_nsec,
> but that should be most of the relevant ones
> 
>   man3type/timespec.3type | 46 +++++++++++++----------------------------
>   1 file changed, 14 insertions(+), 32 deletions(-)
> 
> diff --git a/man3type/timespec.3type b/man3type/timespec.3type
> index 7cd80ce86..ca5533814 100644
> --- a/man3type/timespec.3type
> +++ b/man3type/timespec.3type
> @@ -16,14 +16,27 @@ Standard C library
>   .PP
>   .B struct timespec {
>   .BR "    time_t  tv_sec;" "   /* Seconds */"
> -.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"

I'm tempted to merge this patch.  It's sooo qute /*↓*/

Please use the digit separator \(aq for the big number.

>   .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 safely be down-cast to any concrete 32-bit integer type for processing.

Ok.

>   .SH STANDARDS
>   C11 and later;
>   POSIX.1-2001 and later.
> +Prior to C23

A comma here?

> +.I tv_nsec
> +was
> +.IR long .

Please move this to a new VERSIONS sexion.

>   .SH NOTES
>   The following headers also provide this type:
>   .IR <aio.h> ,
> @@ -33,37 +46,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.

Ok.

Cheers,

Alex

>   .SH SEE ALSO
>   .BR clock_gettime (2),
>   .BR clock_nanosleep (2),

-- 
<http://www.alejandro-colomar.es/>

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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 1954 bytes --]

Hi!

On Sun, Jan 29, 2023 at 04:48:04PM +0100, Alejandro Colomar wrote:
> On 1/28/23 15:17, наб wrote:
> > This is in many ways a followup to the patchset that originally added
> > the BUGS sexion to timespec.3type, root msgid of
> >    <ec1dcc655184f6cdaae40ff8b7970b750434e4ef.1638123425.git.nabijaczleweli@nabijaczleweli.xyz>
> > 
> > For ease of reference, n3066:
> >    https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3066.pdf
> > and the relevant part of n3091 (screenshot, it's a .doc):
> >    https://cohost.org/nabijaczleweli/post/922578-pog-pog
> What happened in the end with nsec_t?  Was it rejected, or are they still
> considering it?

n3066 (p1) was accepted, and it had nsec_t purged from n2878;
according to my archive, that's because
"nsec_t is only reserved in POSIX, not in C",
so introducing it would be a breaking change,
and it really doesn't matter
(and even my patience for standards processes is limited,
 especially when multiple Austin Group liaisons
 choose to die when you want something from them).

> > diff --git a/man3type/timespec.3type b/man3type/timespec.3type
> > index 7cd80ce86..ca5533814 100644
> > --- a/man3type/timespec.3type
> > +++ b/man3type/timespec.3type
> > @@ -16,14 +16,27 @@ Standard C library
> >   .PP
> >   .B struct timespec {
> >   .BR "    time_t  tv_sec;" "   /* Seconds */"
> > -.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> > +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> I'm tempted to merge this patch.  It's sooo qute /*↓*/
> 
> Please use the digit separator \(aq for the big number.
Applied.

> >   .SH STANDARDS
> >   C11 and later;
> >   POSIX.1-2001 and later.
> > +Prior to C23
> A comma here?
Sure.

> > +.I tv_nsec
> > +was
> > +.IR long .
> Please move this to a new VERSIONS sexion.
Added.

v2 with these notes and \(aqs in 3/3 in follow-up.

Best,
наб

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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 2298 bytes --]

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>
---
 man3type/timespec.3type | 47 +++++++++++++----------------------------
 1 file changed, 15 insertions(+), 32 deletions(-)

diff --git a/man3type/timespec.3type b/man3type/timespec.3type
index 7cd80ce86..37dc2da61 100644
--- a/man3type/timespec.3type
+++ b/man3type/timespec.3type
@@ -16,14 +16,28 @@ Standard C library
 .PP
 .B struct timespec {
 .BR "    time_t  tv_sec;" "   /* Seconds */"
-.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
+.BR "    /*\(da*/   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),
-- 
2.30.2


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

[PATCH v2 2/3] clock_getres.2, clock_getcpuclockid.3, pthread_getcpuclockid.3: fix tv_nsec formatting

[наб]

[-- Attachment #1: Type: text/plain, Size: 2210 bytes --]

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/clock_getres.2          | 8 ++++----
 man3/clock_getcpuclockid.3   | 4 ++--
 man3/pthread_getcpuclockid.3 | 2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index 501c878ca..a02bea852 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -467,8 +467,8 @@ displayClock(clockid_t clock, const char *name, bool showRes)
         exit(EXIT_FAILURE);
     }
 
-    printf("%\-15s: %10jd.%03ld (", name,
-           (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+    printf("%\-15s: %10jd.%03d (", name,
+           (intmax_t) ts.tv_sec, (int) ts.tv_nsec / 1000000);
 
     days = ts.tv_sec / SECS_IN_DAY;
     if (days > 0)
@@ -486,8 +486,8 @@ displayClock(clockid_t clock, const char *name, bool showRes)
     }
 
     if (showRes)
-        printf("     resolution: %10jd.%09ld\en",
-               (intmax_t) ts.tv_sec, ts.tv_nsec);
+        printf("     resolution: %10jd.%09d\en",
+               (intmax_t) ts.tv_sec, (int) ts.tv_nsec);
 }
 
 int
diff --git a/man3/clock_getcpuclockid.3 b/man3/clock_getcpuclockid.3
index bcc2d981e..b2f2e356f 100644
--- a/man3/clock_getcpuclockid.3
+++ b/man3/clock_getcpuclockid.3
@@ -146,8 +146,8 @@ main(int argc, char *argv[])
         exit(EXIT_FAILURE);
     }
 
-    printf("CPU\-time clock for PID %s is %jd.%09ld seconds\en",
-           argv[1], (intmax_t) ts.tv_sec, ts.tv_nsec);
+    printf("CPU\-time clock for PID %s is %jd.%09d seconds\en",
+           argv[1], (intmax_t) ts.tv_sec, (int) ts.tv_nsec);
     exit(EXIT_SUCCESS);
 }
 .EE
diff --git a/man3/pthread_getcpuclockid.3 b/man3/pthread_getcpuclockid.3
index 31dd6a6ef..f481522b3 100644
--- a/man3/pthread_getcpuclockid.3
+++ b/man3/pthread_getcpuclockid.3
@@ -132,7 +132,7 @@ pclock(char *msg, clockid_t cid)
     printf("%s", msg);
     if (clock_gettime(cid, &ts) == \-1)
         handle_error("clock_gettime");
-    printf("%4jd.%03ld\en", (intmax_t) ts.tv_sec, ts.tv_nsec / 1000000);
+    printf("%4jd.%03d\en", (intmax_t) ts.tv_sec, (int) ts.tv_nsec / 1000000);
 }
 
 int
-- 
2.30.2


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

[PATCH v2 3/3] man2/clock_getres.2, man2/clock_nanosleep.2, man2/nanosleep.2, man2/timer_settime.2, man2/timerfd_create.2, man2/utimensat.2, man3/mq_send.3, man3/pthread_tryjoin_np.3, man3/sem_wait.3: standardise on "range [0, 999\(aq999\(aq999]" for tv_nsec

[наб]

[-- Attachment #1: Type: text/plain, Size: 4612 bytes --]

There were a few wildly different formats
(some of which got the range wrong!),
settle on the sanest one,
adding thousands separators per
  <717e8fb9-9159-65f8-093e-a117c82be704@gmail.com>
  <cfda064c-b3f0-d541-bbee-e3a72c0b3cf3@gmail.com>

Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>
---
 man2/clock_getres.2       | 2 +-
 man2/clock_nanosleep.2    | 2 +-
 man2/nanosleep.2          | 4 ++--
 man2/timer_settime.2      | 2 +-
 man2/timerfd_create.2     | 2 +-
 man2/utimensat.2          | 2 +-
 man3/mq_send.3            | 2 +-
 man3/pthread_tryjoin_np.3 | 2 +-
 man3/sem_wait.3           | 2 +-
 9 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
index a02bea852..e4e7ac6e6 100644
--- a/man2/clock_getres.2
+++ b/man2/clock_getres.2
@@ -272,7 +272,7 @@ does not refer to a valid instance of a clock object.
 .I tp.tv_sec
 is negative or
 .I tp.tv_nsec
-is outside the range [0..999,999,999].
+is outside the range [0, 999\(aq999\(aq999].
 .TP
 .B EINVAL
 The
diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
index 5afc2025c..1f04adfd6 100644
--- a/man2/clock_nanosleep.2
+++ b/man2/clock_nanosleep.2
@@ -158,7 +158,7 @@ The sleep was interrupted by a signal handler; see
 .B EINVAL
 The value in the
 .I tv_nsec
-field was not in the range 0 to 999999999 or
+field was not in the range [0, 999\(aq999\(aq999] or
 .I tv_sec
 was negative.
 .TP
diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
index a6f9e627f..a708b1b96 100644
--- a/man2/nanosleep.2
+++ b/man2/nanosleep.2
@@ -66,7 +66,7 @@ The
 structure
 is used to specify intervals of time with nanosecond precision.
 .PP
-The value of the nanoseconds field must be in the range 0 to 999999999.
+The value of the nanoseconds field must be in the range [0, 999\(aq999\(aq999].
 .PP
 Compared to
 .BR sleep (3)
@@ -106,7 +106,7 @@ again and continue with the pause.
 .B EINVAL
 The value in the
 .I tv_nsec
-field was not in the range 0 to 999999999 or
+field was not in the range [0, 999\(aq999\(aq999] or
 .I tv_sec
 was negative.
 .SH STANDARDS
diff --git a/man2/timer_settime.2 b/man2/timer_settime.2
index 29d9ed4d2..ced538911 100644
--- a/man2/timer_settime.2
+++ b/man2/timer_settime.2
@@ -171,7 +171,7 @@ may fail with the following errors:
 .I new_value.it_value
 is negative; or
 .I new_value.it_value.tv_nsec
-is negative or greater than 999,999,999.
+is outside the range [0, 999\(aq999\(aq999].
 .SH VERSIONS
 These system calls are available since Linux 2.6.
 .SH STANDARDS
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index 5ccc165a3..db2e82a50 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -461,7 +461,7 @@ See NOTES.
 .I new_value
 is not properly initialized (one of the
 .I tv_nsec
-falls outside the range zero to 999,999,999).
+falls outside the range [0, 999\(aq999\(aq999]).
 .TP
 .B EINVAL
 .\" This case only checked since Linux 2.6.29, and Linux 2.2.2[78].some-stable-version.
diff --git a/man2/utimensat.2 b/man2/utimensat.2
index 7f43aab7b..b78300155 100644
--- a/man2/utimensat.2
+++ b/man2/utimensat.2
@@ -272,7 +272,7 @@ Invalid value in
 .B EINVAL
 Invalid value in one of the
 .I tv_nsec
-fields (value outside range 0 to 999,999,999, and not
+fields (value outside range [0, 999\(aq999\(aq999], and not
 .B UTIME_NOW
 or
 .BR UTIME_OMIT );
diff --git a/man3/mq_send.3 b/man3/mq_send.3
index ae0bc74d8..7c1fbb47f 100644
--- a/man3/mq_send.3
+++ b/man3/mq_send.3
@@ -123,7 +123,7 @@ was invalid, either because
 .I tv_sec
 was less than zero, or because
 .I tv_nsec
-was less than zero or greater than 1000 million.
+was outside the range [0, 999\(aq999\(aq999].
 .TP
 .B EMSGSIZE
 .I msg_len
diff --git a/man3/pthread_tryjoin_np.3 b/man3/pthread_tryjoin_np.3
index caaaa0707..d4aeb2447 100644
--- a/man3/pthread_tryjoin_np.3
+++ b/man3/pthread_tryjoin_np.3
@@ -82,7 +82,7 @@ value is invalid
 .RI ( tv_sec
 is less than 0 or
 .I tv_nsec
-is greater than 1e9).
+is outside the range [0, 999\(aq999\(aq999]).
 .TP
 .B ETIMEDOUT
 The call timed out before
diff --git a/man3/sem_wait.3 b/man3/sem_wait.3
index 788d687a7..e47ed2ace 100644
--- a/man3/sem_wait.3
+++ b/man3/sem_wait.3
@@ -104,7 +104,7 @@ is not a valid semaphore.
 .RB ( sem_timedwait ())
 The value of
 .I abs_timeout.tv_nsecs
-is less than 0, or greater than or equal to 1000 million.
+is outside the range [0, 999\(aq999\(aq999].
 .TP
 .B ETIMEDOUT
 .RB ( sem_timedwait ())
-- 
2.30.2

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

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

[Alejandro Colomar]

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

Hi наб,

On 1/29/23 17:31, наб wrote:
> 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>
> ---
>   man3type/timespec.3type | 47 +++++++++++++----------------------------
>   1 file changed, 15 insertions(+), 32 deletions(-)
> 
> diff --git a/man3type/timespec.3type b/man3type/timespec.3type
> index 7cd80ce86..37dc2da61 100644
> --- a/man3type/timespec.3type
> +++ b/man3type/timespec.3type
> @@ -16,14 +16,28 @@ Standard C library
>   .PP
>   .B struct timespec {
>   .BR "    time_t  tv_sec;" "   /* Seconds */"
> -.BR "    long    tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> +.BR "    /*\(da*/   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.

Ahh, now I remember!  I had something in mind this morning, that I forgot when 
writing the email.

The thing is, mathematically, the term for this would be interval, rather than 
range.

I started using it in the following code:

<https://github.com/shadow-maint/shadow/pull/624#issuecomment-1384029138>
<https://github.com/shadow-maint/shadow/pull/624/files#diff-de2f8567ced0ae94dd9c780a02947cda28a6adeb61c8cd75d1645c93567bcc6fR103>
<http://www.alejandro-colomar.es/src/alx/alx/libc/libc-rand.git/tree/include/c/rand/csrand/csrand_uniform.h>

Would you mind using interval here?

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

If the C standards and POSIX don't want to add a type for it, let us disagree 
with their decission.

Let's add a bug:

There's no portable way to declare to pointer to tv_nsec, since you never know 
for sure if it will be long* or llong*.

Do you agree?

Cheers,

Alex

>   .SH SEE ALSO
>   .BR clock_gettime (2),
>   .BR clock_nanosleep (2),

-- 
<http://www.alejandro-colomar.es/>

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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 2853 bytes --]

Hi!

On Sun, Jan 29, 2023 at 05:41:56PM +0100, Alejandro Colomar wrote:
> On 1/29/23 17:31, наб wrote:
> > +.PP
> > +.I tv_nsec
> > +is of an implementation-defined signed type capable of holding the specified range.
> Would you mind using interval here?
I don't think it makes sense here? Since (a) this is the standards
phrasing and (b) the /range/ of values is represented by an interval.

We could just as well say "all integers between 0 and 999`999`999",
or "integers at least 0 and smaller 1e9", which are both identical,
but aren't intervals per se. Or consider a similar case,
where the range would be "[0, 2^31-1] ∪ {EOF}" ‒
you wouldn't call that an interval, but it's a valid set expression;
timespec.3type is just a degenerate case.

In general, we're concerned with the logical object here
("the domain" or, well "range [of values]"),
not the implementation detail ("it's spelled with an interval").

Plus, I'd never search for "interval",
but most people would probably grep for "range",
because that's the sanest spelling.

> > -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.
> If the C standards and POSIX don't want to add a type for it, let us
> disagree with their decission.
Let's not. This is valid /right now/ in no-flag (so "gnu18"?)
Clang trunk and bullseye GCC:
-- >8 --
$ cc -Wall -Wextra a.c
$ cat a.c
#include <time.h>

static void nsecify(typeof((struct timespec){}.tv_nsec) * n) {
        *n *= 2;
}

int main() {
        struct timespec q = {};
        __auto_type w = &q.tv_nsec;
        nsecify(w);
}
-- >8 --

And in C23 you'll be able to s/__auto_type/auto/.

> Let's add a bug:
> 
> There's no portable way to declare to pointer to tv_nsec, since you never
> know for sure if it will be long* or llong*.

Again, C23 has typeof() (kinda like decltype()), and on Clang trunk
  $ cc -Wall -Wextra a.c -std=c2x
already compiles cleanly;
the "portable way to declare a pointer to tv_nsec"
is to spell it exactly as "i want a pointer to timespec::tv_nsec",
which is even better than a single-use typedef.

Best,
наб

https://twitter.com/__phantomderp/status/1619027523257667584
(that's the C standard project editor shitposting; it's a glamorous age)

https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3054.pdf
already has typeof and
https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3079.htm
has the latest notes on auto, which n3091 marks as "Accepted with
comment: wording from N3079 with editorial corrections."

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

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

[Jakub Wilk]

* Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-29 16:48:
>>+.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
>
>I'm tempted to merge this patch.  It's sooo qute /*↓*/

I want man pages legible, not cute. Please make it

   /* see below */ tv_nsec

or maybe

   long /* but see below */ tv_nsec

(given that C23 is not a thing yet).

-- 
Jakub Wilk

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

[Alejandro Colomar]

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

Hi!

On 1/30/23 03:05, наб wrote:
> Hi!
> 
> On Sun, Jan 29, 2023 at 05:41:56PM +0100, Alejandro Colomar wrote:
>> On 1/29/23 17:31, наб wrote:
>>> +.PP
>>> +.I tv_nsec
>>> +is of an implementation-defined signed type capable of holding the specified range.
>> Would you mind using interval here?
> I don't think it makes sense here? Since (a) this is the standards
> phrasing and (b) the /range/ of values is represented by an interval.

Makes sense.

> 
> We could just as well say "all integers between 0 and 999`999`999",
> or "integers at least 0 and smaller 1e9", which are both identical,
> but aren't intervals per se. Or consider a similar case,
> where the range would be "[0, 2^31-1] ∪ {EOF}" ‒
> you wouldn't call that an interval, but it's a valid set expression;
> timespec.3type is just a degenerate case.

I just checked again, and I was confused by the statistics definition of range, 
which seems to be more available in Big Search Engine.

There's a second definition which matches this, which I didn't find last time.

<https://sciencing.com/what-range-mathematics-4865897.html>

> 
> In general, we're concerned with the logical object here
> ("the domain" or, well "range [of values]"),
> not the implementation detail ("it's spelled with an interval").
> 
> Plus, I'd never search for "interval",
> but most people would probably grep for "range",
> because that's the sanest spelling.

:)

> 
>>> -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.
>> If the C standards and POSIX don't want to add a type for it, let us
>> disagree with their decission.
> Let's not. This is valid /right now/ in no-flag (so "gnu18"?)
> Clang trunk and bullseye GCC:
> -- >8 --
> $ cc -Wall -Wextra a.c
> $ cat a.c
> #include <time.h>
> 
> static void nsecify(typeof((struct timespec){}.tv_nsec) * n) {

If I see such a function declarator, I'ma cry.

>          *n *= 2;
> }
> 
> int main() {
>          struct timespec q = {};
>          __auto_type w = &q.tv_nsec;

Please take off my eyes. :P

I love auto, but it belongs to type-generic macros, IMO.

>          nsecify(w);
> }
> -- >8 --
> 
> And in C23 you'll be able to s/__auto_type/auto/.

In the end we got it!
I hope GCC addresses this, cause auto still means the old thing even in gnu2x mode.

> 
>> Let's add a bug:
>>
>> There's no portable way to declare to pointer to tv_nsec, since you never
>> know for sure if it will be long* or llong*.
> 
> Again, C23 has typeof() (kinda like decltype()), and on Clang trunk
>    $ cc -Wall -Wextra a.c -std=c2x
> already compiles cleanly;
> the "portable way to declare a pointer to tv_nsec"
> is to spell it exactly as "i want a pointer to timespec::tv_nsec",
> which is even better than a single-use typedef.

You got me; it's portable.  I'd port it to hell, but, it's portable.

> 
> Best,
> наб
> 
> https://twitter.com/__phantomderp/status/1619027523257667584
> (that's the C standard project editor shitposting; it's a glamorous age)

Oh, such a glorious age it is! :)

It seems my shots at nullptr have failed :(

> 
> https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3054.pdf
> already has typeof and
> https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3079.htm
> has the latest notes on auto, which n3091 marks as "Accepted with
> comment: wording from N3079 with editorial corrections."

Cheers,

Alex

-- 
<http://www.alejandro-colomar.es/>

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

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

[Alejandro Colomar]

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

Hi Jakub,

On 1/30/23 08:08, Jakub Wilk wrote:
> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-29 16:48:
>>> +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
>>
>> I'm tempted to merge this patch.  It's sooo qute /*↓*/
> 
> I want man pages legible, not cute.

I know, I know.

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

Cheers,

Alex

> 

-- 
<http://www.alejandro-colomar.es/>

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

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

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 1412 bytes --]

Hi Alex,

At 2023-01-30T14:15:50+0100, Alejandro Colomar wrote:
> On 1/30/23 08:08, Jakub Wilk wrote:
> > * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-29 16:48:
> > > > +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
> > > 
> > > I'm tempted to merge this patch.  It's sooo qute /*↓*/
> > 
> > I want man pages legible, not cute.
> 
> I know, I know.
> 
> > 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.

Even more shocking will be 'v', which is what it will degrade to on
ASCII, ISO 8859, and code page 1047 terminals.  On top of being
startling, it will look simply like an error.

> I'm worried that if we make it `long` plus a comment to see below,
> many will ignore it.

That's on them.  "/* see below */" means what it says.  A person cannot
reasonably claim they weren't warned.

> /* see below */ with no mentions to `long` might be a reasonable
> alternative. Maybe I'd use /* ... */
> 
> What do y'all think about it?

I think

long /* see below */ tv_nsec;

meets the requirements at issue.

Regards,
Branden

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

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

[Alejandro Colomar]

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

Hi Branden!

On 1/30/23 14:50, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2023-01-30T14:15:50+0100, Alejandro Colomar wrote:
>> On 1/30/23 08:08, Jakub Wilk wrote:
>>> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-29 16:48:
>>>>> +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"
>>>>
>>>> I'm tempted to merge this patch.  It's sooo qute /*↓*/
>>>
>>> I want man pages legible, not cute.
>>
>> I know, I know.
>>
>>> 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.
> 
> Even more shocking will be 'v', which is what it will degrade to on
> ASCII, ISO 8859, and code page 1047 terminals.  On top of being
> startling, it will look simply like an error.

Makes sense.

> 
>> I'm worried that if we make it `long` plus a comment to see below,
>> many will ignore it.
> 
> That's on them.  "/* see below */" means what it says.  A person cannot
> reasonably claim they weren't warned.
> 
>> /* see below */ with no mentions to `long` might be a reasonable
>> alternative. Maybe I'd use /* ... */
>>
>> What do y'all think about it?
> 
> I think
> 
> long /* see below */ tv_nsec;
> 
> meets the requirements at issue.

I think so.

Cheers,

Alex

> 
> Regards,
> Branden

-- 
<http://www.alejandro-colomar.es/>

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

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 3426 bytes --]

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>
---
 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),
-- 
2.30.2

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

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

[Brian Inglis]

On Mon, 30 Jan 2023 14:54:39 +0100, Alejandro Colomar wrote:
> On 1/30/23 14:50, G. Branden Robinson wrote:
>> At 2023-01-30T14:15:50+0100, Alejandro Colomar wrote:
>>> On 1/30/23 08:08, Jakub Wilk wrote:
>>>> * Alejandro Colomar <alx.manpages@gmail.com>, 2023-01-29 16:48:
>>>>>> +.BR "    /*\(da*/   tv_nsec;" "  /* Nanoseconds [" 0 ", " 999999999 "] */"

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

>> Even more shocking will be 'v', which is what it will degrade to on
>> ASCII, ISO 8859, and code page 1047 terminals.  On top of being
>> startling, it will look simply like an error.

>>> I'm worried that if we make it `long` plus a comment to see below,
>>> many will ignore it.

>> That's on them.  "/* see below */" means what it says.  A person cannot
>> reasonably claim they weren't warned.

>> I think
>> long /* see below */ tv_nsec;
>> meets the requirements at issue.

The last POSIX 202x Issue 8 Draft 2.1 2021-08 says under B.2.8.5 Clocks and 
Timers - • Data Definitions for Clocks and Timers from lines numbered 121835ff:

"Time values are represented in the timespec structure.
The tv_sec member is of type time_t so that this member is compatible
with time values used by POSIX.1 functions and the ISO C standard.
The tv_nsec member is a *signed long* in order to simplify and clarify
code that decrements or finds differences of time values.
Note that because 1 billion (number of nanoseconds per second) is less
than half of the value representable by a signed 32-bit value, it is
always possible to add two valid fractional seconds represented as
integral nanoseconds without overflowing the signed 32-bit value."

and other mentions repeat its 32-bitness, disallow values < 0 or >= 1Mi, laud 
simplicity of arithmetic, and eschew binary fraction representations!

More recent discussions about implementation-defined type start from the 
publicly available archive and mention N2878:

https://www.mail-archive.com/austin-group-l%40opengroup.org/msg09706.html

with replies:

"The Linux issue raised there has been discussed here in the past (2014) and was 
considered simply a bug that either glibc or the kernel should fix."

"(There are other reasons why the motivation for the change seems weak, such as 
that the primary motivating example given is to facilitate working around a 
Linux kernel issue that was fixed five years ago.)"

"...suggestion that perhaps changing this type might be acceptable is being 
taken as approval from the AG that such a change should go into C2x. ..., I 
propose to refute this during the upcoming ballot resolution meeting unless 
someone can persuade me I'm wrong!"

"In any case, if C23 changes it to nsec_t and we decide we want it to remain a 
long in POSIX, we can simply require that nsec_t is defined as a long in Issue 9."

"If that's the proposal, then I agree with you, that's relatively harmless for 
POSIX code (slightly more difficult for strict C code, and they should certainly 
be adding a PRI macro to inttypes.h - all invented printable types should have 
at least one such a macro defined).
But if the proposal is to change it to int32_t (or worse uint32_t) then that 
would be a real problem - despite 32 bits clearly being enough to represent a 
count of nanoseconds within one second (had the tv_nsec field been defined that 
way originally, that would have been OK, but it cannot be changed into that now)."

WG14 documents repeat the long-ness but have little discussion from 2011 drafts 
until N2878 and N3066.

Perhaps some more discussion between committee members who are Linux 
implementers and/or representatives on other/both standards bodies (e.g. liaison 
Nick), could help resolve this discrepancy, before one gets frozen in a position 
that some other can not conform to?

-- 
Take care. Thanks, Brian Inglis			Calgary, Alberta, Canada

La perfection est atteinte			Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter	not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer	but when there is no more to cut
			-- Antoine de Saint-Exupéry

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

[Alejandro Colomar]

[-- 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 --]

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

[наб]

[-- Attachment #1: Type: text/plain, Size: 947 bytes --]

On Sun, Feb 05, 2023 at 04:39:49PM +0100, Alejandro Colomar wrote:
> I'll apply the following diff to your patch, if you agree:
> 
> On 1/30/23 19:38, наб wrote:
> 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
Sure, go wild.

> The /* ... */ should not be formatted, since it's not a literal (if you
> found it formatted anywhere, that's a bug; please report).
There's .B "#define EOF  /* ... */" in man3const/EOF.3const,
but besides that, all are in fR, yeah.

наб

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

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

[Alejandro Colomar]

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



On 2/5/23 16:49, наб wrote:
> On Sun, Feb 05, 2023 at 04:39:49PM +0100, Alejandro Colomar wrote:
>> I'll apply the following diff to your patch, if you agree:
>>
>> On 1/30/23 19:38, наб wrote:
>> 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
> Sure, go wild.
> 
>> The /* ... */ should not be formatted, since it's not a literal (if you
>> found it formatted anywhere, that's a bug; please report).
> There's .B "#define EOF  /* ... */" in man3const/EOF.3const,
> but besides that, all are in fR, yeah.

Thanks!  Fixed.  And I already applied the global change to use \[aq] and \[dq].

> 
> наб

Cheers,

Alex

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

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