[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 <colomar.6.4.3@gmail.com>]

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