[RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/16/20 1:01 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3 at gmail.com>
> ---
> 
> Hi Michael,
> 
> Changelog since v4:
> 
> - Comment "See also" about yet undocumented size_t
> - Simplify header ordering
> - Curate See also
> - Remove incorrect headers
> 
> 
> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
>> Okay. Time to nit pick:-). Do not be too dispirited,
>> I think we started with some of the most difficult types...
> 
> I was waiting for it :-).
> 
>> I soppose what I meant is that POSIX defers to the C standard
>> in the cases where they overlap, and I'd expect that the set
>> of headers specified in the C standard and in POSIX might be the
>> same, but where they're not, I suspect the list of POSIX headers
>> would always be a superset of the C headers. So, just make a
>> single list of those headers, followed by 3 and 4 (merged)
> 
> See updated comment in the page.

It looks good to me.

>> I suggest dropping the pages marked XX. The remaining can serve
>> as the (commonly used) exemplars of APIs that use this type.
> 
> Done.  I don't have experience enough to subjectively decide
> which ones should stay and which ones we should drop, so...
> 
>> Okay, now I look closer at these lists. How have you determined them?
> 
> I kept references to all APIs that use the type in the prototype.
> 
> And for the headers list:
> 
> I started reading the contents of the headers, but all I had seen
> did actually define the type, so I guessed that all the remaining
> grep appearances would also define the type.  Clearly, I guessed wrong.

What I did was read the specifications of the .h files in the 
standard, to see which ones said "shall define type XXX".
I think that's the way we should go, at least for types that 
are in the standards.

>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
>> tell! I'm not sure how/if we want to represent that detail.
> 
> I added a Notes section for that type.  You like it?

Yes.

>> But size_t is not in this page (yet). Is it in your tree?
> 
> Not yet.  In my tree I didn't forget to comment it, though.  As you can
> guess, It'll be the next type to document, and then ptrdiff_t.
> 
>> Today I learned: size_t is in C99, but ssize_t is not!

[...]

I have no comments on the page. It looks great! I'm happy to
merge it now, unless you have something you want to change first.

Thanks,

Michael

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