New pages for types: structs and typedfefs

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.

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)

Hi Michael,

Quoted 4 lines · Michael Kerrisk (man-pages)

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

Quoted 12 lines

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/

Quoted 4 lines

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.

Quoted 6 lines

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

Quoted 9 lines

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.

Quoted 4 lines

         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?

Quoted 7 lines

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:

Quoted 1 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)

Quoted 2 lines

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

Yes.

Hi Alex,

On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar

Quoted 8 lines

Hi Michael,

Quoted 4 lines · Michael Kerrisk (man-pages)

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

Quoted 6 lines

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

Quoted 16 lines

Quoted 4 lines

I propose the desired information for each type would be

Quoted 9 lines

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

Quoted 3 lines

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

Quoted 7 lines

Quoted 5 lines

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.

Quoted 23 lines

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

Quoted 6 lines

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

Quoted 9 lines

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.

Quoted 6 lines

Quoted 4 lines

         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.

Quoted 1 line

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.

Quoted 12 lines

Quoted 9 lines

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:

Quoted 3 lines

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

Quoted 5 lines

Quoted 3 lines

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

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

Hi Alex,

On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar

<[email protected]> wrote:

Quoted 5 lines

Quoted 1 line

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

Quoted 10 lines

Quoted 5 lines

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?

Quoted 5 lines

Quoted 4 lines

Quoted 2 lines

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

Yes.

Quoted 3 lines

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?

Hi Alex,

Quoted 7 lines · Alejandro Colomar

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

Hi Alex,

On Sat, 12 Sep 2020 at 10:59, Alejandro Colomar

<[email protected]> 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.

[...]

Quoted 6 lines

Quoted 6 lines

Quoted 5 lines

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)

Quoted 1 line

[...]

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.

Quoted 1 line

[...]

Throw in 'struct timeval' too?

Quoted 3 lines

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.

Quoted 1 line

From ffd8ea312527935cd86cc7ed1133a08d4e642b06 Mon Sep 17 00:00:00 2001

From: Alejandro Colomar <[email protected]>
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?

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

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)

Quoted 6 lines

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?

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

Michael Kerrisk (man-pages) dixit:

Quoted 1 line

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.

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

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.

Quoted 3 lines

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/

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

Quoted 3 lines

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.

* Michael Kerrisk <[email protected]>, 2020-09-13, 14:01:

Quoted 5 lines

Quoted 3 lines

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

Quoted 5 lines · Alejandro Colomar

Quoted 4 lines · Michael Kerrisk (man-pages)

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.

Quoted 5 lines

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

Quoted 11 lines

Quoted 8 lines

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:

Quoted 3 lines

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

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

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.

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

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>

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.

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 <[email protected]>

---

Hi Michael,

Quoted 5 lines · Michael Kerrisk (man-pages)

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:

Quoted 1 line

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

OK.

Quoted 2 lines

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.

Quoted 1 line

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

:-)

Quoted 4 lines

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>

Quoted 2 lines

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 +

Quoted 5 lines

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

man3/sigval.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/suseconds_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/time_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timer_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timespec.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timeval.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man7/system_data_types.7 new file +73 -0

new file mode 100644
index 000000000..8b89a46f3
@@ -0,0 +1,227 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <[email protected]>
+.\"
+.\" %%%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),

man7/system_data_types.7 new file +18 -0

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

man7/system_data_types.7 new file +31 -0

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

man7/system_data_types.7 new file +12 -0

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

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

Quoted 8 lines

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")

Quoted 5 lines

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

man7/system_data_types.7 line 92

Quoted 10 lines

+.IP
+.EX

man7/system_data_types.7 new file +7 -0

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

man7/system_data_types.7 line 96

Quoted 5 lines

+.IP

man7/system_data_types.7 new file +3 -0

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

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

man7/system_data_types.7 line 124

Quoted 12 lines

+.BR adjtimex (2),
[...]
+.BR socket (7)
+.TP
+.I suseconds_t
+.IP

man7/system_data_types.7 new file +5 -0

+Include:
+.I <sys/types.h>
+.IP
+Used for time in microseconds.
+It shall be a signed integer type

s/It/According to POSIX, it/

man7/system_data_types.7 line 136

Quoted 12 lines

man7/system_data_types.7 new file +11 -0

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

man7/system_data_types.7 line 146

Quoted 11 lines

+.TP
+.I time_t
+.IP

man7/system_data_types.7 new file +7 -0

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

man7/system_data_types.7 line 150

Quoted 5 lines

+.IP

man7/system_data_types.7 new file +3 -0

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

Many items in the following list should go...

Quoted 8 lines

+.BR clock_getres (2),
[...]
+.BR timeradd (3)
+.TP
+.I timer_t
+.IP
+Include:

Add "<time.h> or"

man7/system_data_types.7 line 195

Quoted 5 lines

+.I <sys/types.h>
+.IP

man7/system_data_types.7 new file +2 -0

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

Quoted 17 lines

+.IP

man7/system_data_types.7 new file +15 -0

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

man7/system_data_types.7 line 217

Quoted 6 lines

man7/system_data_types.7 new file +6 -0

+    int     sigval_int; /* Integer value */
+    void   *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with notification.

s/notification/a signal/

man7/system_data_types.7 line 227

Quoted 11 lines

+.IP

man7/system_data_types.7 new file +9 -0

+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

Hi Michael,

Quoted 3 lines · Michael Kerrisk (man-pages)

Small misunderstanding here, bu the way. I meant: after merging the lists, sort by identifier name. Thus:

Quoted 6 lines

union sigval
suseconds_t
time_t
timer_t
struct timespec
struct timeval

OK.

Quoted 11 lines

man7/system_data_types.7 line 92

Quoted 9 lines

+.IP
+.EX

man7/system_data_types.7 new file +7 -0

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

???

Quoted 5 lines

Quoted 5 lines

+.BR adjtimex (2),
[...]
+.BR socket (7)
+.TP
+.I suseconds_t

Quoted 8 lines

man7/system_data_types.7 line 124

Quoted 6 lines

+.IP

man7/system_data_types.7 new file +5 -0

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

Quoted 5 lines

Quoted 5 lines

man7/system_data_types.7 new file +5 -0

+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),

Quoted 8 lines

Quoted 6 lines

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

Quoted 7 lines

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

Quoted 9 lines

Quoted 7 lines

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

Quoted 6 lines

man7/system_data_types.7 line 195

Quoted 4 lines

+.I <sys/types.h>
+.IP

man7/system_data_types.7 new file +2 -0

+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

Hi Alex,

Quoted 1 line · Alejandro Colomar

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?

Quoted 2 lines

Quoted 1 line

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.

Quoted 8 lines

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

Good progress so far. Thanks, Alex!

Cheers,

Michael

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 <[email protected]>

---

Quoted 11 lines

Quoted 8 lines

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.

Quoted 5 lines

Good progress so far. Thanks, Alex!

Cheers,

Michael

Thank you too, Michael!

 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

man3/sigval.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/ssize_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/suseconds_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/time_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timer_t.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timespec.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man3/timeval.3 new file +1 -0

new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7

man7/system_data_types.7 new file +41 -0

new file mode 100644
index 000000000..dd93c6746
@@ -0,0 +1,349 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <[email protected]>
+.\"
+.\" %%%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,

man7/system_data_types.7 new file +83 -0

+.\"
+.\"		* 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>

man7/system_data_types.7 new file +20 -0

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

man7/system_data_types.7 new file +39 -0

+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

man7/system_data_types.7 new file +84 -0

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

man7/system_data_types.7 new file +11 -0

+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),

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.

Review

Quoted 3 lines

(quoted diff) +3 -0

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

Above two lines should also be commented out.

Quoted 2 lines

+See also the
+.B timeval

s/.B/.I/

Signed-off-by Alejandro Colomar <[email protected]>

---

Hi Michael,

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

Changelog since Draft v3:

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

Quoted 4 lines · Michael Kerrisk (man-pages)

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

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

man7/system_data_types.7 new file +32 -0

new file mode 100644
index 000000000..9011ce74e
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <[email protected]>
+.\"
+.\" %%%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"

man7/system_data_types.7 new file +33 -0

+.\"			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 */
+};

man7/system_data_types.7 new file +7 -0

+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or

man7/system_data_types.7 new file +11 -0

+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

man7/system_data_types.7 new file +21 -0

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

man7/system_data_types.7 new file +32 -0

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

Quoted 13 lines

+.\" %%%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

Quoted 8 lines

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

Michael Kerrisk (man-pages) dixit:

Quoted 13 lines

Quoted 13 lines

+.\" %%%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

Quoted 8 lines

Quoted 8 lines

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

[CC += AEB]

Quoted 24 lines

Michael Kerrisk (man-pages) dixit:

Quoted 21 lines

Quoted 21 lines

+.\" %%%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

Quoted 1 line

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),

Quoted 26 lines · Michael Kerrisk (man-pages)

[CC += AEB]

Quoted 24 lines

Michael Kerrisk (man-pages) dixit:

Quoted 21 lines

Quoted 21 lines

+.\" %%%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

Quoted 7 lines

Quoted 1 line

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.

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

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)

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

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

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

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

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

Signed-off-by Alejandro Colomar <[email protected]>

---

Hi Michael,

Changelog since v4:

- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers

Quoted 2 lines · Michael Kerrisk (man-pages)

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

Quoted 6 lines

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.

Quoted 2 lines

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

Quoted 1 line

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.

Quoted 2 lines

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

Quoted 1 line

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.

Quoted 1 line

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

Hello Alex,

Quoted 26 lines · Alejandro Colomar

Signed-off-by Alejandro Colomar <[email protected]>

---

Hi Michael,

Changelog since v4:

- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers

Quoted 2 lines · Michael Kerrisk (man-pages)

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

Quoted 6 lines

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)

Quoted 1 line

See updated comment in the page.

It looks good to me.

Quoted 13 lines

Quoted 3 lines

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

Quoted 1 line

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:

Quoted 3 lines

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.

Quoted 5 lines

Quoted 3 lines

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

Quoted 5 lines

Quoted 1 line

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.

Quoted 1 line

Quoted 1 line

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

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

Quoted 2 lines

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?

Hello Michael

Quoted 29 lines · Michael Kerrisk (man-pages)

Hello Alex,

Quoted 26 lines · Alejandro Colomar

Signed-off-by Alejandro Colomar <[email protected]>

---

Hi Michael,

Changelog since v4:

- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers

Quoted 2 lines · Michael Kerrisk (man-pages)

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

Quoted 6 lines

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)

Quoted 3 lines

Quoted 1 line

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

Quoted 12 lines

Quoted 4 lines

Quoted 2 lines

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

Quoted 5 lines

Quoted 1 line

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.

Quoted 6 lines

Quoted 1 line

Quoted 1 line

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

man7/system_data_types.7 +1 -1

index 8fc827332..ffdcc9793 100644
@@ -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.

man7/system_data_types.7 +6 -2

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

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

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)

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

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

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

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

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

Signed-off-by Alejandro Colomar <[email protected]>

---

Hi Michael,

Changelog since v4:

- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers

Quoted 2 lines · Michael Kerrisk (man-pages)

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

Quoted 6 lines

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.

Quoted 2 lines

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

Quoted 1 line

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.

Quoted 2 lines

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

Quoted 1 line

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.

Quoted 1 line

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

man7/system_data_types.7 new file +304 -0

new file mode 100644
index 000000000..1616d858c
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <[email protected]>
+.\"
+.\" %%%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)

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

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)

Quoted 2 lines

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

Right.

Hello Alex

Quoted 3 lines · Alejandro Colomar

Hi Michael,

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

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

Quoted 9 lines

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.

Quoted 6 lines · Michael Kerrisk (man-pages)

Quoted 2 lines

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