Re: [RFC v2] system_data_types.7: Draft v2

[Alejandro Colomar <colomar.6.4.3@gmail.com>]

Hi Michael,

On 9/14/20 5:00 PM, Michael Kerrisk (man-pages) wrote:
> Small misunderstanding here, bu the way. I meant: after merging 
> the lists, sort by identifier name. Thus:
> 
> union sigval
> suseconds_t
> time_t
> timer_t
> struct timespec
> struct timeval

OK.

>> BTW, would you also add "struct-" and "union-" link pages?:
>>
>> man3/struct-timespec.3   |   1 +
>> man3/timespec.3          |   1 +
>>
>> instead of
>>
>> man3/timespec.3          |   1 +
> 
> I think just one link: the name of the type (without any
> "struct" or "union")

OK.

>> +.TP
>> +.BI "struct " timeval
>> +.IP
>> +Include:
>> +.I <sys/time.h>
> 
> or <sys/select.h>

True.

> (Really, a PDF copy of the standard is gpoing to help...)

I already have a login, and it works, but when I try to download the PDF
(just after accepting terms and conditions in downloads), another login
prompt appears and I can't log in that one.  I'll email them.

But for now I can live with the HTML version.

> 
>> +.IP
>> +.EX
>> +struct timeval {
>> +    time_t      tv_sec;  /* Seconds */
>> +    suseconds_t tv_usec; /* Microseconds */
>> +};
>> +.EE
>> +.IP
>> +Describes times in seconds and microseconds.
> 
> According to POSIX, this shall be a signed integer type.

???

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> 
> I think there are several in the following list that should be removed...

Probably.  I'll have a look at them later.

> 
>> +.BR adjtimex (2),
>> [...]
>> +.BR socket (7)
>> +.TP
>> +.I suseconds_t
>> +.IP
>> +Include:
>> +.I <sys/types.h>
>> +.IP
>> +Used for time in microseconds.
>> +It shall be a signed integer type
> 
> s/It/According to POSIX, it/

As this type is POSIX-only, I thought it was redundant.  Don't you?

> 
>> +capable of storing values at least in the range [-1, 1000000].
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.>> +.IP
>> +See also:
>> +.\".BR getitimer (2),
>> +.\".BR gettimeofday (2),
>> +.\".BR select (2),
>> +.\".BR adjtime (3),
>> +.\".BR ntp_gettime (3),
>> +.BR timeval (3)
>> +.\".BR timeradd (3)
> 
> The above is a little too circular for my taste :-).

Maybe... I'll leave it commented, just in case some day the list is
splitted.

> 
> How about just saying: 
> 
> [[
> This type is used for one of the 
> fields of the timeval structure (see below).
> ]]

That's too long for my taste :)

How about?:

[[
See the timeval structure in this page.
]]

> 
>> +.TP
>> +.I time_t
>> +.IP
>> +Include:
>> +.I <time.h>
>> +or
>> +.I <sys/types.h>
>> +.IP
>> +Used for time in seconds.
>> +In POSIX, it shall be an integer type.
> 
> s/In/According to/

OK.

> 
>> +.IP
>> +Conforming to: C99 and later; POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> 
> Many items in the following list should go...

Yes

> 
>> +.BR clock_getres (2),
>> [...]
>> +.BR timeradd (3)
>> +.TP
>> +.I timer_t
>> +.IP
>> +Include:
> 
> Add "<time.h> or"

POSIX says:

The <time.h> header shall define the clockid_t and timer_t types as
described in <sys/types.h>.

That pattern is used by POSIX (AFAIK; I only guessed it by reading many
of those) when the type is defined by inclusion of another header
(<time.h> includes <sys/types.h> I guess).

If I added every header that has a line like that, the lists of headers
would be much bigger for most of the types.  It could be good, but I
don't know if we should do it.  Maybe we should limit to the headers
that are required by CXX and the ones where the POSIX docs actually
document the type (this header doesn't define it, and instead it defers
to <sys//types.h> for example).

Your thoughts?

> 
>> +.I <sys/types.h>
>> +.IP
>> +Used for timer ID returned by timer_create().
>> +There are no defined comparison or assignment operators for this type.
> 
> Where is that mentioned in the standard, by the way?

https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html

DESCRIPTION:

[...]

There are no defined comparison or assignment operators for the
following types:

[...]

timer_t

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR timer_create (2),
>> +.BR timer_delete (2),
>> +.BR timer_getoverrun (2),
>> +.BR timer_settime (2)
>> +.TP
>> +.BI "union " sigval
>> +.IP
>> +Include:
>> +.I <signal.h>
>> +.IP
>> +.EX
>> +union sigval {
>> +    int     sigval_int; /* Integer value */
>> +    void   *sigval_ptr; /* Pointer value */
>> +};
>> +.EE
>> +.IP
>> +Data passed with notification.
> 
> s/notification/a signal/

OK.

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR rt_sigqueueinfo (2),
>> +.BR sigaction (2),
>> +.BR mq_notify (3),
>> +.BR pthread_sigqueue (3),
>> +.BR sigqueue (3),
>> +.BR sigevent (7)
> 
> Thanks,
> 
> Michael
> 
> 

Thanks,

Alex