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> --- 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:
signature.asc
Description: PGP signature
