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/
