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

Tue Sep 15 21:30:38 UTC 2020

Hi Alex,

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

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

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

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

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

[...]

>  man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 304 insertions(+)
>  create mode 100644 man7/system_data_types.7
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..9011ce74e
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,304 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3 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.

See my comments above.

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

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

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

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

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

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

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

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

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

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

> +.IP
> +See also:

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

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

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

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

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

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

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

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

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

Remove the above two lines.

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

<sched.h> only defines time_t since POSIX.1-2008, as far as I can
tell! I'm not sure how/if we want to represent that detail.

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

Drop lines marked XX

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

(time_t turns up only as part of timespec)

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

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

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

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

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

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

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

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

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

Let's limit things to a representative sample:

XX > +.BR futimesat (2),

futimesat() is obsolete and nonstandard.

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

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

> +.BR timeradd (3)

Thanks,

Michael

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