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

Wed Sep 16 10:52:29 UTC 2020

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

Hi Michael,

Changelog since v4:

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


On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
> Okay. Time to nit pick:-). Do not be too dispirited,
> I think we started with some of the most difficult types...

I was waiting for it :-).

> I soppose what I meant is that POSIX defers to the C standard
> in the cases where they overlap, and I'd expect that the set
> of headers specified in the C standard and in POSIX might be the
> same, but where they're not, I suspect the list of POSIX headers
> would always be a superset of the C headers. So, just make a
> single list of those headers, followed by 3 and 4 (merged)

See updated comment in the page.

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

