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

Thu Sep 17 10:27:53 UTC 2020

Hello Alex,

On 9/16/20 9:51 PM, Alejandro Colomar wrote:
> Hello Michael
> 
> On 2020-09-16 21:24, Michael Kerrisk (man-pages) wrote:
>  > 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.
> 
> It still doesn't convince me.
> 
> Let's see how the standards define the types:
> 
> C has a ¿main? header that defines a type
> (for example, for 'time_t' it would be <time.h>;
> for 'size_t' it would be <stddef.h>),
> and then there may be other headers that shall also define the type
> (for example, 'size_t' is also defined in <stdio.h> and others).
> 
> POSIX does more or less the same:
> It has a ¿main? header where the type is defined
> (for 'time_t' it is <sys/types>,
> which as you can it sometimes see differs from C),
> and then there may be other headers that shall define the type.
> 
> I think we should differentiate those 1 or 2 headers
> by putting them the first ones,
> and then the rest could be merged together
> (and maybe use a comma or something to differentiate them?).

Maybe a semicolon (;), just because more visually obvious?

> Such as (for 'time_t'):
> 
> Include: <sys/types.h> or <time.h>, or <sched.h> or <sys/msg.h> or
> <sys/select.h> or <sys/sem.h> or <sys/shm.h> or <sys/stat.h> or
> <sys/time.h> or <utime.h>
> 
> However this still doesn't convince me...
> I don't see a perfect way to express that.

Maybe not perfect, but I don't think we have to come up with
the perfect solution (yet). I think things are okay as you
propose them currently.

> Also, should we put a dot at the end of the includes?

Yes, perhaps a little tidier.

> 
> Include: <sys/types.h> or <time.h>¿.?

[...]

>  >>> <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.
> 
> See above.  That's the only thing that I don't fully like.
> 
> Also there are a few cosmetic fixes that I have in my tree already.
> 
> And, I trimmed a bit more the 'sigval' See also section.
> 
> Here's what I already applied to my tree.  I will show you the diff as
> it is very short so you have an idea off what is coming:
> 
> $ git diff types_draft_6
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 8fc827332..ffdcc9793 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -38,7 +38,7 @@ system_data_types \- overview of system data types
>   .\"                    1) The header(s) that shall define the type
>   .\"                       according to the C standard,
>   .\"                       and
> -.\"                       the header that shall define the type
> +.\"                       the main header that shall define the type
>   .\"                       according to POSIX,
>   .\"                       in alphabetical order.
>   .\"                    2) All other headers that shall define the type
> 
> (inline comment): Actually this still doesn't convince me, as I already 
> said.
> 
> @@ -81,11 +81,15 @@ Data passed with a signal.
>   Conforming to: POSIX.1-2001 and later.
>   .IP
>   See also:
> -.BR rt_sigqueueinfo (2),
> -.BR sigaction (2),
>   .BR pthread_sigqueue (3),
>   .BR sigqueue (3),
>   .BR sigevent (7)
> +.\".IP
> +.\"See also the
> +.\".I sigevent
> +.\"structure and the
> +.\".I siginfo_t
> +.\"type in this page.
>   .TP
>   .I ssize_t
>   .IP
> 
> Those 2 man pages aren't very related to this type,
> and instead are related to 'siginfo_t', which contains a member of
> type 'union sigval'.
> So I prefer to refer to 'siginfo_t',
> and there we will refer to those pages.

That sounds okay to me. I presume you plan to uncomment the
lines above that mention sigevent and siginfo_t, right?

Cheers,

Michael

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