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

["Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com>]

Hi Alex,

On 9/14/20 5:52 PM, Alejandro Colomar wrote:
> 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.

As I think about more, maybe the list of type keywords could even
omit 'struct' and 'union', since the struct/union definition will be shown
in the following text. Your thoughts?

[...]

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

Ooops -- I think I misplaced that sentence. It related to suseconds_t.

[...]

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

I think it's clearer to be explicit. Otherwise, the reader has to do
some deductive work.

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

Vale.

[...]

>>> +.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 think the list would not be so long. Maybe two headers sometimes,
occasionally three, but I doubt more. At least right now, I think we
should do it; I may yet be shown the error of my ways :-).


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

Thanks. It's good that you included that sentence in the man page.

[...]

Good progress so far. Thanks, Alex!

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/