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

Michael Kerrisk (man-pages)
2020-09-17T10:28:17Z

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@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/