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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxxxxxxxx>

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: OpenPGP_signature
Description: OpenPGP digital signature


[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux