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

[Alejandro Colomar]

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

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.

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

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

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

Yeah, that's what I wanted to do.
But I was too lazy, and at some point stopped doing it :(

I'll do it from now on...

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


 >
 > Thanks,
 >
 > Michael
 >

Thanks,

Alex