[IDEA] New pages for types: structs and typedfefs

[IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

Hello Michael,

In the past, when I was beginning to learn C, I had a lot of trouble 
with the types.

When you want to know about a function, you just type 'man function' and 
that tells you everything you need to know.

However, when you need to use a type, such as a struct or one of those 
weird POSIX types (e.g., loff_t), the only solution is to grep through 
the system headers (e.g., 'cd /usr/include/; grep -rn "struct 
timespec"'), unless you already know in which man page the type appears.

I remember well when I wanted to use 'ssize_t' for the first time: it 
was a nightmare to find which header I had to include to get it.

Do you agree that it would be a good idea to write man pages for the 
types, or at least write link pages that link to the page where the type 
is mentioned?

Thanks,


Alex

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/11/20 2:47 PM, Alejandro Colomar wrote:
> Hello Michael,
> 
> In the past, when I was beginning to learn C, I had a lot of trouble 
> with the types.
> 
> When you want to know about a function, you just type 'man function' and 
> that tells you everything you need to know.
> 
> However, when you need to use a type, such as a struct or one of those 
> weird POSIX types (e.g., loff_t), the only solution is to grep through 
> the system headers (e.g., 'cd /usr/include/; grep -rn "struct 
> timespec"'), unless you already know in which man page the type appears.
> 
> I remember well when I wanted to use 'ssize_t' for the first time: it 
> was a nightmare to find which header I had to include to get it.
> 
> Do you agree that it would be a good idea to write man pages for the 
> types, or at least write link pages that link to the page where the type 
> is mentioned?

Your not the first to suggest this. Most recently, if I recall
correctly, Florian also suggested it.

The idea seems reasonable, but I wonder about the best way of doing it.

I propose the desired information for each type would be

* Type name
* Short explanation of the type (often this mcould be just a
  few words, I think)
* Whether the type is specified in POSIX; POSIX requirements on 
  the type.
* Header file that defines the type (in some cases, there 
  may be more than one. This info can be discovered in the
  POSIX spec. (Alex, do you have a PDF of the POSIX spec?)
* Cross references to manual pages of relevant APIs that use the type.

There are some weird corner cases. For example, clock_t:

* times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK))
* clock(3): clock_t measures in CLOCKS_PER_SEC

Then, do we do one page per type? At first glance, that seems
unwieldy to me. (I could be wrong.) And it seems to me that
there might be benefits in having all of the information in 
one place rather than spread across multiple pages. (For example
cantralizing the info would make it easier for the reader to
get an overview.)

Alternatively, we could have one big page that is a list of the 
types with the above information. Say "system_data_types(7)".
That page might be an alphabetically ordered hanging list of 
entries that look like this:

    timer_t     <time.h> or <sys/types.h>
        POSIX timer ID.

        Conforming to: POSIX.1-2008.

        See: timer_create(2), timer_delete(2), timer_getoverrun(2),
        timer_settime(2)

Then of course, we'd need to have links to that page, so that
people could just type 'man timer_t'. What section should the links
be in? The reasonable candidates would be section 3 or 7. I'm not
yet sure which is better. But the point is that we'd have files 
such as timer_t.3 (or timer_t.7) that are link pages containing the
line:

    .so man7/system_data_types.7

For the moment at least, I'd favor the "one big page plus 
links" approach.

Your thoughts?

Thanks,

Michael

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

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

Hi Michael,

On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote:
 > Your not the first to suggest this. Most recently, if I recall
 > correctly, Florian also suggested it.
 >
 > The idea seems reasonable, but I wonder about the best way of doing it.

libbsd already provides a few pages on types.  Maybe we could have a
look at them.  At least I've seen 'man timespec' (which redirects to
timeval.3bsd):

https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd

 >
 > I propose the desired information for each type would be
 >
 > * Type name
 > * Short explanation of the type (often this mcould be just a
 >    few words, I think)
 > * Whether the type is specified in POSIX; POSIX requirements on
 >    the type.
 > * Header file that defines the type (in some cases, there
 >    may be more than one. This info can be discovered in the
 >    POSIX spec. (Alex, do you have a PDF of the POSIX spec?)
 > * Cross references to manual pages of relevant APIs that use the type.

I think that would be reasonable.

No, I don't have a PDF.  I usually search here:

https://pubs.opengroup.org/onlinepubs/9699919799/

 >
 > There are some weird corner cases. For example, clock_t:
 >
 > * times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK))
 > * clock(3): clock_t measures in CLOCKS_PER_SEC

That would just be 1 or 2 more lines in the explanation, I guess.

That's also similar to the typical (mis?)use of size_t as a ptrdiff_t.

 >
 > Then, do we do one page per type? At first glance, that seems
 > unwieldy to me. (I could be wrong.) And it seems to me that
 > there might be benefits in having all of the information in
 > one place rather than spread across multiple pages. (For example
 > cantralizing the info would make it easier for the reader to
 > get an overview.)

I agree in that everything should be centralized, at least in the
beginning.  That would make it much easier to maintain and find the
information.  If the future requires the information to be spread
across many pages, let the future solve that problem :)

 >
 > Alternatively, we could have one big page that is a list of the
 > types with the above information. Say "system_data_types(7)".
 > That page might be an alphabetically ordered hanging list of
 > entries that look like this:
 >
 >      timer_t     <time.h> or <sys/types.h>
 >          POSIX timer ID.
 >
 >          Conforming to: POSIX.1-2008.
 >
 >          See: timer_create(2), timer_delete(2), timer_getoverrun(2),
 >          timer_settime(2)

I'd say here is missing the POSIX requirements on the type.

Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?

 >
 > Then of course, we'd need to have links to that page, so that
 > people could just type 'man timer_t'. What section should the links
 > be in? The reasonable candidates would be section 3 or 7. I'm not
 > yet sure which is better. But the point is that we'd have files
 > such as timer_t.3 (or timer_t.7) that are link pages containing the
 > line:
 >
 >      .so man7/system_data_types.7

Sure.  And for the structs, I'd allow:

'man struct timespec'	(For simplicity)
'man struct-timespec'	(Similar to the git man pages)
'man timespec'		(For compatibility with libbsd)

Your thoughts?

 >
 > For the moment at least, I'd favor the "one big page plus
 > links" approach.

Yes.

Thanks,

Alex

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

On 2020-09-12 10:59, Alejandro Colomar wrote:
> Sure.  And for the structs, I'd allow:
> 
> 'man struct timespec'    (For simplicity)
> 'man struct-timespec'    (Similar to the git man pages)
> 'man timespec'           (For compatibility with libbsd)

Actually, the 3rd form might create collisions.  I'm not sure it's a 
good idea.

Alex

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hi Alex,

On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
>
> Hi Michael,
>
> On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote:
>  > Your not the first to suggest this. Most recently, if I recall
>  > correctly, Florian also suggested it.
>  >
>  > The idea seems reasonable, but I wonder about the best way of doing it.
>
> libbsd already provides a few pages on types.  Maybe we could have a
> look at them.  At least I've seen 'man timespec' (which redirects to
> timeval.3bsd):
>
> https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd
>
>  >
>  > I propose the desired information for each type would be
>  >
>  > * Type name
>  > * Short explanation of the type (often this mcould be just a
>  >    few words, I think)
>  > * Whether the type is specified in POSIX; POSIX requirements on
>  >    the type.
>  > * Header file that defines the type (in some cases, there
>  >    may be more than one. This info can be discovered in the
>  >    POSIX spec. (Alex, do you have a PDF of the POSIX spec?)
>  > * Cross references to manual pages of relevant APIs that use the type.
>
> I think that would be reasonable.
>
> No, I don't have a PDF.  I usually search here:
>
> https://pubs.opengroup.org/onlinepubs/9699919799/

You can get a PDF by registering as a member of The Open Group. I
think the necessary info is here:
https://www.opengroup.org/austin/lists.html
(I find having everything in a single PDF is useful for searching.)

>  > There are some weird corner cases. For example, clock_t:
>  >
>  > * times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK))
>  > * clock(3): clock_t measures in CLOCKS_PER_SEC
>
> That would just be 1 or 2 more lines in the explanation, I guess.

Yes, I guess.

> That's also similar to the typical (mis?)use of size_t as a ptrdiff_t.
>
>  > Then, do we do one page per type? At first glance, that seems
>  > unwieldy to me. (I could be wrong.) And it seems to me that
>  > there might be benefits in having all of the information in
>  > one place rather than spread across multiple pages. (For example
>  > cantralizing the info would make it easier for the reader to
>  > get an overview.)
>
> I agree in that everything should be centralized, at least in the
> beginning.  That would make it much easier to maintain and find the
> information.  If the future requires the information to be spread
> across many pages, let the future solve that problem :)
>
>  >
>  > Alternatively, we could have one big page that is a list of the
>  > types with the above information. Say "system_data_types(7)".
>  > That page might be an alphabetically ordered hanging list of
>  > entries that look like this:
>  >
>  >      timer_t     <time.h> or <sys/types.h>
>  >          POSIX timer ID.
>  >
>  >          Conforming to: POSIX.1-2008.
>  >
>  >          See: timer_create(2), timer_delete(2), timer_getoverrun(2),
>  >          timer_settime(2)
>
> I'd say here is missing the POSIX requirements on the type.

As far as I can tell, in the case of timer_t, I think there are no
requirements in POSIX.

> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?

POSIX doesn't specify, I think.

One other thing the page should show of course is definition of the
structure types.

>  > Then of course, we'd need to have links to that page, so that
>  > people could just type 'man timer_t'. What section should the links
>  > be in? The reasonable candidates would be section 3 or 7. I'm not
>  > yet sure which is better. But the point is that we'd have files
>  > such as timer_t.3 (or timer_t.7) that are link pages containing the
>  > line:
>  >
>  >      .so man7/system_data_types.7
>
> Sure.  And for the structs, I'd allow:
>
> 'man struct timespec'   (For simplicity)
> 'man struct-timespec'   (Similar to the git man pages)
> 'man timespec'          (For compatibility with libbsd)

Mainly, I'm interested in the last case. That's the one I think that
people would most likely use. In a follow-up mail, you expressed
concern with conflicts with libbsd pages. I'm not too worried about
that. There are already *many* conflicts between libbsd and man-pages.

>  > For the moment at least, I'd favor the "one big page plus
>  > links" approach.
>
> Yes.

Would you like to take a shot at this? I'd suggest just a simple page
covering just two or three types to start with. Maybe time_t and
timer_t, or otherwise some types that seem good choices to you?

Thanks,

Michael



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

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

Hi Michael,

On 9/13/20 2:01 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar
<colomar.6.4.3@gmail.com> wrote:
>>
>> Hi Michael,
>>
>> On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote:
>>  > Your not the first to suggest this. Most recently, if I recall
>>  > correctly, Florian also suggested it.
>>  >
>>  > The idea seems reasonable, but I wonder about the best way of
doing it.
>>
>> libbsd already provides a few pages on types.  Maybe we could have a
>> look at them.  At least I've seen 'man timespec' (which redirects to
>> timeval.3bsd):
>>
>>
https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd
>>
>>  >
>>  > I propose the desired information for each type would be
>>  >
>>  > * Type name
>>  > * Short explanation of the type (often this mcould be just a
>>  >    few words, I think)
>>  > * Whether the type is specified in POSIX; POSIX requirements on
>>  >    the type.
>>  > * Header file that defines the type (in some cases, there
>>  >    may be more than one. This info can be discovered in the
>>  >    POSIX spec. (Alex, do you have a PDF of the POSIX spec?)
>>  > * Cross references to manual pages of relevant APIs that use the type.
>>
>> I think that would be reasonable.
>>
>> No, I don't have a PDF.  I usually search here:
>>
>> https://pubs.opengroup.org/onlinepubs/9699919799/
>
> You can get a PDF by registering as a member of The Open Group. I
> think the necessary info is here:
> https://www.opengroup.org/austin/lists.html
> (I find having everything in a single PDF is useful for searching.)

Thanks.

>
>>  > There are some weird corner cases. For example, clock_t:
>>  >
>>  > * times(2): clock_t == clock ticks (sysconf(_SC_CLK_TCK))
>>  > * clock(3): clock_t measures in CLOCKS_PER_SEC
>>
>> That would just be 1 or 2 more lines in the explanation, I guess.
>
> Yes, I guess.
>
>> That's also similar to the typical (mis?)use of size_t as a ptrdiff_t.
>>
>>  > Then, do we do one page per type? At first glance, that seems
>>  > unwieldy to me. (I could be wrong.) And it seems to me that
>>  > there might be benefits in having all of the information in
>>  > one place rather than spread across multiple pages. (For example
>>  > cantralizing the info would make it easier for the reader to
>>  > get an overview.)
>>
>> I agree in that everything should be centralized, at least in the
>> beginning.  That would make it much easier to maintain and find the
>> information.  If the future requires the information to be spread
>> across many pages, let the future solve that problem :)
>>
>>  >
>>  > Alternatively, we could have one big page that is a list of the
>>  > types with the above information. Say "system_data_types(7)".
>>  > That page might be an alphabetically ordered hanging list of
>>  > entries that look like this:
>>  >
>>  >      timer_t     <time.h> or <sys/types.h>
>>  >          POSIX timer ID.
>>  >
>>  >          Conforming to: POSIX.1-2008.
>>  >
>>  >          See: timer_create(2), timer_delete(2), timer_getoverrun(2),
>>  >          timer_settime(2)
>>
>> I'd say here is missing the POSIX requirements on the type.
>
> As far as I can tell, in the case of timer_t, I think there are no
> requirements in POSIX.
>
>> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?
>
> POSIX doesn't specify, I think.>
> One other thing the page should show of course is definition of the
> structure types.

Yes.


    timer_t     <time.h> or <sys/types.h>
        POSIX timer ID.

        typedef void *timer_t;

        Conforming to: POSIX.1-2008.

        See: timer_create(2), timer_delete(2), timer_getoverrun(2),
        timer_settime(2)

Like this?  Should I specify somehow if the type definition
is so for Linux only, or for all POSIX, ...?

sources:
x86_64-linux-gnu/bits/types/timer_t.h:7:typedef __timer_t timer_t;
x86_64-linux-gnu/bits/types.h:171:__STD_TYPE __TIMER_T_TYPE __timer_t;
x86_64-linux-gnu/bits/types.h:126:# define __STD_TYPE		typedef
x86_64-linux-gnu/bits/typesizes.h:70:#define __TIMER_T_TYPE		void *

This is so for my Debian x86-64.

However, I don't know if this is the definition for all architectures.

I'll start with what I can do, and if you see any type that you know
has a different definition in other systems, I'll let that to you :)

>
>>  > Then of course, we'd need to have links to that page, so that
>>  > people could just type 'man timer_t'. What section should the links
>>  > be in? The reasonable candidates would be section 3 or 7. I'm not
>>  > yet sure which is better. But the point is that we'd have files
>>  > such as timer_t.3 (or timer_t.7) that are link pages containing the
>>  > line:
>>  >
>>  >      .so man7/system_data_types.7
>>
>> Sure.  And for the structs, I'd allow:
>>
>> 'man struct timespec'   (For simplicity)
>> 'man struct-timespec'   (Similar to the git man pages)
>> 'man timespec'          (For compatibility with libbsd)
>
> Mainly, I'm interested in the last case. That's the one I think that
> people would most likely use. In a follow-up mail, you expressed
> concern with conflicts with libbsd pages. I'm not too worried about
> that. There are already *many* conflicts between libbsd and man-pages.

I wasn't concerned about conflict with libbsd; that's the form libbsd
uses, and a good point for having that form would be for compatibility
(people will probably like having to write 'man timespec' in any
system and work).

I was instead concerned that some struct tag may have the same name as
some function, which I don't know for sure:

Let's say there exist a function 'int foo(void)', and a 'struct foo'.
If that is the case, which I ignore, you would need to either have
'foo.3' and 'foo.3t' or have 'foo.3' and 'struct-foo.3'.

Your thoughts?

>
>>  > For the moment at least, I'd favor the "one big page plus
>>  > links" approach.
>>
>> Yes.
>
> Would you like to take a shot at this? I'd suggest just a simple page
> covering just two or three types to start with. Maybe time_t and
> timer_t, or otherwise some types that seem good choices to you?

Yes, I'd like to.  It'll be my first page from scratch, though, so
don't expect it to be soon :-}

Maybe 'timer_t', 'time_t' and 'struct timespec' would be a good start.

Do you think there's any page that has a similar format to what we want
to base on it?

>
> Thanks,
>
> Michael
>
>

Thanks,

Alex

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/13/20 2:53 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> On 9/13/20 2:01 PM, Michael Kerrisk (man-pages) wrote:
>> Hi Alex,
>>
>> On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar
> <colomar.6.4.3@gmail.com> wrote:

[...]

>>> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?
>>
>> POSIX doesn't specify, I think.>
>> One other thing the page should show of course is definition of the
>> structure types.
> 
> Yes.
> 
> 
>     timer_t     <time.h> or <sys/types.h>
>         POSIX timer ID.
> 
>         typedef void *timer_t;

Here I would *not* show these kinds of typedefs. The point is
that these types should be treated as being somewhat unknown
(e.g., for casts in printf()). Here, I think instead maybe we 
just have a statement that POSIX makes no specific requirements
for the representation of this type.
 
>         Conforming to: POSIX.1-2008.
> 
>         See: timer_create(2), timer_delete(2), timer_getoverrun(2),
>         timer_settime(2)
> 
> Like this?  Should I specify somehow if the type definition
> is so for Linux only, or for all POSIX, ...?

See the above comment.

[...]

>>> Sure.  And for the structs, I'd allow:
>>>
>>> 'man struct timespec'   (For simplicity)
>>> 'man struct-timespec'   (Similar to the git man pages)
>>> 'man timespec'          (For compatibility with libbsd)
>>
>> Mainly, I'm interested in the last case. That's the one I think that
>> people would most likely use. In a follow-up mail, you expressed
>> concern with conflicts with libbsd pages. I'm not too worried about
>> that. There are already *many* conflicts between libbsd and man-pages.
> 
> I wasn't concerned about conflict with libbsd; that's the form libbsd
> uses, and a good point for having that form would be for compatibility
> (people will probably like having to write 'man timespec' in any
> system and work).
> 
> I was instead concerned that some struct tag may have the same name as
> some function, which I don't know for sure:
> 
> Let's say there exist a function 'int foo(void)', and a 'struct foo'.
> If that is the case, which I ignore, you would need to either have
> 'foo.3' and 'foo.3t' or have 'foo.3' and 'struct-foo.3'.
> 
> Your thoughts?

Offhand, I can't think of any such conflicts. Many of the data
types have names suffixed with "_t", and there should be no 
conflicts there.

For other types, such as timeval, timespec, etc, I don't expect
there are many conflicts. One case that I can think of where
there's a function and a struct with the same name is 'sigaction'.
But there's not really a problem there, since, on the one hand,
I don't expect that that is one of the types that should be
documented in system_data_types(7), and on the other hand,
currently "man sigaction" takes you to the page that documents 
both the function and the structure.

>>>  > For the moment at least, I'd favor the "one big page plus
>>>  > links" approach.
>>>
>>> Yes.
>>
>> Would you like to take a shot at this? I'd suggest just a simple page
>> covering just two or three types to start with. Maybe time_t and
>> timer_t, or otherwise some types that seem good choices to you?
> 
> Yes, I'd like to.  It'll be my first page from scratch, though, so
> don't expect it to be soon :-}
> 
> Maybe 'timer_t', 'time_t' and 'struct timespec' would be a good start.

Throw in 'struct timeval' too?
 
> Do you think there's any page that has a similar format to what we want
> to base on it?

I think nothing special is required. See man-pages(7) for general
info on the layout of pages. I expect the types can be placed
as an alphabetically ordered hanging list under DESCRIPTION.

Cheers,

Michael

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

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

Hi Michael

On 9/13/20 10:20 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On 9/13/20 2:53 PM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> On 9/13/20 2:01 PM, Michael Kerrisk (man-pages) wrote:
>>> Hi Alex,
>>>
>>> On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar
>> <colomar.6.4.3@gmail.com> wrote:
>
> [...]
>
> Here I would *not* show these kinds of typedefs. The point is
> that these types should be treated as being somewhat unknown
> (e.g., for casts in printf()). Here, I think instead maybe we
> just have a statement that POSIX makes no specific requirements
> for the representation of this type.

Agreed.

>
> [...]
>
>>>> Sure.  And for the structs, I'd allow:
>>>>
>>>> 'man struct timespec'   (For simplicity)
>>>> 'man struct-timespec'   (Similar to the git man pages)
>>>> 'man timespec'          (For compatibility with libbsd)
>>>
>> [...]
>
> Offhand, I can't think of any such conflicts. Many of the data
> types have names suffixed with "_t", and there should be no
> conflicts there.

Yes.

>
> For other types, such as timeval, timespec, etc, I don't expect
> there are many conflicts. One case that I can think of where
> there's a function and a struct with the same name is 'sigaction'.
> But there's not really a problem there, since, on the one hand,
> I don't expect that that is one of the types that should be
> documented in system_data_types(7),
Why not?

> and on the other hand,
> currently "man sigaction" takes you to the page that documents
> both the function and the structure.

Fair enough.

>> [...]
>
> Throw in 'struct timeval' too?

Fine.

>
>> Do you think there's any page that has a similar format to what we want
>> to base on it?
>
> I think nothing special is required. See man-pages(7) for general
> info on the layout of pages. I expect the types can be placed
> as an alphabetically ordered hanging list under DESCRIPTION.

Ok.

New question:

I've already started and I'm writing the short description on 'time_t'.

POSIX has copyright and all rights reserved, but do you think it would
be fair use to copy descriptions such as "Used for time in seconds."?
Or do I have to come up with a new short description?

Thanks,

Alex

[RFC v1] system_data_types.7: Draft (and links to it: <type>.3)

[Alejandro Colomar]

From ffd8ea312527935cd86cc7ed1133a08d4e642b06 Mon Sep 17 00:00:00 2001
From: Alejandro Colomar <colomar.6.4.3@gmail.com>
Date: Mon, 14 Sep 2020 02:07:50 +0200
Subject: [RFC] First draft for system_data_types.7 (and links to it:
 <type>.3)

Hi Michael,

This is my first draft.

There are still TODO things:
- Add types (obviously)
- Write specific "Conforming to" versions
  For now I just wrote POSIX, but I'll write the specific versions.
  Should I write the latest one, the oldest one, or how?
  For C versions I did the following:
	If the type has been there since C89, I wrote C89, C99.
	If the type is >= C99, I wrote C99.
	If the type is >= C11, I wrote C11.
- Correctly highlight function names and similar (see timer_t)
  For this first draft, I just want to show you the idea.  I'll add
  italics and all that stuff later on.
- Review "See also" (right now: all results of 'grep -rl <type>')
  I put everything that came up with grep in the See also section.
  Is it too much?  Any other references I should add?

Your thoughts?

Cheers,

Alex

---
 man3/sigval.3            |   1 +
 man3/time_t.3            |   1 +
 man3/timer_t.3           |   1 +
 man3/timespec.3          |   1 +
 man3/timeval.3           |   1 +
 man7/system_data_types.7 | 201 +++++++++++++++++++++++++++++++++++++++
 6 files changed, 206 insertions(+)
 create mode 100644 man3/sigval.3
 create mode 100644 man3/time_t.3
 create mode 100644 man3/timer_t.3
 create mode 100644 man3/timespec.3
 create mode 100644 man3/timeval.3
 create mode 100644 man7/system_data_types.7

diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..278a6b830
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,201 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Check specific POSIX "Conforming to" versions
+.\"	* Correctly highlight function names and similar (see timer_t)
+.\"	* Review "See also" (right now: all results of 'grep -rl <type>')
+.SS typedef types
+.TP
+.B time_t
+.I <time.h>
+or
+.I <sys/types.h>
+.IP
+Used for time in seconds.
+It shall be an integer type.
+.IP
+Conforming to: POSIX, C89, C99
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR gettimeofday (2),
+.BR io_getevents (2),
+.BR keyctl (2),
+.BR msgctl (2),
+.BR msgop (2),
+.BR nanosleep (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semctl (2),
+.BR shmctl (2),
+.BR stat (2),
+.BR stime (2),
+.BR time (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR times (2),
+.BR utime (2),
+.BR utimensat (2),
+.BR adjtime (3),
+.BR ctime (3),
+.BR difftime (3),
+.BR ftime (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR newlocale (3),
+.BR ntp_gettime (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_tryjoin_np (3),
+.BR rtime (3),
+.BR sem_wait (3),
+.BR strcat (3),
+.BR strftime (3),
+.BR timegm (3),
+.BR timeradd (3)
+.TP
+.B timer_t
+.I <time.h>
+or
+.I <sys/types.h>
+.IP
+Used for timer ID returned by timer_create().
+There are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.SS struct types
+.TP
+.B timespec
+.I <time.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: POSIX, C11
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR futex (2),
+.BR io_getevents (2),
+.BR nanosleep (2),
+.BR poll (2),
+.BR recvmmsg (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semop (2),
+.BR sigwaitinfo (2),
+.BR stat (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR utimensat (2),
+.BR aio_suspend (3),
+.BR clock_getcpuclockid (3),
+.BR getaddrinfo_a (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR pthread_getcpuclockid (3),
+.BR pthread_tryjoin_np (3),
+.BR sem_wait (3),
+.BR socket (7)
+.TP
+.B timeval
+.I <sys/time.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and miliseconds.
+.\" Comment from /usr/include/x86_64-linux-gnu/bits/types/struct_timeval.h
+.IP
+Conforming to: POSIX
+.IP
+See also:
+.BR adjtimex (2),
+.BR futimesat (2),
+.BR getitimer (2),
+.BR getpriority (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR utime (2),
+.BR wait4 (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR ntp_gettime (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3),
+.BR utmp (5),
+.BR packet (7),
+.BR socket (7)
+.SS union types
+.TP
+.B sigval
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with notification.
+.IP
+Conforming to: POSIX
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
-- 
2.28.0

Re: [RFC v1] system_data_types.7: Draft (and links to it: <type>.3)

[Michael Kerrisk (man-pages)]

Hello Alex,

On 9/14/20 2:20 AM, Alejandro Colomar wrote:
>>From ffd8ea312527935cd86cc7ed1133a08d4e642b06 Mon Sep 17 00:00:00 2001
> From: Alejandro Colomar <colomar.6.4.3@gmail.com>
> Date: Mon, 14 Sep 2020 02:07:50 +0200
> Subject: [RFC] First draft for system_data_types.7 (and links to it:
>  <type>.3)
> 
> Hi Michael,
> 
> This is my first draft.
> 
> There are still TODO things:
> - Add types (obviously)
> - Write specific "Conforming to" versions
>   For now I just wrote POSIX, but I'll write the specific versions.

Good. I think that we can get away with just mentioning one each of
POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
far enough back in time that we don't need to clutter the page with
it. Something like:

Conforming to: C99 and later; POSIX.1-2001 and later.


>   Should I write the latest one, the oldest one, or how?

See above.

>   For C versions I did the following:
> 	If the type has been there since C89, I wrote C89, C99.
> 	If the type is >= C99, I wrote C99.
> 	If the type is >= C11, I wrote C11.
> - Correctly highlight function names and similar (see timer_t)
>   For this first draft, I just want to show you the idea.  I'll add
>   italics and all that stuff later on.
> - Review "See also" (right now: all results of 'grep -rl <type>')
>   I put everything that came up with grep in the See also section.
>   Is it too much?  Any other references I should add?

I am ambivalent on the question of "is it too much?". Some of those
lists seem rather long. But the question of whether it is valuable to
mention *all* of the APIs is open: maybe it is; maybe it is not. Then
again, trying to be exhaustive, makes the lists fragile (new API
appears, but we forgot to add it to the list). And then if we
do not include all of the APIs, what are the criteria for
inclusion/exclusion?

I'm going to hold my finger in the wind, and say: lets restrict the
list to what seem like the most relevant APIs, where obviously that is
a somewhat subjective choice. You could include all the other APIs in
.\" comments, so we can see what's excluded, and this may trigger some
tweaking. So, for 'struct timespec' the list might be as simple as:

clock_gettime(2), clock_nanosleep(2), nanosleep(2)
timerfd_gettime(2), timer_gettime(2)

Note by the way, that that list is not a subset of your list.
Instead, I looked inside the pages that you listed to see which APIs
seemed "relevant".

I cannot think of other references that you should add.

You better include suseconds_t in the next draft :-).

I think it would be better not to split the types into separate lists.
Instead (and note the formatting) order by type name:

.TP
.BI "union " sigval
...
.TP
.I time_t
...
.TP
.I timer_t
...
.TP
.BI "struct " timespec
...
.TP
.BI "struct " timeval
...

Having seen how it looks with the header files, I'm going to suggest a
differnt approach. Let's put them on a separate line, something like:

Obtained by including: <abc.h> or <xyz.h>

> ---
>  man3/sigval.3            |   1 +
>  man3/time_t.3            |   1 +
>  man3/timer_t.3           |   1 +
>  man3/timespec.3          |   1 +
>  man3/timeval.3           |   1 +

It's an open question whether the links should be in section 3 or 
section 7. Do you have any thoughts on what's better?

Don't get wrapped up in including too many more types in the
yet, while we try to iron out the format.

Also, I'd like to see the types added incrementally (one or a few
at a time), so that it's easy to comment on each type, when needed.

Thanks,

Michael



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

Re: [RFC v1] system_data_types.7: Draft (and links to it: <type>.3)

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/14/20 12:37 PM, Michael Kerrisk (man-pages) wrote:
> Hello Alex,
> 
> On 9/14/20 2:20 AM, Alejandro Colomar wrote:
> I'm going to hold my finger in the wind, and say: lets restrict the
> list to what seem like the most relevant APIs, where obviously that is
> a somewhat subjective choice. You could include all the other APIs in
> .\" comments, so we can see what's excluded, and this may trigger some
> tweaking. So, for 'struct timespec' the list might be as simple as:
> 
> clock_gettime(2), clock_nanosleep(2), nanosleep(2)
> timerfd_gettime(2), timer_gettime(2)

Just to add to this. Even if limiting to "relevant" APIs,
I think some of the lists might still be quite long (which 
is okay). For example, I do expect the 'time_t' list will
remain long.

Some of your items in the 'timer_t' list definitely don't
belong (timer_getoverrun, timer_delete).

The 'sigval' list looks about right.

I think the 'timeval' list could be trimmed back a bit.

Thanks,

Michael

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

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hello Alex,

Following up on your mail that I missed replying to:

On Sun, 13 Sep 2020 at 23:29, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:

[...]

> > For other types, such as timeval, timespec, etc, I don't expect
> > there are many conflicts. One case that I can think of where
> > there's a function and a struct with the same name is 'sigaction'.
> > But there's not really a problem there, since, on the one hand,
> > I don't expect that that is one of the types that should be
> > documented in system_data_types(7),
> Why not?

Well, my first thought is that the type is well documented in
sigaction(2). But, now I wonder if maybe the type should also be
documented in system_data_types(7).

[...]

> New question:
>
> I've already started and I'm writing the short description on 'time_t'.
>
> POSIX has copyright and all rights reserved, but do you think it would
> be fair use to copy descriptions such as "Used for time in seconds."?
> Or do I have to come up with a new short description?

I think quoting POSIX is fine (fair use etc.), but we must be explicit
about it, as I noted in my other mail in another thread a few minutes
ago [1].

Thanks,

Michael

[1] https://lore.kernel.org/linux-man/20200922153822.33728-2-colomar.6.4.3@gmail.com/T/#m4eeb425aca975ded062fc36ada62dc4935eb4f67
-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/

Re: [IDEA] New pages for types: structs and typedfefs

[Thorsten Glaser]

Michael Kerrisk (man-pages) dixit:

>I think quoting POSIX is fine (fair use etc.)

“fair use” only applies to the USA. For pieces quoted under
USA “fair use” copyright still applies in all other countries,
and, worse, you can’t issue a licence for it (as you don’t own
it).

https://pubs.opengroup.org/onlinepubs/9699919799/frontmatter/notice.html
specifically reserves the copyright for POSIX.

https://pubs.opengroup.org/onlinepubs/9699919799/help/terms.html
specifically does not issue a licence for reproduction.

I know that some POSIX documents were re-released under a free-ish
licence some time ago for inclusion into some manual pages, but I
don’t have a reference for that and don’t know the scope.

Please get explicit permission from The Open Group before quoting
from POSIX in anything you intend to distribute to the general public.

Thanks,
//mirabilos (current hat: Debian Developer nōn-US)
-- 
I believe no one can invent an algorithm. One just happens to hit upon it
when God enlightens him. Or only God invents algorithms, we merely copy them.
If you don't believe in God, just consider God as Nature if you won't deny
existence.		-- Coywolf Qi Hunt

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

[Thorsten, I have removed you from the CC because I get persistent
bounce messages whenever I send you mail. Hopefully you see this reply
via the list.]

Thorsten, thanks for your input.

On Tue, 22 Sep 2020 at 22:40, Thorsten Glaser <tg@mirbsd.org> wrote:
>
> Michael Kerrisk (man-pages) dixit:
>
> >I think quoting POSIX is fine (fair use etc.)
>
> “fair use” only applies to the USA. For pieces quoted under
> USA “fair use” copyright still applies in all other countries,
> and, worse, you can’t issue a licence for it (as you don’t own
> it).

Yes, it's complicated in theory at least. (I suspect it's simpler in practice.)

> https://pubs.opengroup.org/onlinepubs/9699919799/frontmatter/notice.html
> specifically reserves the copyright for POSIX.
>
> https://pubs.opengroup.org/onlinepubs/9699919799/help/terms.html
> specifically does not issue a licence for reproduction.

Obviously, it is a gray area, but there's a significant difference
between quoting a sentence or three from the standard and
reproducing/redistributing the standard.

> I know that some POSIX documents were re-released under a free-ish
> licence some time ago for inclusion into some manual pages, but I
> don’t have a reference for that and don’t know the scope.

Yes:
https://lwn.net/Articles/581858/

> Please get explicit permission from The Open Group before quoting
> from POSIX in anything you intend to distribute to the general public.

While I'm pretty sure they would allow this without problem, I'm
wondering if it's worth the effort. Ideally, we'd have text written by
someone in their own words. Reproducing the text of the standard has
limited value, since people can in any case consult the standard
directly.

Alex, how about we just go much simpler, saying something like:

[[
This type represents floating-point status flags; for further details
see fenv(3).
]]

Thanks,

Michael

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

Re: [IDEA] New pages for types: structs and typedfefs

[Thorsten Glaser]

Michael Kerrisk (man-pages) dixit:

>[Thorsten, I have removed you from the CC because I get persistent
>bounce messages whenever I send you mail. Hopefully you see this reply
>via the list.]

(I’m doing the same, Googlemail doesn’t work with standard eMail.)

>Obviously, it is a gray area, but there's a significant difference
>between quoting a sentence or three from the standard and
>reproducing/redistributing the standard.

True, but taking quotes is severely restricted at least in Germany.
That being said, if the quoted parts are trivial enough to not fall
under copyright or if copyright exemption due to interop applies,
it won’t be a problem… but better try to avoid it altogether.

>> I know that some POSIX documents were re-released under a free-ish
>> licence some time ago for inclusion into some manual pages, but I
>> don’t have a reference for that and don’t know the scope.
>
>Yes:
>https://lwn.net/Articles/581858/

Ah, great!

>While I'm pretty sure they would allow this without problem, I'm
>wondering if it's worth the effort. Ideally, we'd have text written by
>someone in their own words. Reproducing the text of the standard has
>limited value, since people can in any case consult the standard
>directly.

Right.

>Alex, how about we just go much simpler, saying something like:
>
>[[
>This type represents floating-point status flags; for further details
>see fenv(3).
>]]

Yes, referencing the already-existing “donated” pages would work
the best.

Thanks!

bye,
//mirabilos
-- 
Stéphane, I actually don’t block Googlemail, they’re just too utterly
stupid to successfully deliver to me (or anyone else using Greylisting
and not whitelisting their ranges). Same for a few other providers such
as Hotmail.

Re: [IDEA] New pages for types: structs and typedfefs

[Jakub Wilk]

* Michael Kerrisk <mtk.manpages@gmail.com>, 2020-09-13, 14:01:
>>No, I don't have a PDF.  I usually search here:
>>
>>https://pubs.opengroup.org/onlinepubs/9699919799/
>
>You can get a PDF by registering as a member of The Open Group.

Alternatively, you could download HTML versions of the standards:

https://pubs.opengroup.org/onlinepubs/007908799/download/susv2.tar.bz2 
https://pubs.opengroup.org/onlinepubs/007904975/download/susv3.tar.bz2 
https://pubs.opengroup.org/onlinepubs/9699919799/download/susv4-2018.tar.bz2

These should be even more greppable than the PDFs. (But I admit I've 
never seen the PDFs. I found the The Open Group registration form too 
intimidating.)

-- 
Jakub Wilk

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

On 9/14/20 11:19 AM, Jakub Wilk wrote:
> * Michael Kerrisk <mtk.manpages@gmail.com>, 2020-09-13, 14:01:
>>> No, I don't have a PDF.  I usually search here:
>>>
>>> https://pubs.opengroup.org/onlinepubs/9699919799/
>>
>> You can get a PDF by registering as a member of The Open Group.
> 
> Alternatively, you could download HTML versions of the standards:
> 
> https://pubs.opengroup.org/onlinepubs/007908799/download/susv2.tar.bz2
> https://pubs.opengroup.org/onlinepubs/007904975/download/susv3.tar.bz2
> https://pubs.opengroup.org/onlinepubs/9699919799/download/susv4-2018.tar.bz2
> 
> 
> These should be even more greppable than the PDFs. (But I admit I've
> never seen the PDFs. I found the The Open Group registration form too
> intimidating.)
> 


Great!

Thanks,

Alex

Re: [IDEA] New pages for types: structs and typedfefs

[Guillem Jover]

Hi!

[ I see this has already been merged, just giving some little context,
  from the libbsd side. :) ]

On Sun, 2020-09-13 at 14:01:22 +0200, Michael Kerrisk (man-pages) wrote:
> On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar <colomar.6.4.3@gmail.com> wrote:
> > On 2020-09-12 08:33, Michael Kerrisk (man-pages) wrote:
> >  > Your not the first to suggest this. Most recently, if I recall
> >  > correctly, Florian also suggested it.
> >  >
> >  > The idea seems reasonable, but I wonder about the best way of doing it.

Yes, this sounds great, this is also something I've missed from time
to time. :)

> > libbsd already provides a few pages on types.  Maybe we could have a
> > look at them.  At least I've seen 'man timespec' (which redirects to
> > timeval.3bsd):
> >
> > https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/master/man/timeval.3bsd

Ah, timespec.3bsd is actually (at least) a man-db construct, libbsd
does not install an actual link on disk, I assume the .Nm macros in
the .Sh NAME section are being indexed. I should add such explicit
link for completeness though, thanks!

> >  > Then of course, we'd need to have links to that page, so that
> >  > people could just type 'man timer_t'. What section should the links
> >  > be in? The reasonable candidates would be section 3 or 7. I'm not
> >  > yet sure which is better. But the point is that we'd have files
> >  > such as timer_t.3 (or timer_t.7) that are link pages containing the
> >  > line:
> >  >
> >  >      .so man7/system_data_types.7
> >
> > Sure.  And for the structs, I'd allow:
> >
> > 'man struct timespec'   (For simplicity)
> > 'man struct-timespec'   (Similar to the git man pages)
> > 'man timespec'          (For compatibility with libbsd)
> 
> Mainly, I'm interested in the last case. That's the one I think that
> people would most likely use. In a follow-up mail, you expressed
> concern with conflicts with libbsd pages. I'm not too worried about
> that. There are already *many* conflicts between libbsd and man-pages.

In libbsd I try to have man pages for at least every function and macro,
ideally originating from the related BSD. The timeval.3bsd came mostly
out of a need to document the TIMEVAL_TO_TIMESPEC and TIMESPEC_TO_TIMEVAL
macros, and finding this on NetBSD:

  <http://man.netbsd.org/timeval.3>

and they do seem to have dedicated man pages for some other
structures, which seems rather nice, and indeed worth imitating.

Regarding conflicts, I specifically chose to place all libbsd man
pages in the 3bsd section (both in filename and in the .Dt macro, to
avoid an actual conflict, and to not override the system man pages.
So once a man page appears in say man-pages, then that will take
precedence:

  $ man explicit_bzero # man-pages version recentish addition

vs

  $ man 3bsd explicit_bzero # libbsd version

Thanks,
Guillem

Re: [IDEA] New pages for types: structs and typedfefs

[Michael Kerrisk (man-pages)]

Hello Guillem

On Fri, 18 Sep 2020 at 04:16, Guillem Jover <guillem@hadrons.org> wrote:
> Regarding conflicts, I specifically chose to place all libbsd man
> pages in the 3bsd section (both in filename and in the .Dt macro, to
> avoid an actual conflict, and to not override the system man pages.
> So once a man page appears in say man-pages, then that will take
> precedence:
>
>   $ man explicit_bzero # man-pages version recentish addition
>
> vs
>
>   $ man 3bsd explicit_bzero # libbsd version

Yes. Thanks for arranging things that way!

Cheers,

Michael


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

Re: [IDEA] New pages for types: structs and typedfefs

[Alejandro Colomar]

Here's a link to my branch where I'm developing system_data_types.7 and
the many link pages:

https://github.com/alejandro-colomar/man-pages/tree/system_data_types

I'll usually send an update to this thread from time to time, in the
form of a single commit, to ask for comments.

However, to find the latest version, and also see a detailed commit
history of the changes, you can follow that link.

Alex

[RFC v2] system_data_types.7: Draft v2

[Alejandro Colomar]

Changelog since Draft v1:

- Fix includes for timer_t: remove <time.h>
- tfix
- Clarify POSIX requirements
- Remove subsections, and instead use full names for structs/unions
- Includes: ffix
- Conforming to: ffix
- struct timespec: update "see also"
- Add suseconds_t
- Remove old comments

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

On 2020-09-14 12:37, Michael Kerrisk (man-pages) wrote:
> Good. I think that we can get away with just mentioning one each of
> POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
> far enough back in time that we don't need to clutter the page with
> it. Something like:
> 
> Conforming to: C99 and later; POSIX.1-2001 and later.

OK.

> Instead, I looked inside the pages that you listed to see which APIs
> seemed "relevant".

Work in progress.  I'll do it for the other types soon.

> You better include suseconds_t in the next draft:-).

:-)

> Having seen how it looks with the header files, I'm going to suggest a
> differnt approach. Let's put them on a separate line, something like:
> 
> Obtained by including: <abc.h> or <xyz.h>

I simplified it to just:

Include: <asd.h> or <qwe.h>

> It's an open question whether the links should be in section 3 or
> section 7. Do you have any thoughts on what's better?

All sources I could find talk about section 3 as a section containing
all C "library functions".
Types don't exactly fit in that description, but it could be stretched
a bit to contain all C "library definitions".

Also, libbsd already chose section 3, and I don't see a strong reason
against it, so maybe we could follow that pattern.

I would still have system_data_types.7 in section 7, as it doesn't
match the name of any library definition.

BTW, would you also add "struct-" and "union-" link pages?:

man3/struct-timespec.3   |   1 +
man3/timespec.3          |   1 +

instead of

man3/timespec.3          |   1 +

> Don't get wrapped up in including too many more types in the
> yet, while we try to iron out the format.
> 
> Also, I'd like to see the types added incrementally (one or a few
> at a time), so that it's easy to comment on each type, when needed.

Agree.

Thanks,

Alex


 man3/sigval.3            |   1 +
 man3/suseconds_t.3       |   1 +
 man3/time_t.3            |   1 +
 man3/timer_t.3           |   1 +
 man3/timespec.3          |   1 +
 man3/timeval.3           |   1 +
 man7/system_data_types.7 | 227 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 233 insertions(+)
 create mode 100644 man3/sigval.3
 create mode 100644 man3/suseconds_t.3
 create mode 100644 man3/time_t.3
 create mode 100644 man3/timer_t.3
 create mode 100644 man3/timespec.3
 create mode 100644 man3/timeval.3
 create mode 100644 man7/system_data_types.7

diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8b89a46f3
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,227 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Check specific POSIX "Conforming to" versions
+.\"	* Correctly highlight function names and similar (see timer_t)
+.TP
+.BI "struct " timespec
+.IP
+Include:
+.I <time.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR clock_getres (2),
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.\".BR futex (2),
+.\".BR io_getevents (2),
+.BR nanosleep (2),
+.\".BR poll (2),
+.\".BR recvmmsg (2),
+.\".BR sched_rr_get_interval (2),
+.\".BR select (2),
+.\".BR semop (2),
+.\".BR sigwaitinfo (2),
+.\".BR stat (2),
+.\".BR timerfd_create (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.\".BR timer_settime (2),
+.\".BR utimensat (2),
+.\".BR aio_suspend (3),
+.\".BR clock_getcpuclockid (3),
+.\".BR getaddrinfo_a (3),
+.\".BR mq_receive (3),
+.\".BR mq_send (3),
+.\".BR pthread_getcpuclockid (3),
+.\".BR pthread_tryjoin_np (3),
+.\".BR sem_wait (3),
+.\".BR socket (7)
+.TP
+.BI "struct " timeval
+.IP
+Include:
+.I <sys/time.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR adjtimex (2),
+.BR futimesat (2),
+.BR getitimer (2),
+.BR getpriority (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR utime (2),
+.BR wait4 (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR ntp_gettime (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3),
+.BR utmp (5),
+.BR packet (7),
+.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
+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)
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+.IP
+Used for time in seconds.
+In POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR gettimeofday (2),
+.BR io_getevents (2),
+.BR keyctl (2),
+.BR msgctl (2),
+.BR msgop (2),
+.BR nanosleep (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semctl (2),
+.BR shmctl (2),
+.BR stat (2),
+.BR stime (2),
+.BR time (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR times (2),
+.BR utime (2),
+.BR utimensat (2),
+.BR adjtime (3),
+.BR ctime (3),
+.BR difftime (3),
+.BR ftime (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR newlocale (3),
+.BR ntp_gettime (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_tryjoin_np (3),
+.BR rtime (3),
+.BR sem_wait (3),
+.BR strcat (3),
+.BR strftime (3),
+.BR timegm (3),
+.BR timeradd (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+.IP
+Used for timer ID returned by timer_create().
+There are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.BI "union " sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with notification.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
-- 
2.28.0

Re: [RFC v2] system_data_types.7: Draft v2

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/14/20 4:03 PM, Alejandro Colomar wrote:
> Changelog since Draft v1:
> 
> - Fix includes for timer_t: remove <time.h>
> - tfix
> - Clarify POSIX requirements
> - Remove subsections, and instead use full names for structs/unions

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

> - Includes: ffix
> - Conforming to: ffix
> - struct timespec: update "see also"
> - Add suseconds_t
> - Remove old comments
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> On 2020-09-14 12:37, Michael Kerrisk (man-pages) wrote:
>> Good. I think that we can get away with just mentioning one each of
>> POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
>> far enough back in time that we don't need to clutter the page with
>> it. Something like:
>>
>> Conforming to: C99 and later; POSIX.1-2001 and later.
> 
> OK.
> 
>> Instead, I looked inside the pages that you listed to see which APIs
>> seemed "relevant".
> 
> Work in progress.  I'll do it for the other types soon.

Okay. I'll make a few notes below.

>> You better include suseconds_t in the next draft:-).
> 
> :-)
> 
>> Having seen how it looks with the header files, I'm going to suggest a
>> differnt approach. Let's put them on a separate line, something like:
>>
>> Obtained by including: <abc.h> or <xyz.h>
> 
> I simplified it to just:
> 
> Include: <asd.h> or <qwe.h>

Yes, better.

>> It's an open question whether the links should be in section 3 or
>> section 7. Do you have any thoughts on what's better?
> 
> All sources I could find talk about section 3 as a section containing
> all C "library functions".
> Types don't exactly fit in that description, but it could be stretched
> a bit to contain all C "library definitions".
> 
> Also, libbsd already chose section 3, and I don't see a strong reason
> against it, so maybe we could follow that pattern.

Thanks. I forgot that libbsd detail. Yes, let's go with Section 3.

> I would still have system_data_types.7 in section 7, as it doesn't
> match the name of any library definition.

Yes.

> BTW, would you also add "struct-" and "union-" link pages?:
> 
> man3/struct-timespec.3   |   1 +
> man3/timespec.3          |   1 +
> 
> instead of
> 
> man3/timespec.3          |   1 +

I think just one link: the name of the type (without any
"struct" or "union")

>> Don't get wrapped up in including too many more types in the
>> yet, while we try to iron out the format.
>>
>> Also, I'd like to see the types added incrementally (one or a few
>> at a time), so that it's easy to comment on each type, when needed.
> 
> Agree.
> 
> Thanks,
> 
> Alex

A few further comments below.
> 
>  man3/sigval.3            |   1 +
>  man3/suseconds_t.3       |   1 +
>  man3/time_t.3            |   1 +
>  man3/timer_t.3           |   1 +
>  man3/timespec.3          |   1 +
>  man3/timeval.3           |   1 +
>  man7/system_data_types.7 | 227 +++++++++++++++++++++++++++++++++++++++
>  7 files changed, 233 insertions(+)
>  create mode 100644 man3/sigval.3
>  create mode 100644 man3/suseconds_t.3
>  create mode 100644 man3/time_t.3
>  create mode 100644 man3/timer_t.3
>  create mode 100644 man3/timespec.3
>  create mode 100644 man3/timeval.3
>  create mode 100644 man7/system_data_types.7
> 
> diff --git a/man3/sigval.3 b/man3/sigval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/suseconds_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/time_t.3 b/man3/time_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/time_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timer_t.3 b/man3/timer_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timer_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timespec.3 b/man3/timespec.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timespec.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timeval.3 b/man3/timeval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timeval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..8b89a46f3
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,227 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\"	* Add types
> +.\"	* Check specific POSIX "Conforming to" versions
> +.\"	* Correctly highlight function names and similar (see timer_t)
> +.TP
> +.BI "struct " timespec
> +.IP
> +Include:
> +.I <time.h>
> +.IP
> +.EX
> +struct timespec {
> +    time_t  tv_sec;  /* Seconds */
> +    long    tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.\".BR clock_getres (2),
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.\".BR futex (2),
> +.\".BR io_getevents (2),
> +.BR nanosleep (2),
> +.\".BR poll (2),
> +.\".BR recvmmsg (2),
> +.\".BR sched_rr_get_interval (2),
> +.\".BR select (2),
> +.\".BR semop (2),
> +.\".BR sigwaitinfo (2),
> +.\".BR stat (2),
> +.\".BR timerfd_create (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.\".BR timer_settime (2),
> +.\".BR utimensat (2),
> +.\".BR aio_suspend (3),
> +.\".BR clock_getcpuclockid (3),
> +.\".BR getaddrinfo_a (3),
> +.\".BR mq_receive (3),
> +.\".BR mq_send (3),
> +.\".BR pthread_getcpuclockid (3),
> +.\".BR pthread_tryjoin_np (3),
> +.\".BR sem_wait (3),
> +.\".BR socket (7)
> +.TP
> +.BI "struct " timeval
> +.IP
> +Include:
> +.I <sys/time.h>

or <sys/select.h>
(Really, a PDF copy of the standard is gpoing to help...)

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

> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:

I think there are several in the following list that should be removed...

> +.BR adjtimex (2),
> +.BR futimesat (2),
> +.BR getitimer (2),
> +.BR getpriority (2),
> +.BR getrusage (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR syscall (2),
> +.BR syscalls (2),
> +.BR utime (2),
> +.BR wait4 (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR ntp_gettime (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3),
> +.BR utmp (5),
> +.BR packet (7),
> +.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/

> +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 :-).

How about just saying: 

[[
This type is used for one of the 
fields of the timeval structure (see below).
]]

> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +.IP
> +Used for time in seconds.
> +In POSIX, it shall be an integer type.

s/In/According to/

> +.IP
> +Conforming to: C99 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:

Many items in the following list should go...

> +.BR clock_getres (2),
> +.BR clock_nanosleep (2),
> +.BR getitimer (2),
> +.BR gettimeofday (2),
> +.BR io_getevents (2),
> +.BR keyctl (2),
> +.BR msgctl (2),
> +.BR msgop (2),
> +.BR nanosleep (2),
> +.BR sched_rr_get_interval (2),
> +.BR select (2),
> +.BR semctl (2),
> +.BR shmctl (2),
> +.BR stat (2),
> +.BR stime (2),
> +.BR time (2),
> +.BR timerfd_create (2),
> +.BR timer_settime (2),
> +.BR times (2),
> +.BR utime (2),
> +.BR utimensat (2),
> +.BR adjtime (3),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR ftime (3),
> +.BR mq_receive (3),
> +.BR mq_send (3),
> +.BR newlocale (3),
> +.BR ntp_gettime (3),
> +.BR pthread_cleanup_push (3),
> +.BR pthread_tryjoin_np (3),
> +.BR rtime (3),
> +.BR sem_wait (3),
> +.BR strcat (3),
> +.BR strftime (3),
> +.BR timegm (3),
> +.BR timeradd (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:

Add "<time.h> or"

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

> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.BI "union " sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> +    int     sigval_int; /* Integer value */
> +    void   *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with notification.

s/notification/a signal/

> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)

Thanks,

Michael


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

Re: [RFC v2] system_data_types.7: Draft v2

[Alejandro Colomar]

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.

>> BTW, would you also add "struct-" and "union-" link pages?:
>>
>> man3/struct-timespec.3   |   1 +
>> man3/timespec.3          |   1 +
>>
>> instead of
>>
>> man3/timespec.3          |   1 +
> 
> I think just one link: the name of the type (without any
> "struct" or "union")

OK.

>> +.TP
>> +.BI "struct " timeval
>> +.IP
>> +Include:
>> +.I <sys/time.h>
> 
> or <sys/select.h>

True.

> (Really, a PDF copy of the standard is gpoing to help...)

I already have a login, and it works, but when I try to download the PDF
(just after accepting terms and conditions in downloads), another login
prompt appears and I can't log in that one.  I'll email them.

But for now I can live with the HTML version.

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

???

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> 
> I think there are several in the following list that should be removed...

Probably.  I'll have a look at them later.

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

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

> 
>> +.TP
>> +.I time_t
>> +.IP
>> +Include:
>> +.I <time.h>
>> +or
>> +.I <sys/types.h>
>> +.IP
>> +Used for time in seconds.
>> +In POSIX, it shall be an integer type.
> 
> s/In/According to/

OK.

> 
>> +.IP
>> +Conforming to: C99 and later; POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> 
> Many items in the following list should go...

Yes

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

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR timer_create (2),
>> +.BR timer_delete (2),
>> +.BR timer_getoverrun (2),
>> +.BR timer_settime (2)
>> +.TP
>> +.BI "union " sigval
>> +.IP
>> +Include:
>> +.I <signal.h>
>> +.IP
>> +.EX
>> +union sigval {
>> +    int     sigval_int; /* Integer value */
>> +    void   *sigval_ptr; /* Pointer value */
>> +};
>> +.EE
>> +.IP
>> +Data passed with notification.
> 
> s/notification/a signal/

OK.

> 
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR rt_sigqueueinfo (2),
>> +.BR sigaction (2),
>> +.BR mq_notify (3),
>> +.BR pthread_sigqueue (3),
>> +.BR sigqueue (3),
>> +.BR sigevent (7)
> 
> Thanks,
> 
> Michael
> 
> 

Thanks,

Alex

Re: [RFC v2] system_data_types.7: Draft v2

[Michael Kerrisk (man-pages)]

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/

[RFC v3] sigval.3, ssize_t.3, suseconds_t.3, time_t.3, timer_t.3, timespec.3, timeval.3, system_data_types.7: Document system types (draft v3)

[Alejandro Colomar]

Changelog since dratf v2:

- Remove struct/union keywords from list of type names (and sort)
- wfix
- ffix
- Add all the headers that define each type
- Specify the layout of the list in a comment
- Add size_t type (I had to do it :-)


Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

On 9/14/20 9:33 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On 9/14/20 5:52 PM, Alejandro Colomar wrote:
>> Hi Michael,


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

Yes, it looks nicer (the eye doesn't need to move to the right at each
struct/union) so it is visually easier to find the types.

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

Agreed.

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

The list is rather long, but now I don't deel it's too much, and it has
some value.  I'd keep all of them.  See my comment (Layout) in the page,
and feel free to add to/modify it.

> Good progress so far. Thanks, Alex!
>
> Cheers,
>
> Michael

Thank you too, Michael!

Cheers,

Alex

 man3/sigval.3            |   1 +
 man3/ssize_t.3           |   1 +
 man3/suseconds_t.3       |   1 +
 man3/time_t.3            |   1 +
 man3/timer_t.3           |   1 +
 man3/timespec.3          |   1 +
 man3/timeval.3           |   1 +
 man7/system_data_types.7 | 349 +++++++++++++++++++++++++++++++++++++++
 8 files changed, 356 insertions(+)
 create mode 100644 man3/sigval.3
 create mode 100644 man3/ssize_t.3
 create mode 100644 man3/suseconds_t.3
 create mode 100644 man3/time_t.3
 create mode 100644 man3/timer_t.3
 create mode 100644 man3/timespec.3
 create mode 100644 man3/timeval.3
 create mode 100644 man7/system_data_types.7

diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/ssize_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..dd93c6746
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,349 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Check specific POSIX "Conforming to" versions
+.\"	* Correctly highlight function names and similar (see timer_t)
+.\"	* Curate "See also"
+.\" Layout:
+.\"	A list of type names (the struct/union keyword will be omitted).
+.\"	Each entry will have the following parts:
+.\"		* Include
+.\"			The headers will be in the following order:
+.\"			1) The header(s) that shall define the type
+.\"			   according to the C standard,
+.\"			   in alphabetical order.
+.\"			2) The header that shall define the type
+.\"			   according to POSIX.
+.\"			3) All other headers that shall define the type
+.\"			   as described in the previous header
+.\"			   according to POSIX,
+.\"			   in alphabetical order.
+.\"			4) All other headers that define the type
+.\"			   that are Linux specific,
+.\"			   in alphabetical order.
+.\"
+.\"		* Definition (no "Definition" header)
+.\"			Only struct/union types will have definition;
+.\"			typedefs will remain opaque.
+.\"
+.\"		* Description (no "Description" header)
+.\"			A few lines describing the type.
+.\"
+.\"		* Conforming to
+.\"			example: CXY and later; POSIX.1-XXXX and later
+.\"			Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\"		* Notes (optional)
+.\"
+.\"		* See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR TODO (XXX),
+.BR TODO (may be too large)
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+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)
+.IP
+See also the
+.B timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR gettimeofday (2),
+.BR io_getevents (2),
+.BR keyctl (2),
+.BR msgctl (2),
+.BR msgop (2),
+.BR nanosleep (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semctl (2),
+.BR shmctl (2),
+.BR stat (2),
+.BR stime (2),
+.BR time (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR times (2),
+.BR utime (2),
+.BR utimensat (2),
+.BR adjtime (3),
+.BR ctime (3),
+.BR difftime (3),
+.BR ftime (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR newlocale (3),
+.BR ntp_gettime (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_tryjoin_np (3),
+.BR rtime (3),
+.BR sem_wait (3),
+.BR strcat (3),
+.BR strftime (3),
+.BR timegm (3),
+.BR timeradd (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+There are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR clock_getres (2),
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.\".BR futex (2),
+.\".BR io_getevents (2),
+.BR nanosleep (2),
+.\".BR poll (2),
+.\".BR recvmmsg (2),
+.\".BR sched_rr_get_interval (2),
+.\".BR select (2),
+.\".BR semop (2),
+.\".BR sigwaitinfo (2),
+.\".BR stat (2),
+.\".BR timerfd_create (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.\".BR timer_settime (2),
+.\".BR utimensat (2),
+.\".BR aio_suspend (3),
+.\".BR clock_getcpuclockid (3),
+.\".BR getaddrinfo_a (3),
+.\".BR mq_receive (3),
+.\".BR mq_send (3),
+.\".BR pthread_getcpuclockid (3),
+.\".BR pthread_tryjoin_np (3),
+.\".BR sem_wait (3),
+.\".BR socket (7)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR adjtimex (2),
+.BR futimesat (2),
+.BR getitimer (2),
+.BR getpriority (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR utime (2),
+.BR wait4 (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR ntp_gettime (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3),
+.BR utmp (5),
+.BR packet (7),
+.BR socket (7)
-- 
2.28.0

Re: [RFC v3] sigval.3, ssize_t.3, suseconds_t.3, time_t.3, timer_t.3, timespec.3, timeval.3, system_data_types.7: Document system types (draft v3)

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/15/20 2:47 AM, Alejandro Colomar wrote:
> Changelog since dratf v2:
> 
> - Remove struct/union keywords from list of type names (and sort)
> - wfix
> - ffix
> - Add all the headers that define each type
> - Specify the layout of the list in a comment
> - Add size_t type (I had to do it :-)
> 
> 
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---

[...]

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

Okay -- so you showed me otherwise :-).

> The list is rather long, but now I don't deel it's too much, and it has
> some value.  I'd keep all of them.  See my comment (Layout) in the page,
> and feel free to add to/modify it.

I think I agree.

>> Good progress so far. Thanks, Alex!
>>
>> Cheers,
>>
>> Michael
> 
> Thank you too, Michael!

By now, I think we're getting pretty close. I have a few small 
comments below, but other than that, I think once the details
of individual types have been fixed, I think we're good to go.

>  man3/sigval.3            |   1 +
>  man3/ssize_t.3           |   1 +
>  man3/suseconds_t.3       |   1 +
>  man3/time_t.3            |   1 +
>  man3/timer_t.3           |   1 +
>  man3/timespec.3          |   1 +
>  man3/timeval.3           |   1 +
>  man7/system_data_types.7 | 349 +++++++++++++++++++++++++++++++++++++++
>  8 files changed, 356 insertions(+)
>  create mode 100644 man3/sigval.3
>  create mode 100644 man3/ssize_t.3
>  create mode 100644 man3/suseconds_t.3
>  create mode 100644 man3/time_t.3
>  create mode 100644 man3/timer_t.3
>  create mode 100644 man3/timespec.3
>  create mode 100644 man3/timeval.3
>  create mode 100644 man7/system_data_types.7

Let's have two patches. One for the initial page, and then one for
the links.  When adding other types later, the same thing: a patch 
for the added text, and a separate patch for the link(s). This
makes it a little easier for my scripts that generate the changelog.

> diff --git a/man3/sigval.3 b/man3/sigval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/ssize_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/suseconds_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/time_t.3 b/man3/time_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/time_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timer_t.3 b/man3/timer_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timer_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timespec.3 b/man3/timespec.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timespec.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timeval.3 b/man3/timeval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timeval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..dd93c6746
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,349 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\"	* Add types
> +.\"	* Check specific POSIX "Conforming to" versions
> +.\"	* Correctly highlight function names and similar (see timer_t)
> +.\"	* Curate "See also"
> +.\" Layout:
> +.\"	A list of type names (the struct/union keyword will be omitted).
> +.\"	Each entry will have the following parts:
> +.\"		* Include
> +.\"			The headers will be in the following order:
> +.\"			1) The header(s) that shall define the type
> +.\"			   according to the C standard,
> +.\"			   in alphabetical order.
> +.\"			2) The header that shall define the type
> +.\"			   according to POSIX.
> +.\"			3) All other headers that shall define the type
> +.\"			   as described in the previous header
> +.\"			   according to POSIX,
> +.\"			   in alphabetical order.
> +.\"			4) All other headers that define the type
> +.\"			   that are Linux specific,
> +.\"			   in alphabetical order.

I think the reader won't easily deduce the above ordering.
I think just the following will be fine:
* (1)/(2) (merged is fine)
* The rest, ordered alphabetically.

> +.\"
> +.\"		* Definition (no "Definition" header)
> +.\"			Only struct/union types will have definition;
> +.\"			typedefs will remain opaque.
> +.\"
> +.\"		* Description (no "Description" header)
> +.\"			A few lines describing the type.
> +.\"
> +.\"		* Conforming to
> +.\"			example: CXY and later; POSIX.1-XXXX and later
> +.\"			Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\"		* Notes (optional)
> +.\"
> +.\"		* See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> +    int     sigval_int; /* Integer value */
> +    void   *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>
> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR TODO (XXX),
> +.BR TODO (may be too large)
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:

Above two lines should also be commented out.

> +.\".BR getitimer (2),
> +.\".BR gettimeofday (2),
> +.\".BR select (2),
> +.\".BR adjtime (3),
> +.\".BR ntp_gettime (3),
> +.\".BR timeval (3),
> +.\".BR timeradd (3)
> +.IP
> +See also the
> +.B timeval

s/.B/.I/

> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-xxxx and later.
> +.IP

Just a placeholder note that the following lis still needs trimming/tuning.

> +See also:
> +.BR clock_getres (2),
> +.BR clock_nanosleep (2),
> +.BR getitimer (2),
> +.BR gettimeofday (2),
> +.BR io_getevents (2),
> +.BR keyctl (2),
> +.BR msgctl (2),
> +.BR msgop (2),
> +.BR nanosleep (2),
> +.BR sched_rr_get_interval (2),
> +.BR select (2),
> +.BR semctl (2),
> +.BR shmctl (2),
> +.BR stat (2),
> +.BR stime (2),
> +.BR time (2),
> +.BR timerfd_create (2),
> +.BR timer_settime (2),
> +.BR times (2),
> +.BR utime (2),
> +.BR utimensat (2),
> +.BR adjtime (3),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR ftime (3),
> +.BR mq_receive (3),
> +.BR mq_send (3),
> +.BR newlocale (3),
> +.BR ntp_gettime (3),
> +.BR pthread_cleanup_push (3),
> +.BR pthread_tryjoin_np (3),
> +.BR rtime (3),
> +.BR sem_wait (3),
> +.BR strcat (3),
> +.BR strftime (3),
> +.BR timegm (3),
> +.BR timeradd (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +There are no defined comparison or assignment operators for this type.

I think the above sentence should better start with something like
"According to POSIX..."

> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>
> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>
> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>
> +.IP
> +.EX
> +struct timespec {
> +    time_t  tv_sec;  /* Seconds */
> +    long    tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.\".BR clock_getres (2),
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.\".BR futex (2),
> +.\".BR io_getevents (2),
> +.BR nanosleep (2),
> +.\".BR poll (2),
> +.\".BR recvmmsg (2),
> +.\".BR sched_rr_get_interval (2),
> +.\".BR select (2),
> +.\".BR semop (2),
> +.\".BR sigwaitinfo (2),
> +.\".BR stat (2),
> +.\".BR timerfd_create (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.\".BR timer_settime (2),
> +.\".BR utimensat (2),
> +.\".BR aio_suspend (3),
> +.\".BR clock_getcpuclockid (3),
> +.\".BR getaddrinfo_a (3),
> +.\".BR mq_receive (3),
> +.\".BR mq_send (3),
> +.\".BR pthread_getcpuclockid (3),
> +.\".BR pthread_tryjoin_np (3),
> +.\".BR sem_wait (3),
> +.\".BR socket (7)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> +    time_t      tv_sec;  /* Seconds */
> +    suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP

Just a placeholder note that the following lis still needs trimming/tuning.

> +See also:
> +.BR adjtimex (2),
> +.BR futimesat (2),
> +.BR getitimer (2),
> +.BR getpriority (2),
> +.BR getrusage (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR syscall (2),
> +.BR syscalls (2),
> +.BR utime (2),
> +.BR wait4 (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR ntp_gettime (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3),
> +.BR utmp (5),
> +.BR packet (7),
> +.BR socket (7)

Thanks,

Michael



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

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

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

This is already a release candidate, I'd say.

Changelog since Draft v3:

- Specify POSIX versions
- ffix
- wfix
- Curate See also


On 2020-09-15 08:22, Michael Kerrisk (man-pages) wrote:
> I think the reader won't easily deduce the above ordering.
> I think just the following will be fine:
> * (1)/(2) (merged is fine)
> * The rest, ordered alphabetically.

I'm not sure I fully understood it.  Please check the updated comments.
No type required actual modifications after that change.

Basically, I merged (3) & (4).

>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> Above two lines should also be commented out.

Done

>> +See also the
>> +.B timeval
> s/.B/.I/

Done

I decided to definitively remove many of the see also links.
They were most of them junk.

Cheers,

Alex



 man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 304 insertions(+)
 create mode 100644 man7/system_data_types.7

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..9011ce74e
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Curate "See also"
+.\" Layout:
+.\"	A list of type names (the struct/union keyword will be omitted).
+.\"	Each entry will have the following parts:
+.\"		* Include
+.\"			The headers will be in the following order:
+.\"			1) The header(s) that shall define the type
+.\"			   according to the C standard,
+.\"			   in alphabetical order.
+.\"			2) The header that shall define the type
+.\"			   according to POSIX.
+.\"			3) All other headers that shall define the type
+.\"			   as described in the previous header
+.\"			   according to POSIX,
+.\"			   and
+.\"			   all other headers that define the type
+.\"			   that are Linux specific,
+.\"			   in alphabetical order.
+.\"
+.\"		* Definition (no "Definition" header)
+.\"			Only struct/union types will have definition;
+.\"			typedefs will remain opaque.
+.\"
+.\"		* Description (no "Description" header)
+.\"			A few lines describing the type.
+.\"
+.\"		* Conforming to
+.\"			example: CXY and later; POSIX.1-XXXX and later.
+.\"			Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\"		* Notes (optional)
+.\"
+.\"		* See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR copy_file_range (2),
+.BR getrandom (2),
+.BR getxattr (2),
+.BR listxattr (2),
+.BR msgrcv (2),
+.BR pread (2),
+.BR process_vm_readv (2),
+.BR read (2),
+.BR readahead (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR sendfile (2),
+.BR splice (2),
+.BR tee (2),
+.BR vmsplice (2),
+.BR write (2),
+.BR aio_return (3),
+.BR getdirentries (3),
+.BR getline (3),
+.BR mq_receive (3),
+.BR strfmon (3),
+.BR swab (3),
+.BR mq_receive (3)
+.IP
+See also the
+.I size_t
+type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.\".IP
+.\"See also:
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR timer_settime (2),
+.BR ctime (3),
+.BR difftime (3),
+.BR timegm (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR futimesat (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3)
-- 
2.28.0

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

[Michael Kerrisk (man-pages)]

Hi Alex,

On 9/15/20 3:33 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> This is already a release candidate, I'd say.

Okay. Time to nit pick :-). Do not be too dispirited,
I think we started with some of the most difficult types...

> Changelog since Draft v3:
> 
> - Specify POSIX versions
> - ffix
> - wfix
> - Curate See also

> On 2020-09-15 08:22, Michael Kerrisk (man-pages) wrote:
>> I think the reader won't easily deduce the above ordering.
>> I think just the following will be fine:
>> * (1)/(2) (merged is fine)
>> * The rest, ordered alphabetically.
> 
> I'm not sure I fully understood it.  Please check the updated comments.
> No type required actual modifications after that change.
> 
> Basically, I merged (3) & (4).

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)

[...]

>  man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 304 insertions(+)
>  create mode 100644 man7/system_data_types.7
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..9011ce74e
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,304 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\"	* Add types
> +.\"	* Curate "See also"
> +.\" Layout:
> +.\"	A list of type names (the struct/union keyword will be omitted).
> +.\"	Each entry will have the following parts:
> +.\"		* Include
> +.\"			The headers will be in the following order:
> +.\"			1) The header(s) that shall define the type
> +.\"			   according to the C standard,
> +.\"			   in alphabetical order.
> +.\"			2) The header that shall define the type
> +.\"			   according to POSIX.

See my comments above.

> +.\"			3) All other headers that shall define the type
> +.\"			   as described in the previous header
> +.\"			   according to POSIX,
> +.\"			   and
> +.\"			   all other headers that define the type
> +.\"			   that are Linux specific,
> +.\"			   in alphabetical order.
> +.\"
> +.\"		* Definition (no "Definition" header)
> +.\"			Only struct/union types will have definition;
> +.\"			typedefs will remain opaque.
> +.\"
> +.\"		* Description (no "Description" header)
> +.\"			A few lines describing the type.
> +.\"
> +.\"		* Conforming to
> +.\"			example: CXY and later; POSIX.1-XXXX and later.
> +.\"			Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\"		* Notes (optional)
> +.\"
> +.\"		* See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> +    int     sigval_int; /* Integer value */
> +    void   *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),

I think we can drop mq_notify(3). Its relationship to sigval is 
somewhat indirect, and is covered via sigevent(7).

> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:

Okay, now I look closer at these lists. How have you determined them?

> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>

The type is mentioned in the <limits.h> spec, but it is not required to 
be defined by that header. (grep is not enough; one must read the text, 
sorry :-).)

> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>

The type is mentioned in the <regex.h> spec, but it is not required to 
be defined by that header.

> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-2001 and later.

Today I learned: size_t is in C99, but ssize_t is not!

> +.IP
> +See also:

Okay -- I think this list really is rather too long; I'm not
convinced that it brings value.

I suggest dropping the pages marked XX. The remaining can serve
as the (commonly used) exemplars of APIs that use this type.

XX > +.BR copy_file_range (2),
XX > +.BR getrandom (2),
XX > +.BR getxattr (2),
XX > +.BR listxattr (2),
XX > +.BR msgrcv (2),
XX > +.BR pread (2),
XX > +.BR process_vm_readv (2),
> +.BR read (2),
XX > +.BR readahead (2),
> +.BR readlink (2),
> +.BR readv (2),
> +.BR recv (2),
> +.BR send (2),
XX > +.BR sendfile (2),
XX > +.BR splice (2),
XX > +.BR tee (2),
XX > +.BR vmsplice (2),
> +.BR write (2),
XX > +.BR aio_return (3),
XX > +.BR getdirentries (3),
XX > +.BR getline (3),
XX > +.BR mq_receive (3),
XX > +.BR strfmon (3),
XX > +.BR swab (3),
XX > +.BR mq_receive (3)
> +.IP
> +See also the
> +.I size_t
> +type in this page.

But size_t is not in this page (yet). Is it in your tree?

By the way,from my reading of POSIX.1-2008, the list of headers that 
define size_t is:

<sys/types.h>
<aio.h>
<glob.h>
<grp.h>
<iconv.h>
<monetary.h>
<mqueue.h>
<ndbm.h>
<pwd.h>
<regex.h>
<search.h>
<signal.h>
<stddef.h>
<stdio.h>
<stdlib.h>
<string.h>
<strings.h>
<sys/mman.h>
<sys/msg.h>
<sys/sem.h>
<sys/shm.h>
<sys/socket.h>
<sys/uio.h>
<time.h>
<trace.h> # But omit, because not on Linux
<unistd.h>
<wchar.h>
<wordexp.h>

> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>

The type is mentioned in the <limits.h> spec, but it is not required to
be defined by that header. grep is not enough; one must read the text,
sorry :-).

> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.\".IP
> +.\"See also:

Remove the above two lines.

> +.IP
> +See also the
> +.I timeval
> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.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.

> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:

Drop lines marked XX

> +.BR stime (2),
> +.BR time (2)XX > +.BR timer_settime (2),

(time_t turns up only as part of timespec)

> +.BR ctime (3),
> +.BR difftime (3),
XX > +.BR timegm (3)

(timegm(3) is not in POSIX; let's ignore it in this page.)

> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +According to POSIX,
> +there are no defined comparison or assignment operators for this type.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>

AFAICS, the type is mentioned in the <pthread.h> spec, but it is not 
required to be defined by that header.

> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>

AFAICS, the type is mentioned in the <semaphore.h> spec, but it is not 
required to be defined by that header.

> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>

AFAICS, the type is mentioned in the <trace.h> spec, but it is not 
required to be defined by that header.

> +.IP
> +.EX
> +struct timespec {
> +    time_t  tv_sec;  /* Seconds */
> +    long    tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.BR nanosleep (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> +    time_t      tv_sec;  /* Seconds */
> +    suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:

Let's limit things to a representative sample:

XX > +.BR futimesat (2),

futimesat() is obsolete and nonstandard.

> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR utimes (2),
> +.BR adjtime (3),
> +.BR futimes (3),
XX > +.BR rpc (3),
XX > +.BR rtime (3),

These two are probably more obscure. We don't need to mention
them, I think.

> +.BR timeradd (3)

Thanks,

Michael

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

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

[Thorsten Glaser]

Michael Kerrisk (man-pages) dixit:

>> +.\" %%%LICENSE_START(VERBATIM)
>> +.\" Permission is granted to make and distribute verbatim copies of this
>> +.\" manual provided the copyright notice and this permission notice are
>> +.\" preserved on all copies.
>> +.\"
>> +.\" Permission is granted to copy and distribute modified versions of this
>> +.\" manual under the conditions for verbatim copying, provided that the
>> +.\" entire resulting derived work is distributed under the terms of a
>> +.\" permission notice identical to this one.
>> +.\"
>> +.\" Since the Linux kernel and libraries are constantly changing, this
>> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
>> +.\" responsibility for errors or omissions, or for damages resulting from
>> +.\" the use of the information contained herein.  The author(s) may not
>> +.\" have taken the same level of care in the production of this manual,
>> +.\" which is licensed free of charge, as they might when working
>> +.\" professionally.
>> +.\"
>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>> +.\" the source, must acknowledge the copyright and authors of this work.
>> +.\" %%%LICENSE_END

I severely object.

This licence doesn’t even have an SPDX identifier, nor is it
OSI certified.

Please use a standard Open Source licence, *especially* as you
are introducing new material here.

Before submitting this eMail, I found
https://www.kernel.org/doc/man-pages/licenses.html
and if that is indeed the applicable document, please use BSD.

Thanks,
//mirabilos
-- 
I believe no one can invent an algorithm. One just happens to hit upon it
when God enlightens him. Or only God invents algorithms, we merely copy them.
If you don't believe in God, just consider God as Nature if you won't deny
existence.		-- Coywolf Qi Hunt

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

[Michael Kerrisk (man-pages)]

[CC += AEB]

On 9/16/20 2:59 AM, Thorsten Glaser wrote:
> Michael Kerrisk (man-pages) dixit:
> 
>>> +.\" %%%LICENSE_START(VERBATIM)
>>> +.\" Permission is granted to make and distribute verbatim copies of this
>>> +.\" manual provided the copyright notice and this permission notice are
>>> +.\" preserved on all copies.
>>> +.\"
>>> +.\" Permission is granted to copy and distribute modified versions of this
>>> +.\" manual under the conditions for verbatim copying, provided that the
>>> +.\" entire resulting derived work is distributed under the terms of a
>>> +.\" permission notice identical to this one.
>>> +.\"
>>> +.\" Since the Linux kernel and libraries are constantly changing, this
>>> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
>>> +.\" responsibility for errors or omissions, or for damages resulting from
>>> +.\" the use of the information contained herein.  The author(s) may not
>>> +.\" have taken the same level of care in the production of this manual,
>>> +.\" which is licensed free of charge, as they might when working
>>> +.\" professionally.
>>> +.\"
>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>>> +.\" the source, must acknowledge the copyright and authors of this work.
>>> +.\" %%%LICENSE_END
> 
> I severely object.

And as someone with no history of involvement with the man-pages project
(at least as far as I am aware), and seemingly little awareness of the 
history or practices of the project, we should listen to you because...?

To be clear: I ask that provocative question because the strident,
demanding tone of your mail rubs me the wrong way. Please take it
somewhere else than this list.

> This licence doesn’t even have an SPDX identifier, nor is it
> OSI certified.

True, though OSI is in the business of certifying software
licenses, not documentation licenses. That said, I'd have
no problem with someone attempting OSI certification of the
license or doing the mechanics of obtaining an SPDX identifier
for it.

> Please use a standard Open Source licence, *especially* as you
> are introducing new material here.

The "verbatim" license has been the most widely used license in
manual pages, almost since the inception of the project 27 years
ago. (Currently more than half of the pages carry this license.)

I don't know the origin of the license (perhaps AEB does),
but as far as I'm concerned, it is a satisfactory license for 
its purpose. And since on the one hand it is, and has been, the
most widely used license and, on the other hand, I am interested
to avoid license proliferation, it's my preferred choice for new
pages. But, as you note, there are other choices:

> Before submitting this eMail, I found
> https://www.kernel.org/doc/man-pages/licenses.html
> and if that is indeed the applicable document, please use BSD.

(Obviously) I have no objection to this license, but currently
about 5% of pages in the project use some flavor of BSD license,
and then mainly because they were lifted straight from a BSD.

Thanks,

Michael

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

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

[Andries E. Brouwer]

On Wed, Sep 16, 2020 at 10:03:13AM +0200, Michael Kerrisk (man-pages) wrote:
> [CC += AEB]
> 
>> Michael Kerrisk (man-pages) dixit:
>> 
>>>> +.\" %%%LICENSE_START(VERBATIM)
>>>> +.\" Permission is granted to make and distribute verbatim copies of this
>>>> +.\" manual provided the copyright notice and this permission notice are
>>>> +.\" preserved on all copies.
>>>> +.\"
>>>> +.\" Permission is granted to copy and distribute modified versions of this
>>>> +.\" manual under the conditions for verbatim copying, provided that the
>>>> +.\" entire resulting derived work is distributed under the terms of a
>>>> +.\" permission notice identical to this one.
>>>> +.\"
>>>> +.\" Since the Linux kernel and libraries are constantly changing, this
>>>> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
>>>> +.\" responsibility for errors or omissions, or for damages resulting from
>>>> +.\" the use of the information contained herein.  The author(s) may not
>>>> +.\" have taken the same level of care in the production of this manual,
>>>> +.\" which is licensed free of charge, as they might when working
>>>> +.\" professionally.
>>>> +.\"
>>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>>>> +.\" the source, must acknowledge the copyright and authors of this work.
>>>> +.\" %%%LICENSE_END
>> 
>> I severely object.
> 
> The "verbatim" license has been the most widely used license in
> manual pages, almost since the inception of the project 27 years
> ago. (Currently more than half of the pages carry this license.)
> 
> I don't know the origin of the license (perhaps AEB does),

Digging through old sources reveals:

I started maintaing man-pages in 1995.
My first release was man-pages-1.6.
That release contained 245 man pages with the above license.

The first release that had the above license was man-pages-1.4,
released Sep 1994 by Rik Faith.
It contained 234 man pages with the above license.
man-pages-1.4.Announce describes that there are now
238 pages with "verbatim copying" and
41 pages with "GNU General Public License".

Earlier, man-pages-1.3 (released Jun 1994) by Rik Faith had
messy copyright statements or nothing at all, and Rik Faith made
for 1.4 a serious attempt at providing each page with a proper license.

So, this text came from Rik Faith.
It mentions "this manual page", so was probably written
especially for this manpage collection.
You might ask him for further details.

Andries

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

[Michael Kerrisk (man-pages)]

Hello Andries,

It's kind of you to reply; thank you!

On Wed, 16 Sep 2020 at 12:06, Andries E. Brouwer <Andries.Brouwer@cwi.nl> wrote:
>
> On Wed, Sep 16, 2020 at 10:03:13AM +0200, Michael Kerrisk (man-pages) wrote:
> > [CC += AEB]
> >
> >> Michael Kerrisk (man-pages) dixit:
> >>
> >>>> +.\" %%%LICENSE_START(VERBATIM)
> >>>> +.\" Permission is granted to make and distribute verbatim copies of this
> >>>> +.\" manual provided the copyright notice and this permission notice are
> >>>> +.\" preserved on all copies.
> >>>> +.\"
> >>>> +.\" Permission is granted to copy and distribute modified versions of this
> >>>> +.\" manual under the conditions for verbatim copying, provided that the
> >>>> +.\" entire resulting derived work is distributed under the terms of a
> >>>> +.\" permission notice identical to this one.
> >>>> +.\"
> >>>> +.\" Since the Linux kernel and libraries are constantly changing, this
> >>>> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> >>>> +.\" responsibility for errors or omissions, or for damages resulting from
> >>>> +.\" the use of the information contained herein.  The author(s) may not
> >>>> +.\" have taken the same level of care in the production of this manual,
> >>>> +.\" which is licensed free of charge, as they might when working
> >>>> +.\" professionally.
> >>>> +.\"
> >>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
> >>>> +.\" the source, must acknowledge the copyright and authors of this work.
> >>>> +.\" %%%LICENSE_END
> >>
> >> I severely object.
> >
> > The "verbatim" license has been the most widely used license in
> > manual pages, almost since the inception of the project 27 years
> > ago. (Currently more than half of the pages carry this license.)
> >
> > I don't know the origin of the license (perhaps AEB does),
>
> Digging through old sources reveals:
>
> I started maintaing man-pages in 1995.
> My first release was man-pages-1.6.
> That release contained 245 man pages with the above license.
>
> The first release that had the above license was man-pages-1.4,
> released Sep 1994 by Rik Faith.
> It contained 234 man pages with the above license.
> man-pages-1.4.Announce describes that there are now
> 238 pages with "verbatim copying" and
> 41 pages with "GNU General Public License".
>
> Earlier, man-pages-1.3 (released Jun 1994) by Rik Faith had
> messy copyright statements or nothing at all, and Rik Faith made
> for 1.4 a serious attempt at providing each page with a proper license.
>
> So, this text came from Rik Faith.
> It mentions "this manual page", so was probably written
> especially for this manpage collection.

Thanks for the insight. I had noticed that the license wasn't there
right at the start, but that it appeared very soon afterwards. It
hadn't occurred to me that perhaps Rik might be the author of the
license.

> You might ask him for further details.

I tried a few times over the years to contact Rik on other matters,
but either I was using the wrong channels, or he didn't reply. I'll
try again via another channel.

Cheers,

Michael

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

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

[Alejandro Colomar]

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.

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

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

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

:)

Cheers,

Alex.

 man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 304 insertions(+)
 create mode 100644 man7/system_data_types.7

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..1616d858c
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Curate "See also"
+.\" Layout:
+.\"	A list of type names (the struct/union keyword will be omitted).
+.\"	Each entry will have the following parts:
+.\"		* Include
+.\"			The headers will be in the following order:
+.\"			1) The header(s) that shall define the type
+.\"			   according to the C standard,
+.\"			   in alphabetical order.
+.\"			2) The header that shall define the type
+.\"			   according to POSIX.
+.\"			3) All other headers that shall define the type
+.\"			   as described in the previous header
+.\"			   according to POSIX,
+.\"			   and
+.\"			   all other headers that define the type
+.\"			   that are Linux specific,
+.\"			   in alphabetical order.
+.\"
+.\"		* Definition (no "Definition" header)
+.\"			Only struct/union types will have definition;
+.\"			typedefs will remain opaque.
+.\"
+.\"		* Description (no "Description" header)
+.\"			A few lines describing the type.
+.\"
+.\"		* Conforming to
+.\"			Format: CXY and later; POSIX.1-XXXX and later.
+.\"			Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\"		* Notes (optional)
+.\"
+.\"		* See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR copy_file_range (2),
+.BR getrandom (2),
+.BR getxattr (2),
+.BR listxattr (2),
+.BR msgrcv (2),
+.BR pread (2),
+.BR process_vm_readv (2),
+.BR read (2),
+.BR readahead (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR sendfile (2),
+.BR splice (2),
+.BR tee (2),
+.BR vmsplice (2),
+.BR write (2),
+.BR aio_return (3),
+.BR getdirentries (3),
+.BR getline (3),
+.BR mq_receive (3),
+.BR strfmon (3),
+.BR swab (3),
+.BR mq_receive (3)
+.\".IP	FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.\".IP
+.\"See also:
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR timer_settime (2),
+.BR ctime (3),
+.BR difftime (3),
+.BR timegm (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR futimesat (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3)
-- 
2.28.0

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

[Alejandro Colomar]

Sorry, this patch is old.

Somehow I mixed the new version with this.

I'll resend it correctly in a few minutes as v6

Alex

On 2020-09-16 12:52, 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.
> 
>> 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.
> 
>> <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?
> 
>> 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!
> 
> :)
> 
> Cheers,
> 
> Alex.
> 
>   man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
>   1 file changed, 304 insertions(+)
>   create mode 100644 man7/system_data_types.7
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..1616d858c
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,304 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date.  The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein.  The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\"	* Add types
> +.\"	* Curate "See also"
> +.\" Layout:
> +.\"	A list of type names (the struct/union keyword will be omitted).
> +.\"	Each entry will have the following parts:
> +.\"		* Include
> +.\"			The headers will be in the following order:
> +.\"			1) The header(s) that shall define the type
> +.\"			   according to the C standard,
> +.\"			   in alphabetical order.
> +.\"			2) The header that shall define the type
> +.\"			   according to POSIX.
> +.\"			3) All other headers that shall define the type
> +.\"			   as described in the previous header
> +.\"			   according to POSIX,
> +.\"			   and
> +.\"			   all other headers that define the type
> +.\"			   that are Linux specific,
> +.\"			   in alphabetical order.
> +.\"
> +.\"		* Definition (no "Definition" header)
> +.\"			Only struct/union types will have definition;
> +.\"			typedefs will remain opaque.
> +.\"
> +.\"		* Description (no "Description" header)
> +.\"			A few lines describing the type.
> +.\"
> +.\"		* Conforming to
> +.\"			Format: CXY and later; POSIX.1-XXXX and later.
> +.\"			Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\"		* Notes (optional)
> +.\"
> +.\"		* See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> +    int     sigval_int; /* Integer value */
> +    void   *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>
> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR copy_file_range (2),
> +.BR getrandom (2),
> +.BR getxattr (2),
> +.BR listxattr (2),
> +.BR msgrcv (2),
> +.BR pread (2),
> +.BR process_vm_readv (2),
> +.BR read (2),
> +.BR readahead (2),
> +.BR readlink (2),
> +.BR readv (2),
> +.BR recv (2),
> +.BR send (2),
> +.BR sendfile (2),
> +.BR splice (2),
> +.BR tee (2),
> +.BR vmsplice (2),
> +.BR write (2),
> +.BR aio_return (3),
> +.BR getdirentries (3),
> +.BR getline (3),
> +.BR mq_receive (3),
> +.BR strfmon (3),
> +.BR swab (3),
> +.BR mq_receive (3)
> +.\".IP	FIXME: When size_t is added, uncomment
> +.\"See also the
> +.\".I size_t
> +.\"type in this page.
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.\".IP
> +.\"See also:
> +.IP
> +See also the
> +.I timeval
> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR stime (2),
> +.BR time (2),
> +.BR timer_settime (2),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR timegm (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +According to POSIX,
> +there are no defined comparison or assignment operators for this type.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>
> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>
> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>
> +.IP
> +.EX
> +struct timespec {
> +    time_t  tv_sec;  /* Seconds */
> +    long    tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.BR nanosleep (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> +    time_t      tv_sec;  /* Seconds */
> +    suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR futimesat (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR utimes (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3)
> 

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

[Alejandro Colomar]

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.

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

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

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

:)

Cheers,

Alex.

 man7/system_data_types.7 | 272 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 272 insertions(+)
 create mode 100644 man7/system_data_types.7

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8fc827332
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,272 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Curate "See also"
+.\" Layout:
+.\"	A list of type names (the struct/union keyword will be omitted).
+.\"	Each entry will have the following parts:
+.\"		* Include
+.\"			The headers will be in the following order:
+.\"			1) The header(s) that shall define the type
+.\"			   according to the C standard,
+.\"			   and
+.\"			   the header that shall define the type
+.\"			   according to POSIX,
+.\"			   in alphabetical order.
+.\"			2) All other headers that shall define the type
+.\"			   as described in the previous header
+.\"			   according to POSIX,
+.\"			   in alphabetical order.
+.\"			*) All headers that define the type
+.\"			   *if* the type is not defined by C nor POSIX,
+.\"			   in alphabetical order.
+.\"
+.\"		* Definition (no "Definition" header)
+.\"			Only struct/union types will have definition;
+.\"			typedefs will remain opaque.
+.\"
+.\"		* Description (no "Description" header)
+.\"			A few lines describing the type.
+.\"
+.\"		* Conforming to
+.\"			Format: CXY and later; POSIX.1-XXXX and later.
+.\"			Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\"		* Notes (optional)
+.\"
+.\"		* See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+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)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR read (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR write (2)
+.\".IP	FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+Notes:
+.I <sched.h>
+defines
+.I time_t
+since POSIX.1-2008.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR ctime (3),
+.BR difftime (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <sched.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR timeradd (3)
-- 
2.28.0

Re: [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@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/

Re: [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@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

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

[Thorsten Glaser]

Alejandro Colomar dixit:

> POSIX does more or less the same:
> It has a ¿main? header where the type is defined

It does?

When I look at one of the headers, for example…
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html
… I see a number of types being defined, but the types don’t have
their own pages nor is described which is the “main” header (the same
goes for constants, e.g. NULL is defined by several headers).

Or is wording like…

     The <stdlib.h> header shall define NULL as described in [10]<stddef.h>.

… where you get the notion of a “main header” from?
If so, where in the standard is this expectation documented?

Curious,
//mirabilos
-- 
“It is inappropriate to require that a time represented as
 seconds since the Epoch precisely represent the number of
 seconds between the referenced time and the Epoch.”
	-- IEEE Std 1003.1b-1993 (POSIX) Section B.2.2.2

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

[Alejandro Colomar]

Hi Thorsten,

 >> POSIX does more or less the same:
 >> It has a ¿main? header where the type is defined
 >
 > It does?

It doesn't explicitly say so (AFACS; I didn't read the standard so deep).

But it hints so.

 > When I look at one of the headers, for example…
 > https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html
 > … I see a number of types being defined, but the types don’t have
 > their own pages nor is described which is the “main” header (the same
 > goes for constants, e.g. NULL is defined by several headers).
 >
 > Or is wording like…
 >
 >      The <stdlib.h> header shall define NULL as described in 
[10]<stddef.h>.

Yes, the POSIX standard defines types (and in general everything) in
one header.  And then other headers refer the definition to that header,
with that wording you extracted.

The C standard does more or less the same thing:

Extracts from C18:

§ 6.5.3.3 (5)
"The value of the result of both operators is implementation-defined,
and its type (an unsignedinteger type) is size_t, defined
in <stddef.h> (and other headers)."

§ 7.19
"  Common definitions <stddef.h>
The header <stddef.h> defines the following macros and declares the
following types. Some are also defined in other headers, as noted in
their respective subclauses.

The types are
[...]
size_t
which is the unsigned integer type of the result of the sizeof operator;
[...]
"

§ 7.21
"  Input/output <stdio.h>
Introduction
The header <stdio.h> defines several macros, and declares three types
and many functions for performing input and output.
The types declared are size_t (described in 7.19);
[...]
"


 > … where you get the notion of a “main header” from?
 > If so, where in the standard is this expectation documented?

It's not that the standards document it, but in practice it is so.

The main point of differentiating those headers from the rest would be:

- It is likely that it's the lightest header you need to get that type
   (usually most types are in <stddef.h> or <sys/types.h> or <sys/time.h>
   or <stdint.h>, which are very light headers, and the rest of the
   headers just need the types the many function prototypes, which
   you don't need).

- If one wants to find the actual documentation for a type, it's easier
   if you know which header you should look at, although I have to admit
   that if you see any of the other headers, it clearly redirects you,
   so not very important.

- If you just include any of the headers in the list for just getting
   one type (e.g., you included <monetary.h> to get 'ssize_t'),
   a reader of the code might spend a few minutes wondering why the hell
   is that header included.  It's ok if you need monetary for something
   else, and you also happen to need 'ssize_t' and omit <sys/types.h>
   because you happen to have the definition already, but including that
   header just for 'ssize_t' would be a shooting offense, IMO.


Thanks,

Alex

Re: [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 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/

[PATCH v7 0/8] Document system data types

[Alejandro Colomar]

Hi Michael,

I'm proud enough of the result to commit it now :-}.

Changelog since v6:

- ffix
- wsfix
- wfix
- Change ordering of headers (no actual change)
- Curate See also (sigval)
- Add NOTES section (about structures)

On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
> That sounds okay to me. I presume you plan to uncomment the
> lines above that mention sigevent and siginfo_t, right?

Right.

Cheers,

Alex


Alejandro Colomar (8):
  system_data_types.7: Document types: sigval, ssize_t, suseconds_t,
    time_t, timer_t, timespec, timeval
  sigval.3: Add link page
  ssize_t.3: Add link page
  suseconds_t.3: Add link page
  time_t.3: Add link page
  timer_t.3: Add link page
  timespec.3: Add link page
  timeval.3: Add link page

 man3/sigval.3            |   1 +
 man3/ssize_t.3           |   1 +
 man3/suseconds_t.3       |   1 +
 man3/time_t.3            |   1 +
 man3/timer_t.3           |   1 +
 man3/timespec.3          |   1 +
 man3/timeval.3           |   1 +
 man7/system_data_types.7 | 280 +++++++++++++++++++++++++++++++++++++++
 8 files changed, 287 insertions(+)
 create mode 100644 man3/sigval.3
 create mode 100644 man3/ssize_t.3
 create mode 100644 man3/suseconds_t.3
 create mode 100644 man3/time_t.3
 create mode 100644 man3/timer_t.3
 create mode 100644 man3/timespec.3
 create mode 100644 man3/timeval.3
 create mode 100644 man7/system_data_types.7

-- 
2.28.0

Re: [PATCH v7 0/8] Document system data types

[Michael Kerrisk (man-pages)]

Hello Alex

On 9/17/20 12:42 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> I'm proud enough of the result to commit it now :-}.

And fair enough! It's been a great piece of work!

> Changelog since v6:
> 
> - ffix
> - wsfix
> - wfix
> - Change ordering of headers (no actual change)
> - Curate See also (sigval)
> - Add NOTES section (about structures)

I've merged all of the patches. However, I then squashed 
all the patches adding the links into a single commit.

> On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
>> That sounds okay to me. I presume you plan to uncomment the
>> lines above that mention sigevent and siginfo_t, right?
> 
> Right.

Did you actually do that.? It seems not. Wanna send me 
a patch?

Thanks,

Michael




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

Re: [PATCH v7 0/8] Document system data types

[Alejandro Colomar]

On 2020-09-17 23:05, Michael Kerrisk (man-pages) wrote:
> Hello Alex
> 
> On 9/17/20 12:42 PM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> I'm proud enough of the result to commit it now :-}.
> 
> And fair enough! It's been a great piece of work!

Thank you, Michael!

> 
>> Changelog since v6:
>>
>> - ffix
>> - wsfix
>> - wfix
>> - Change ordering of headers (no actual change)
>> - Curate See also (sigval)
>> - Add NOTES section (about structures)
> 
> I've merged all of the patches. However, I then squashed
> all the patches adding the links into a single commit.

That's fine.

> 
>> On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
>>> That sounds okay to me. I presume you plan to uncomment the
>>> lines above that mention sigevent and siginfo_t, right?
>>
>> Right.
> 
> Did you actually do that.? It seems not. Wanna send me
> a patch?

Oh, I meant that I plan to uncomment those lines when we document those 
other types (to not have broken references).

> 
> Thanks,
> 
> Michael
> 
> 

Cheers,

Alex.

[PATCH v7 1/8] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 280 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 280 insertions(+)
 create mode 100644 man7/system_data_types.7

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8072f739b
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,280 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein.  The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\"	* Add types
+.\"	* Curate "See also"
+.\" Layout:
+.\"	A list of type names (the struct/union keyword will be omitted).
+.\"	Each entry will have the following parts:
+.\"		* Include
+.\"			The headers will be in the following order:
+.\"			1) The main header that shall define the type
+.\"			   according to the C Standard,
+.\"			   and
+.\"			   the main header that shall define the type
+.\"			   according to POSIX,
+.\"			   in alphabetical order.
+.\"			;
+.\"			2) All other headers that shall define the type
+.\"			   as described in the previous header(s)
+.\"			   according to the C Standard or POSIX,
+.\"			   in alphabetical order.
+.\"			*) All headers that define the type
+.\"			   *if* the type is not defined by C nor POSIX,
+.\"			   in alphabetical order.
+.\"
+.\"		* Definition (no "Definition" header)
+.\"			Only struct/union types will have definition;
+.\"			typedefs will remain opaque.
+.\"
+.\"		* Description (no "Description" header)
+.\"			A few lines describing the type.
+.\"
+.\"		* Conforming to
+.\"			Format: CXY and later; POSIX.1-XXXX and later.
+.\"			Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\"		* Notes (optional)
+.\"
+.\"		* See also
+.TP
+.I sigval
+.IP
+Include:
+.IR <signal.h> .
+.IP
+.EX
+union sigval {
+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.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
+Include:
+.IR <sys/types.h> ;
+or
+.I <aio.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.IR <unistd.h> .
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR read (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR write (2)
+.\".IP	FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.IR <sys/types.h> ;
+or
+.I <sys/select.h>
+or
+.IR <sys/time.h> .
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.IR <time.h> ;
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.IR <utime.h> .
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+Notes:
+.I <sched.h>
+defines
+.I time_t
+since POSIX.1-2008.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR ctime (3),
+.BR difftime (3)
+.TP
+.I timer_t
+.IP
+Include:
+.IR <sys/types.h> ;
+or
+.IR <time.h> .
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.IR <time.h> ;
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <sched.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.IR <sys/stat.h> .
+.IP
+.EX
+struct timespec {
+    time_t  tv_sec;  /* Seconds */
+    long    tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.IR <sys/time.h> ;
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.IR <utmpx.h> .
+.IP
+.EX
+struct timeval {
+    time_t      tv_sec;  /* Seconds */
+    suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR timeradd (3)
+.SH NOTES
+The structures described in this manual page shall contain,
+at least, the members shown in their definition, in no particular order.
-- 
2.28.0

[PATCH v7 2/8] sigval.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/sigval.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/sigval.3

diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 3/8] ssize_t.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/ssize_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/ssize_t.3

diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/ssize_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 4/8] suseconds_t.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/suseconds_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/suseconds_t.3

diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 5/8] time_t.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/time_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/time_t.3

diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 6/8] timer_t.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/timer_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/timer_t.3

diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 7/8] timespec.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/timespec.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/timespec.3

diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

[PATCH v7 8/8] timeval.3: Add link page

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/timeval.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/timeval.3

diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0