* [RFC v2] system_data_types.7: Draft v2
2020-09-14 10:22 ` Alejandro Colomar
@ 2020-09-14 14:03 ` Alejandro Colomar
2020-09-14 15:00 ` Michael Kerrisk (man-pages)
2020-09-15 0:47 ` [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
` (12 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-14 14:03 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, fweimer, libbsd, jwilk, Alejandro Colomar
Changelog since Draft v1:
- Fix includes for timer_t: remove <time.h>
- tfix
- Clarify POSIX requirements
- Remove subsections, and instead use full names for structs/unions
- Includes: ffix
- Conforming to: ffix
- struct timespec: update "see also"
- Add suseconds_t
- Remove old comments
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
On 2020-09-14 12:37, Michael Kerrisk (man-pages) wrote:
> Good. I think that we can get away with just mentioning one each of
> POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
> far enough back in time that we don't need to clutter the page with
> it. Something like:
>
> Conforming to: C99 and later; POSIX.1-2001 and later.
OK.
> Instead, I looked inside the pages that you listed to see which APIs
> seemed "relevant".
Work in progress. I'll do it for the other types soon.
> You better include suseconds_t in the next draft:-).
:-)
> Having seen how it looks with the header files, I'm going to suggest a
> differnt approach. Let's put them on a separate line, something like:
>
> Obtained by including: <abc.h> or <xyz.h>
I simplified it to just:
Include: <asd.h> or <qwe.h>
> It's an open question whether the links should be in section 3 or
> section 7. Do you have any thoughts on what's better?
All sources I could find talk about section 3 as a section containing
all C "library functions".
Types don't exactly fit in that description, but it could be stretched
a bit to contain all C "library definitions".
Also, libbsd already chose section 3, and I don't see a strong reason
against it, so maybe we could follow that pattern.
I would still have system_data_types.7 in section 7, as it doesn't
match the name of any library definition.
BTW, would you also add "struct-" and "union-" link pages?:
man3/struct-timespec.3 | 1 +
man3/timespec.3 | 1 +
instead of
man3/timespec.3 | 1 +
> Don't get wrapped up in including too many more types in the
> yet, while we try to iron out the format.
>
> Also, I'd like to see the types added incrementally (one or a few
> at a time), so that it's easy to comment on each type, when needed.
Agree.
Thanks,
Alex
man3/sigval.3 | 1 +
man3/suseconds_t.3 | 1 +
man3/time_t.3 | 1 +
man3/timer_t.3 | 1 +
man3/timespec.3 | 1 +
man3/timeval.3 | 1 +
man7/system_data_types.7 | 227 +++++++++++++++++++++++++++++++++++++++
7 files changed, 233 insertions(+)
create mode 100644 man3/sigval.3
create mode 100644 man3/suseconds_t.3
create mode 100644 man3/time_t.3
create mode 100644 man3/timer_t.3
create mode 100644 man3/timespec.3
create mode 100644 man3/timeval.3
create mode 100644 man7/system_data_types.7
diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8b89a46f3
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,227 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Check specific POSIX "Conforming to" versions
+.\" * Correctly highlight function names and similar (see timer_t)
+.TP
+.BI "struct " timespec
+.IP
+Include:
+.I <time.h>
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR clock_getres (2),
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.\".BR futex (2),
+.\".BR io_getevents (2),
+.BR nanosleep (2),
+.\".BR poll (2),
+.\".BR recvmmsg (2),
+.\".BR sched_rr_get_interval (2),
+.\".BR select (2),
+.\".BR semop (2),
+.\".BR sigwaitinfo (2),
+.\".BR stat (2),
+.\".BR timerfd_create (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.\".BR timer_settime (2),
+.\".BR utimensat (2),
+.\".BR aio_suspend (3),
+.\".BR clock_getcpuclockid (3),
+.\".BR getaddrinfo_a (3),
+.\".BR mq_receive (3),
+.\".BR mq_send (3),
+.\".BR pthread_getcpuclockid (3),
+.\".BR pthread_tryjoin_np (3),
+.\".BR sem_wait (3),
+.\".BR socket (7)
+.TP
+.BI "struct " timeval
+.IP
+Include:
+.I <sys/time.h>
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR adjtimex (2),
+.BR futimesat (2),
+.BR getitimer (2),
+.BR getpriority (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR utime (2),
+.BR wait4 (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR ntp_gettime (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3),
+.BR utmp (5),
+.BR packet (7),
+.BR socket (7)
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+.IP
+Used for time in microseconds.
+It shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR getitimer (2),
+.\".BR gettimeofday (2),
+.\".BR select (2),
+.\".BR adjtime (3),
+.\".BR ntp_gettime (3),
+.BR timeval (3)
+.\".BR timeradd (3)
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+.IP
+Used for time in seconds.
+In POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR gettimeofday (2),
+.BR io_getevents (2),
+.BR keyctl (2),
+.BR msgctl (2),
+.BR msgop (2),
+.BR nanosleep (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semctl (2),
+.BR shmctl (2),
+.BR stat (2),
+.BR stime (2),
+.BR time (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR times (2),
+.BR utime (2),
+.BR utimensat (2),
+.BR adjtime (3),
+.BR ctime (3),
+.BR difftime (3),
+.BR ftime (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR newlocale (3),
+.BR ntp_gettime (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_tryjoin_np (3),
+.BR rtime (3),
+.BR sem_wait (3),
+.BR strcat (3),
+.BR strftime (3),
+.BR timegm (3),
+.BR timeradd (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+.IP
+Used for timer ID returned by timer_create().
+There are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.BI "union " sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with notification.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v2] system_data_types.7: Draft v2
2020-09-14 14:03 ` [RFC v2] system_data_types.7: Draft v2 Alejandro Colomar
@ 2020-09-14 15:00 ` Michael Kerrisk (man-pages)
2020-09-14 15:52 ` Alejandro Colomar
0 siblings, 1 reply; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-14 15:00 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, fweimer, libbsd, jwilk
Hi Alex,
On 9/14/20 4:03 PM, Alejandro Colomar wrote:
> Changelog since Draft v1:
>
> - Fix includes for timer_t: remove <time.h>
> - tfix
> - Clarify POSIX requirements
> - Remove subsections, and instead use full names for structs/unions
Small misunderstanding here, bu the way. I meant: after merging
the lists, sort by identifier name. Thus:
union sigval
suseconds_t
time_t
timer_t
struct timespec
struct timeval
> - Includes: ffix
> - Conforming to: ffix
> - struct timespec: update "see also"
> - Add suseconds_t
> - Remove old comments
>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> On 2020-09-14 12:37, Michael Kerrisk (man-pages) wrote:
>> Good. I think that we can get away with just mentioning one each of
>> POSIX.1-200x and Cxx, with the latter starting at C99. I think C89 is
>> far enough back in time that we don't need to clutter the page with
>> it. Something like:
>>
>> Conforming to: C99 and later; POSIX.1-2001 and later.
>
> OK.
>
>> Instead, I looked inside the pages that you listed to see which APIs
>> seemed "relevant".
>
> Work in progress. I'll do it for the other types soon.
Okay. I'll make a few notes below.
>> You better include suseconds_t in the next draft:-).
>
> :-)
>
>> Having seen how it looks with the header files, I'm going to suggest a
>> differnt approach. Let's put them on a separate line, something like:
>>
>> Obtained by including: <abc.h> or <xyz.h>
>
> I simplified it to just:
>
> Include: <asd.h> or <qwe.h>
Yes, better.
>> It's an open question whether the links should be in section 3 or
>> section 7. Do you have any thoughts on what's better?
>
> All sources I could find talk about section 3 as a section containing
> all C "library functions".
> Types don't exactly fit in that description, but it could be stretched
> a bit to contain all C "library definitions".
>
> Also, libbsd already chose section 3, and I don't see a strong reason
> against it, so maybe we could follow that pattern.
Thanks. I forgot that libbsd detail. Yes, let's go with Section 3.
> I would still have system_data_types.7 in section 7, as it doesn't
> match the name of any library definition.
Yes.
> BTW, would you also add "struct-" and "union-" link pages?:
>
> man3/struct-timespec.3 | 1 +
> man3/timespec.3 | 1 +
>
> instead of
>
> man3/timespec.3 | 1 +
I think just one link: the name of the type (without any
"struct" or "union")
>> Don't get wrapped up in including too many more types in the
>> yet, while we try to iron out the format.
>>
>> Also, I'd like to see the types added incrementally (one or a few
>> at a time), so that it's easy to comment on each type, when needed.
>
> Agree.
>
> Thanks,
>
> Alex
A few further comments below.
>
> man3/sigval.3 | 1 +
> man3/suseconds_t.3 | 1 +
> man3/time_t.3 | 1 +
> man3/timer_t.3 | 1 +
> man3/timespec.3 | 1 +
> man3/timeval.3 | 1 +
> man7/system_data_types.7 | 227 +++++++++++++++++++++++++++++++++++++++
> 7 files changed, 233 insertions(+)
> create mode 100644 man3/sigval.3
> create mode 100644 man3/suseconds_t.3
> create mode 100644 man3/time_t.3
> create mode 100644 man3/timer_t.3
> create mode 100644 man3/timespec.3
> create mode 100644 man3/timeval.3
> create mode 100644 man7/system_data_types.7
>
> diff --git a/man3/sigval.3 b/man3/sigval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/suseconds_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/time_t.3 b/man3/time_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/time_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timer_t.3 b/man3/timer_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timer_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timespec.3 b/man3/timespec.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timespec.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timeval.3 b/man3/timeval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timeval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..8b89a46f3
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,227 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein. The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\" * Add types
> +.\" * Check specific POSIX "Conforming to" versions
> +.\" * Correctly highlight function names and similar (see timer_t)
> +.TP
> +.BI "struct " timespec
> +.IP
> +Include:
> +.I <time.h>
> +.IP
> +.EX
> +struct timespec {
> + time_t tv_sec; /* Seconds */
> + long tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.\".BR clock_getres (2),
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.\".BR futex (2),
> +.\".BR io_getevents (2),
> +.BR nanosleep (2),
> +.\".BR poll (2),
> +.\".BR recvmmsg (2),
> +.\".BR sched_rr_get_interval (2),
> +.\".BR select (2),
> +.\".BR semop (2),
> +.\".BR sigwaitinfo (2),
> +.\".BR stat (2),
> +.\".BR timerfd_create (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.\".BR timer_settime (2),
> +.\".BR utimensat (2),
> +.\".BR aio_suspend (3),
> +.\".BR clock_getcpuclockid (3),
> +.\".BR getaddrinfo_a (3),
> +.\".BR mq_receive (3),
> +.\".BR mq_send (3),
> +.\".BR pthread_getcpuclockid (3),
> +.\".BR pthread_tryjoin_np (3),
> +.\".BR sem_wait (3),
> +.\".BR socket (7)
> +.TP
> +.BI "struct " timeval
> +.IP
> +Include:
> +.I <sys/time.h>
or <sys/select.h>
(Really, a PDF copy of the standard is gpoing to help...)
> +.IP
> +.EX
> +struct timeval {
> + time_t tv_sec; /* Seconds */
> + suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
According to POSIX, this shall be a signed integer type.
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
I think there are several in the following list that should be removed...
> +.BR adjtimex (2),
> +.BR futimesat (2),
> +.BR getitimer (2),
> +.BR getpriority (2),
> +.BR getrusage (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR syscall (2),
> +.BR syscalls (2),
> +.BR utime (2),
> +.BR wait4 (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR ntp_gettime (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3),
> +.BR utmp (5),
> +.BR packet (7),
> +.BR socket (7)
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +.IP
> +Used for time in microseconds.
> +It shall be a signed integer type
s/It/According to POSIX, it/
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.\".BR getitimer (2),
> +.\".BR gettimeofday (2),
> +.\".BR select (2),
> +.\".BR adjtime (3),
> +.\".BR ntp_gettime (3),
> +.BR timeval (3)
> +.\".BR timeradd (3)
The above is a little too circular for my taste :-).
How about just saying:
[[
This type is used for one of the
fields of the timeval structure (see below).
]]
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +.IP
> +Used for time in seconds.
> +In POSIX, it shall be an integer type.
s/In/According to/
> +.IP
> +Conforming to: C99 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:
Many items in the following list should go...
> +.BR clock_getres (2),
> +.BR clock_nanosleep (2),
> +.BR getitimer (2),
> +.BR gettimeofday (2),
> +.BR io_getevents (2),
> +.BR keyctl (2),
> +.BR msgctl (2),
> +.BR msgop (2),
> +.BR nanosleep (2),
> +.BR sched_rr_get_interval (2),
> +.BR select (2),
> +.BR semctl (2),
> +.BR shmctl (2),
> +.BR stat (2),
> +.BR stime (2),
> +.BR time (2),
> +.BR timerfd_create (2),
> +.BR timer_settime (2),
> +.BR times (2),
> +.BR utime (2),
> +.BR utimensat (2),
> +.BR adjtime (3),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR ftime (3),
> +.BR mq_receive (3),
> +.BR mq_send (3),
> +.BR newlocale (3),
> +.BR ntp_gettime (3),
> +.BR pthread_cleanup_push (3),
> +.BR pthread_tryjoin_np (3),
> +.BR rtime (3),
> +.BR sem_wait (3),
> +.BR strcat (3),
> +.BR strftime (3),
> +.BR timegm (3),
> +.BR timeradd (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:
Add "<time.h> or"
> +.I <sys/types.h>
> +.IP
> +Used for timer ID returned by timer_create().
> +There are no defined comparison or assignment operators for this type.
Where is that mentioned in the standard, by the way?
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.BI "union " sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> + int sigval_int; /* Integer value */
> + void *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with notification.
s/notification/a signal/
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v2] system_data_types.7: Draft v2
2020-09-14 15:00 ` Michael Kerrisk (man-pages)
@ 2020-09-14 15:52 ` Alejandro Colomar
2020-09-14 19:33 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-14 15:52 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: linux-man, fweimer, libbsd, jwilk
Hi Michael,
On 9/14/20 5:00 PM, Michael Kerrisk (man-pages) wrote:
> Small misunderstanding here, bu the way. I meant: after merging
> the lists, sort by identifier name. Thus:
>
> union sigval
> suseconds_t
> time_t
> timer_t
> struct timespec
> struct timeval
OK.
>> BTW, would you also add "struct-" and "union-" link pages?:
>>
>> man3/struct-timespec.3 | 1 +
>> man3/timespec.3 | 1 +
>>
>> instead of
>>
>> man3/timespec.3 | 1 +
>
> I think just one link: the name of the type (without any
> "struct" or "union")
OK.
>> +.TP
>> +.BI "struct " timeval
>> +.IP
>> +Include:
>> +.I <sys/time.h>
>
> or <sys/select.h>
True.
> (Really, a PDF copy of the standard is gpoing to help...)
I already have a login, and it works, but when I try to download the PDF
(just after accepting terms and conditions in downloads), another login
prompt appears and I can't log in that one. I'll email them.
But for now I can live with the HTML version.
>
>> +.IP
>> +.EX
>> +struct timeval {
>> + time_t tv_sec; /* Seconds */
>> + suseconds_t tv_usec; /* Microseconds */
>> +};
>> +.EE
>> +.IP
>> +Describes times in seconds and microseconds.
>
> According to POSIX, this shall be a signed integer type.
???
>
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>
> I think there are several in the following list that should be removed...
Probably. I'll have a look at them later.
>
>> +.BR adjtimex (2),
>> [...]
>> +.BR socket (7)
>> +.TP
>> +.I suseconds_t
>> +.IP
>> +Include:
>> +.I <sys/types.h>
>> +.IP
>> +Used for time in microseconds.
>> +It shall be a signed integer type
>
> s/It/According to POSIX, it/
As this type is POSIX-only, I thought it was redundant. Don't you?
>
>> +capable of storing values at least in the range [-1, 1000000].
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.>> +.IP
>> +See also:
>> +.\".BR getitimer (2),
>> +.\".BR gettimeofday (2),
>> +.\".BR select (2),
>> +.\".BR adjtime (3),
>> +.\".BR ntp_gettime (3),
>> +.BR timeval (3)
>> +.\".BR timeradd (3)
>
> The above is a little too circular for my taste :-).
Maybe... I'll leave it commented, just in case some day the list is
splitted.
>
> How about just saying:
>
> [[
> This type is used for one of the
> fields of the timeval structure (see below).
> ]]
That's too long for my taste :)
How about?:
[[
See the timeval structure in this page.
]]
>
>> +.TP
>> +.I time_t
>> +.IP
>> +Include:
>> +.I <time.h>
>> +or
>> +.I <sys/types.h>
>> +.IP
>> +Used for time in seconds.
>> +In POSIX, it shall be an integer type.
>
> s/In/According to/
OK.
>
>> +.IP
>> +Conforming to: C99 and later; POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>
> Many items in the following list should go...
Yes
>
>> +.BR clock_getres (2),
>> [...]
>> +.BR timeradd (3)
>> +.TP
>> +.I timer_t
>> +.IP
>> +Include:
>
> Add "<time.h> or"
POSIX says:
The <time.h> header shall define the clockid_t and timer_t types as
described in <sys/types.h>.
That pattern is used by POSIX (AFAIK; I only guessed it by reading many
of those) when the type is defined by inclusion of another header
(<time.h> includes <sys/types.h> I guess).
If I added every header that has a line like that, the lists of headers
would be much bigger for most of the types. It could be good, but I
don't know if we should do it. Maybe we should limit to the headers
that are required by CXX and the ones where the POSIX docs actually
document the type (this header doesn't define it, and instead it defers
to <sys//types.h> for example).
Your thoughts?
>
>> +.I <sys/types.h>
>> +.IP
>> +Used for timer ID returned by timer_create().
>> +There are no defined comparison or assignment operators for this type.
>
> Where is that mentioned in the standard, by the way?
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html
DESCRIPTION:
[...]
There are no defined comparison or assignment operators for the
following types:
[...]
timer_t
>
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR timer_create (2),
>> +.BR timer_delete (2),
>> +.BR timer_getoverrun (2),
>> +.BR timer_settime (2)
>> +.TP
>> +.BI "union " sigval
>> +.IP
>> +Include:
>> +.I <signal.h>
>> +.IP
>> +.EX
>> +union sigval {
>> + int sigval_int; /* Integer value */
>> + void *sigval_ptr; /* Pointer value */
>> +};
>> +.EE
>> +.IP
>> +Data passed with notification.
>
> s/notification/a signal/
OK.
>
>> +.IP
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
>> +.BR rt_sigqueueinfo (2),
>> +.BR sigaction (2),
>> +.BR mq_notify (3),
>> +.BR pthread_sigqueue (3),
>> +.BR sigqueue (3),
>> +.BR sigevent (7)
>
> Thanks,
>
> Michael
>
>
Thanks,
Alex
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v2] system_data_types.7: Draft v2
2020-09-14 15:52 ` Alejandro Colomar
@ 2020-09-14 19:33 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-14 19:33 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, fweimer, libbsd, jwilk
Hi Alex,
On 9/14/20 5:52 PM, Alejandro Colomar wrote:
> Hi Michael,
>
> On 9/14/20 5:00 PM, Michael Kerrisk (man-pages) wrote:
>> Small misunderstanding here, bu the way. I meant: after merging
>> the lists, sort by identifier name. Thus:
>>
>> union sigval
>> suseconds_t
>> time_t
>> timer_t
>> struct timespec
>> struct timeval
>
> OK.
As I think about more, maybe the list of type keywords could even
omit 'struct' and 'union', since the struct/union definition will be shown
in the following text. Your thoughts?
[...]
>>> +.IP
>>> +.EX
>>> +struct timeval {
>>> + time_t tv_sec; /* Seconds */
>>> + suseconds_t tv_usec; /* Microseconds */
>>> +};
>>> +.EE
>>> +.IP
>>> +Describes times in seconds and microseconds.
>>
>> According to POSIX, this shall be a signed integer type.
>
> ???
Ooops -- I think I misplaced that sentence. It related to suseconds_t.
[...]
>>> +.BR adjtimex (2),
>>> [...]
>>> +.BR socket (7)
>>> +.TP
>>> +.I suseconds_t
>>> +.IP
>>> +Include:
>>> +.I <sys/types.h>
>>> +.IP
>>> +Used for time in microseconds.
>>> +It shall be a signed integer type
>>
>> s/It/According to POSIX, it/
>
> As this type is POSIX-only, I thought it was redundant. Don't you?
I think it's clearer to be explicit. Otherwise, the reader has to do
some deductive work.
>>> +capable of storing values at least in the range [-1, 1000000].
>>> +.IP
>>> +Conforming to: POSIX.1-xxxx and later.>> +.IP
>>> +See also:
>>> +.\".BR getitimer (2),
>>> +.\".BR gettimeofday (2),
>>> +.\".BR select (2),
>>> +.\".BR adjtime (3),
>>> +.\".BR ntp_gettime (3),
>>> +.BR timeval (3)
>>> +.\".BR timeradd (3)
>>
>> The above is a little too circular for my taste :-).
>
> Maybe... I'll leave it commented, just in case some day the list is
> splitted.
>
>>
>> How about just saying:
>>
>> [[
>> This type is used for one of the
>> fields of the timeval structure (see below).
>> ]]
>
> That's too long for my taste :)
>
> How about?:
>
> [[
> See the timeval structure in this page.
> ]]
Vale.
[...]
>>> +.BR clock_getres (2),
>>> [...]
>>> +.BR timeradd (3)
>>> +.TP
>>> +.I timer_t
>>> +.IP
>>> +Include:
>>
>> Add "<time.h> or"
>
> POSIX says:
>
> The <time.h> header shall define the clockid_t and timer_t types as
> described in <sys/types.h>.
>
> That pattern is used by POSIX (AFAIK; I only guessed it by reading many
> of those) when the type is defined by inclusion of another header
> (<time.h> includes <sys/types.h> I guess).
>
> If I added every header that has a line like that, the lists of headers
> would be much bigger for most of the types. It could be good, but I
> don't know if we should do it. Maybe we should limit to the headers
> that are required by CXX and the ones where the POSIX docs actually
> document the type (this header doesn't define it, and instead it defers
> to <sys//types.h> for example).
>
> Your thoughts?
I think the list would not be so long. Maybe two headers sometimes,
occasionally three, but I doubt more. At least right now, I think we
should do it; I may yet be shown the error of my ways :-).
>>> +.I <sys/types.h>
>>> +.IP
>>> +Used for timer ID returned by timer_create().
>>> +There are no defined comparison or assignment operators for this type.
>>
>> Where is that mentioned in the standard, by the way?
>
> https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_types.h.html
>
> DESCRIPTION:
>
> [...]
>
> There are no defined comparison or assignment operators for the
> following types:
>
> [...]
>
> timer_t
Thanks. It's good that you included that sentence in the man page.
[...]
Good progress so far. Thanks, Alex!
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* [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)
2020-09-14 10:22 ` Alejandro Colomar
2020-09-14 14:03 ` [RFC v2] system_data_types.7: Draft v2 Alejandro Colomar
@ 2020-09-15 0:47 ` Alejandro Colomar
2020-09-15 6:22 ` Michael Kerrisk (man-pages)
2020-09-15 13:33 ` [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval Alejandro Colomar
` (11 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-15 0:47 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, fweimer, libbsd, jwilk, Alejandro Colomar
Changelog since dratf v2:
- Remove struct/union keywords from list of type names (and sort)
- wfix
- ffix
- Add all the headers that define each type
- Specify the layout of the list in a comment
- Add size_t type (I had to do it :-)
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
On 9/14/20 9:33 PM, Michael Kerrisk (man-pages) wrote:
> Hi Alex,
>
> On 9/14/20 5:52 PM, Alejandro Colomar wrote:
>> Hi Michael,
> As I think about more, maybe the list of type keywords could even
> omit 'struct' and 'union', since the struct/union definition will be shown
> in the following text. Your thoughts?
Yes, it looks nicer (the eye doesn't need to move to the right at each
struct/union) so it is visually easier to find the types.
>>> s/It/According to POSIX, it/
>> As this type is POSIX-only, I thought it was redundant. Don't you?
> I think it's clearer to be explicit. Otherwise, the reader has to do
> some deductive work.
>
Agreed.
>> If I added every header that has a line like that, the lists of headers
>> would be much bigger for most of the types. It could be good, but I
>> don't know if we should do it. Maybe we should limit to the headers
>> that are required by CXX and the ones where the POSIX docs actually
>> document the type (this header doesn't define it, and instead it defers
>> to <sys//types.h> for example).
>>
>> Your thoughts?
> I think the list would not be so long. Maybe two headers sometimes,
> occasionally three, but I doubt more. At least right now, I think we
> should do it; I may yet be shown the error of my ways :-).
The list is rather long, but now I don't deel it's too much, and it has
some value. I'd keep all of them. See my comment (Layout) in the page,
and feel free to add to/modify it.
> Good progress so far. Thanks, Alex!
>
> Cheers,
>
> Michael
Thank you too, Michael!
Cheers,
Alex
man3/sigval.3 | 1 +
man3/ssize_t.3 | 1 +
man3/suseconds_t.3 | 1 +
man3/time_t.3 | 1 +
man3/timer_t.3 | 1 +
man3/timespec.3 | 1 +
man3/timeval.3 | 1 +
man7/system_data_types.7 | 349 +++++++++++++++++++++++++++++++++++++++
8 files changed, 356 insertions(+)
create mode 100644 man3/sigval.3
create mode 100644 man3/ssize_t.3
create mode 100644 man3/suseconds_t.3
create mode 100644 man3/time_t.3
create mode 100644 man3/timer_t.3
create mode 100644 man3/timespec.3
create mode 100644 man3/timeval.3
create mode 100644 man7/system_data_types.7
diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/ssize_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..dd93c6746
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,349 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Check specific POSIX "Conforming to" versions
+.\" * Correctly highlight function names and similar (see timer_t)
+.\" * Curate "See also"
+.\" Layout:
+.\" A list of type names (the struct/union keyword will be omitted).
+.\" Each entry will have the following parts:
+.\" * Include
+.\" The headers will be in the following order:
+.\" 1) The header(s) that shall define the type
+.\" according to the C standard,
+.\" in alphabetical order.
+.\" 2) The header that shall define the type
+.\" according to POSIX.
+.\" 3) All other headers that shall define the type
+.\" as described in the previous header
+.\" according to POSIX,
+.\" in alphabetical order.
+.\" 4) All other headers that define the type
+.\" that are Linux specific,
+.\" in alphabetical order.
+.\"
+.\" * Definition (no "Definition" header)
+.\" Only struct/union types will have definition;
+.\" typedefs will remain opaque.
+.\"
+.\" * Description (no "Description" header)
+.\" A few lines describing the type.
+.\"
+.\" * Conforming to
+.\" example: CXY and later; POSIX.1-XXXX and later
+.\" Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\" * Notes (optional)
+.\"
+.\" * See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR TODO (XXX),
+.BR TODO (may be too large)
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR getitimer (2),
+.\".BR gettimeofday (2),
+.\".BR select (2),
+.\".BR adjtime (3),
+.\".BR ntp_gettime (3),
+.\".BR timeval (3),
+.\".BR timeradd (3)
+.IP
+See also the
+.B timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.BR clock_getres (2),
+.BR clock_nanosleep (2),
+.BR getitimer (2),
+.BR gettimeofday (2),
+.BR io_getevents (2),
+.BR keyctl (2),
+.BR msgctl (2),
+.BR msgop (2),
+.BR nanosleep (2),
+.BR sched_rr_get_interval (2),
+.BR select (2),
+.BR semctl (2),
+.BR shmctl (2),
+.BR stat (2),
+.BR stime (2),
+.BR time (2),
+.BR timerfd_create (2),
+.BR timer_settime (2),
+.BR times (2),
+.BR utime (2),
+.BR utimensat (2),
+.BR adjtime (3),
+.BR ctime (3),
+.BR difftime (3),
+.BR ftime (3),
+.BR mq_receive (3),
+.BR mq_send (3),
+.BR newlocale (3),
+.BR ntp_gettime (3),
+.BR pthread_cleanup_push (3),
+.BR pthread_tryjoin_np (3),
+.BR rtime (3),
+.BR sem_wait (3),
+.BR strcat (3),
+.BR strftime (3),
+.BR timegm (3),
+.BR timeradd (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+There are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-xxxx and later.
+.IP
+See also:
+.\".BR clock_getres (2),
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.\".BR futex (2),
+.\".BR io_getevents (2),
+.BR nanosleep (2),
+.\".BR poll (2),
+.\".BR recvmmsg (2),
+.\".BR sched_rr_get_interval (2),
+.\".BR select (2),
+.\".BR semop (2),
+.\".BR sigwaitinfo (2),
+.\".BR stat (2),
+.\".BR timerfd_create (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.\".BR timer_settime (2),
+.\".BR utimensat (2),
+.\".BR aio_suspend (3),
+.\".BR clock_getcpuclockid (3),
+.\".BR getaddrinfo_a (3),
+.\".BR mq_receive (3),
+.\".BR mq_send (3),
+.\".BR pthread_getcpuclockid (3),
+.\".BR pthread_tryjoin_np (3),
+.\".BR sem_wait (3),
+.\".BR socket (7)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-xxxx and later.
+.IP
+See also:
+.BR adjtimex (2),
+.BR futimesat (2),
+.BR getitimer (2),
+.BR getpriority (2),
+.BR getrusage (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR syscall (2),
+.BR syscalls (2),
+.BR utime (2),
+.BR wait4 (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR ntp_gettime (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3),
+.BR utmp (5),
+.BR packet (7),
+.BR socket (7)
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v3] sigval.3, ssize_t.3, suseconds_t.3, time_t.3, timer_t.3, timespec.3, timeval.3, system_data_types.7: Document system types (draft v3)
2020-09-15 0:47 ` [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
@ 2020-09-15 6:22 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-15 6:22 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, fweimer, libbsd, jwilk
Hi Alex,
On 9/15/20 2:47 AM, Alejandro Colomar wrote:
> Changelog since dratf v2:
>
> - Remove struct/union keywords from list of type names (and sort)
> - wfix
> - ffix
> - Add all the headers that define each type
> - Specify the layout of the list in a comment
> - Add size_t type (I had to do it :-)
>
>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
[...]
>>> If I added every header that has a line like that, the lists of headers
>>> would be much bigger for most of the types. It could be good, but I
>>> don't know if we should do it. Maybe we should limit to the headers
>>> that are required by CXX and the ones where the POSIX docs actually
>>> document the type (this header doesn't define it, and instead it defers
>>> to <sys//types.h> for example).
>>>
>>> Your thoughts?
>> I think the list would not be so long. Maybe two headers sometimes,
>> occasionally three, but I doubt more. At least right now, I think we
>> should do it; I may yet be shown the error of my ways :-).
Okay -- so you showed me otherwise :-).
> The list is rather long, but now I don't deel it's too much, and it has
> some value. I'd keep all of them. See my comment (Layout) in the page,
> and feel free to add to/modify it.
I think I agree.
>> Good progress so far. Thanks, Alex!
>>
>> Cheers,
>>
>> Michael
>
> Thank you too, Michael!
By now, I think we're getting pretty close. I have a few small
comments below, but other than that, I think once the details
of individual types have been fixed, I think we're good to go.
> man3/sigval.3 | 1 +
> man3/ssize_t.3 | 1 +
> man3/suseconds_t.3 | 1 +
> man3/time_t.3 | 1 +
> man3/timer_t.3 | 1 +
> man3/timespec.3 | 1 +
> man3/timeval.3 | 1 +
> man7/system_data_types.7 | 349 +++++++++++++++++++++++++++++++++++++++
> 8 files changed, 356 insertions(+)
> create mode 100644 man3/sigval.3
> create mode 100644 man3/ssize_t.3
> create mode 100644 man3/suseconds_t.3
> create mode 100644 man3/time_t.3
> create mode 100644 man3/timer_t.3
> create mode 100644 man3/timespec.3
> create mode 100644 man3/timeval.3
> create mode 100644 man7/system_data_types.7
Let's have two patches. One for the initial page, and then one for
the links. When adding other types later, the same thing: a patch
for the added text, and a separate patch for the link(s). This
makes it a little easier for my scripts that generate the changelog.
> diff --git a/man3/sigval.3 b/man3/sigval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/sigval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/ssize_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/suseconds_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/time_t.3 b/man3/time_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/time_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timer_t.3 b/man3/timer_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timer_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timespec.3 b/man3/timespec.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timespec.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man3/timeval.3 b/man3/timeval.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/timeval.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..dd93c6746
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,349 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein. The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\" * Add types
> +.\" * Check specific POSIX "Conforming to" versions
> +.\" * Correctly highlight function names and similar (see timer_t)
> +.\" * Curate "See also"
> +.\" Layout:
> +.\" A list of type names (the struct/union keyword will be omitted).
> +.\" Each entry will have the following parts:
> +.\" * Include
> +.\" The headers will be in the following order:
> +.\" 1) The header(s) that shall define the type
> +.\" according to the C standard,
> +.\" in alphabetical order.
> +.\" 2) The header that shall define the type
> +.\" according to POSIX.
> +.\" 3) All other headers that shall define the type
> +.\" as described in the previous header
> +.\" according to POSIX,
> +.\" in alphabetical order.
> +.\" 4) All other headers that define the type
> +.\" that are Linux specific,
> +.\" in alphabetical order.
I think the reader won't easily deduce the above ordering.
I think just the following will be fine:
* (1)/(2) (merged is fine)
* The rest, ordered alphabetically.
> +.\"
> +.\" * Definition (no "Definition" header)
> +.\" Only struct/union types will have definition;
> +.\" typedefs will remain opaque.
> +.\"
> +.\" * Description (no "Description" header)
> +.\" A few lines describing the type.
> +.\"
> +.\" * Conforming to
> +.\" example: CXY and later; POSIX.1-XXXX and later
> +.\" Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\" * Notes (optional)
> +.\"
> +.\" * See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> + int sigval_int; /* Integer value */
> + void *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>
> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR TODO (XXX),
> +.BR TODO (may be too large)
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
Above two lines should also be commented out.
> +.\".BR getitimer (2),
> +.\".BR gettimeofday (2),
> +.\".BR select (2),
> +.\".BR adjtime (3),
> +.\".BR ntp_gettime (3),
> +.\".BR timeval (3),
> +.\".BR timeradd (3)
> +.IP
> +See also the
> +.B timeval
s/.B/.I/
> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-xxxx and later.
> +.IP
Just a placeholder note that the following lis still needs trimming/tuning.
> +See also:
> +.BR clock_getres (2),
> +.BR clock_nanosleep (2),
> +.BR getitimer (2),
> +.BR gettimeofday (2),
> +.BR io_getevents (2),
> +.BR keyctl (2),
> +.BR msgctl (2),
> +.BR msgop (2),
> +.BR nanosleep (2),
> +.BR sched_rr_get_interval (2),
> +.BR select (2),
> +.BR semctl (2),
> +.BR shmctl (2),
> +.BR stat (2),
> +.BR stime (2),
> +.BR time (2),
> +.BR timerfd_create (2),
> +.BR timer_settime (2),
> +.BR times (2),
> +.BR utime (2),
> +.BR utimensat (2),
> +.BR adjtime (3),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR ftime (3),
> +.BR mq_receive (3),
> +.BR mq_send (3),
> +.BR newlocale (3),
> +.BR ntp_gettime (3),
> +.BR pthread_cleanup_push (3),
> +.BR pthread_tryjoin_np (3),
> +.BR rtime (3),
> +.BR sem_wait (3),
> +.BR strcat (3),
> +.BR strftime (3),
> +.BR timegm (3),
> +.BR timeradd (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +There are no defined comparison or assignment operators for this type.
I think the above sentence should better start with something like
"According to POSIX..."
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>
> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>
> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>
> +.IP
> +.EX
> +struct timespec {
> + time_t tv_sec; /* Seconds */
> + long tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-xxxx and later.
> +.IP
> +See also:
> +.\".BR clock_getres (2),
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.\".BR futex (2),
> +.\".BR io_getevents (2),
> +.BR nanosleep (2),
> +.\".BR poll (2),
> +.\".BR recvmmsg (2),
> +.\".BR sched_rr_get_interval (2),
> +.\".BR select (2),
> +.\".BR semop (2),
> +.\".BR sigwaitinfo (2),
> +.\".BR stat (2),
> +.\".BR timerfd_create (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.\".BR timer_settime (2),
> +.\".BR utimensat (2),
> +.\".BR aio_suspend (3),
> +.\".BR clock_getcpuclockid (3),
> +.\".BR getaddrinfo_a (3),
> +.\".BR mq_receive (3),
> +.\".BR mq_send (3),
> +.\".BR pthread_getcpuclockid (3),
> +.\".BR pthread_tryjoin_np (3),
> +.\".BR sem_wait (3),
> +.\".BR socket (7)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> + time_t tv_sec; /* Seconds */
> + suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-xxxx and later.
> +.IP
Just a placeholder note that the following lis still needs trimming/tuning.
> +See also:
> +.BR adjtimex (2),
> +.BR futimesat (2),
> +.BR getitimer (2),
> +.BR getpriority (2),
> +.BR getrusage (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR syscall (2),
> +.BR syscalls (2),
> +.BR utime (2),
> +.BR wait4 (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR ntp_gettime (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3),
> +.BR utmp (5),
> +.BR packet (7),
> +.BR socket (7)
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-14 10:22 ` Alejandro Colomar
2020-09-14 14:03 ` [RFC v2] system_data_types.7: Draft v2 Alejandro Colomar
2020-09-15 0:47 ` [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
@ 2020-09-15 13:33 ` Alejandro Colomar
2020-09-15 21:30 ` Michael Kerrisk (man-pages)
2020-09-16 10:52 ` [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
` (10 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-15 13:33 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, fweimer, libbsd, jwilk, Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
This is already a release candidate, I'd say.
Changelog since Draft v3:
- Specify POSIX versions
- ffix
- wfix
- Curate See also
On 2020-09-15 08:22, Michael Kerrisk (man-pages) wrote:
> I think the reader won't easily deduce the above ordering.
> I think just the following will be fine:
> * (1)/(2) (merged is fine)
> * The rest, ordered alphabetically.
I'm not sure I fully understood it. Please check the updated comments.
No type required actual modifications after that change.
Basically, I merged (3) & (4).
>> +Conforming to: POSIX.1-xxxx and later.
>> +.IP
>> +See also:
> Above two lines should also be commented out.
Done
>> +See also the
>> +.B timeval
> s/.B/.I/
Done
I decided to definitively remove many of the see also links.
They were most of them junk.
Cheers,
Alex
man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
1 file changed, 304 insertions(+)
create mode 100644 man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..9011ce74e
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Curate "See also"
+.\" Layout:
+.\" A list of type names (the struct/union keyword will be omitted).
+.\" Each entry will have the following parts:
+.\" * Include
+.\" The headers will be in the following order:
+.\" 1) The header(s) that shall define the type
+.\" according to the C standard,
+.\" in alphabetical order.
+.\" 2) The header that shall define the type
+.\" according to POSIX.
+.\" 3) All other headers that shall define the type
+.\" as described in the previous header
+.\" according to POSIX,
+.\" and
+.\" all other headers that define the type
+.\" that are Linux specific,
+.\" in alphabetical order.
+.\"
+.\" * Definition (no "Definition" header)
+.\" Only struct/union types will have definition;
+.\" typedefs will remain opaque.
+.\"
+.\" * Description (no "Description" header)
+.\" A few lines describing the type.
+.\"
+.\" * Conforming to
+.\" example: CXY and later; POSIX.1-XXXX and later.
+.\" Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\" * Notes (optional)
+.\"
+.\" * See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR copy_file_range (2),
+.BR getrandom (2),
+.BR getxattr (2),
+.BR listxattr (2),
+.BR msgrcv (2),
+.BR pread (2),
+.BR process_vm_readv (2),
+.BR read (2),
+.BR readahead (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR sendfile (2),
+.BR splice (2),
+.BR tee (2),
+.BR vmsplice (2),
+.BR write (2),
+.BR aio_return (3),
+.BR getdirentries (3),
+.BR getline (3),
+.BR mq_receive (3),
+.BR strfmon (3),
+.BR swab (3),
+.BR mq_receive (3)
+.IP
+See also the
+.I size_t
+type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.\".IP
+.\"See also:
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR timer_settime (2),
+.BR ctime (3),
+.BR difftime (3),
+.BR timegm (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR futimesat (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3)
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-15 13:33 ` [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval Alejandro Colomar
@ 2020-09-15 21:30 ` Michael Kerrisk (man-pages)
2020-09-16 0:59 ` Thorsten Glaser
0 siblings, 1 reply; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-15 21:30 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: mtk.manpages, linux-man, fweimer, libbsd, jwilk
Hi Alex,
On 9/15/20 3:33 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> This is already a release candidate, I'd say.
Okay. Time to nit pick :-). Do not be too dispirited,
I think we started with some of the most difficult types...
> Changelog since Draft v3:
>
> - Specify POSIX versions
> - ffix
> - wfix
> - Curate See also
> On 2020-09-15 08:22, Michael Kerrisk (man-pages) wrote:
>> I think the reader won't easily deduce the above ordering.
>> I think just the following will be fine:
>> * (1)/(2) (merged is fine)
>> * The rest, ordered alphabetically.
>
> I'm not sure I fully understood it. Please check the updated comments.
> No type required actual modifications after that change.
>
> Basically, I merged (3) & (4).
I soppose what I meant is that POSIX defers to the C standard
in the cases where they overlap, and I'd expect that the set
of headers specified in the C standard and in POSIX might be the
same, but where they're not, I suspect the list of POSIX headers
would always be a superset of the C headers. So, just make a
single list of those headers, followed by 3 and 4 (merged)
[...]
> man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 304 insertions(+)
> create mode 100644 man7/system_data_types.7
>
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..9011ce74e
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,304 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein. The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\" * Add types
> +.\" * Curate "See also"
> +.\" Layout:
> +.\" A list of type names (the struct/union keyword will be omitted).
> +.\" Each entry will have the following parts:
> +.\" * Include
> +.\" The headers will be in the following order:
> +.\" 1) The header(s) that shall define the type
> +.\" according to the C standard,
> +.\" in alphabetical order.
> +.\" 2) The header that shall define the type
> +.\" according to POSIX.
See my comments above.
> +.\" 3) All other headers that shall define the type
> +.\" as described in the previous header
> +.\" according to POSIX,
> +.\" and
> +.\" all other headers that define the type
> +.\" that are Linux specific,
> +.\" in alphabetical order.
> +.\"
> +.\" * Definition (no "Definition" header)
> +.\" Only struct/union types will have definition;
> +.\" typedefs will remain opaque.
> +.\"
> +.\" * Description (no "Description" header)
> +.\" A few lines describing the type.
> +.\"
> +.\" * Conforming to
> +.\" example: CXY and later; POSIX.1-XXXX and later.
> +.\" Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\" * Notes (optional)
> +.\"
> +.\" * See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> + int sigval_int; /* Integer value */
> + void *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
I think we can drop mq_notify(3). Its relationship to sigval is
somewhat indirect, and is covered via sigevent(7).
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:
Okay, now I look closer at these lists. How have you determined them?
> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>
The type is mentioned in the <limits.h> spec, but it is not required to
be defined by that header. (grep is not enough; one must read the text,
sorry :-).)
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>
The type is mentioned in the <regex.h> spec, but it is not required to
be defined by that header.
> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
Today I learned: size_t is in C99, but ssize_t is not!
> +.IP
> +See also:
Okay -- I think this list really is rather too long; I'm not
convinced that it brings value.
I suggest dropping the pages marked XX. The remaining can serve
as the (commonly used) exemplars of APIs that use this type.
XX > +.BR copy_file_range (2),
XX > +.BR getrandom (2),
XX > +.BR getxattr (2),
XX > +.BR listxattr (2),
XX > +.BR msgrcv (2),
XX > +.BR pread (2),
XX > +.BR process_vm_readv (2),
> +.BR read (2),
XX > +.BR readahead (2),
> +.BR readlink (2),
> +.BR readv (2),
> +.BR recv (2),
> +.BR send (2),
XX > +.BR sendfile (2),
XX > +.BR splice (2),
XX > +.BR tee (2),
XX > +.BR vmsplice (2),
> +.BR write (2),
XX > +.BR aio_return (3),
XX > +.BR getdirentries (3),
XX > +.BR getline (3),
XX > +.BR mq_receive (3),
XX > +.BR strfmon (3),
XX > +.BR swab (3),
XX > +.BR mq_receive (3)
> +.IP
> +See also the
> +.I size_t
> +type in this page.
But size_t is not in this page (yet). Is it in your tree?
By the way,from my reading of POSIX.1-2008, the list of headers that
define size_t is:
<sys/types.h>
<aio.h>
<glob.h>
<grp.h>
<iconv.h>
<monetary.h>
<mqueue.h>
<ndbm.h>
<pwd.h>
<regex.h>
<search.h>
<signal.h>
<stddef.h>
<stdio.h>
<stdlib.h>
<string.h>
<strings.h>
<sys/mman.h>
<sys/msg.h>
<sys/sem.h>
<sys/shm.h>
<sys/socket.h>
<sys/uio.h>
<time.h>
<trace.h> # But omit, because not on Linux
<unistd.h>
<wchar.h>
<wordexp.h>
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>
The type is mentioned in the <limits.h> spec, but it is not required to
be defined by that header. grep is not enough; one must read the text,
sorry :-).
> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.\".IP
> +.\"See also:
Remove the above two lines.
> +.IP
> +See also the
> +.I timeval
> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.h>
<sched.h> only defines time_t since POSIX.1-2008, as far as I can
tell! I'm not sure how/if we want to represent that detail.
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
Drop lines marked XX
> +.BR stime (2),
> +.BR time (2)XX > +.BR timer_settime (2),
(time_t turns up only as part of timespec)
> +.BR ctime (3),
> +.BR difftime (3),
XX > +.BR timegm (3)
(timegm(3) is not in POSIX; let's ignore it in this page.)
> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +According to POSIX,
> +there are no defined comparison or assignment operators for this type.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>
AFAICS, the type is mentioned in the <pthread.h> spec, but it is not
required to be defined by that header.
> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>
AFAICS, the type is mentioned in the <semaphore.h> spec, but it is not
required to be defined by that header.
> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>
AFAICS, the type is mentioned in the <trace.h> spec, but it is not
required to be defined by that header.
> +.IP
> +.EX
> +struct timespec {
> + time_t tv_sec; /* Seconds */
> + long tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.BR nanosleep (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> + time_t tv_sec; /* Seconds */
> + suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
Let's limit things to a representative sample:
XX > +.BR futimesat (2),
futimesat() is obsolete and nonstandard.
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR utimes (2),
> +.BR adjtime (3),
> +.BR futimes (3),
XX > +.BR rpc (3),
XX > +.BR rtime (3),
These two are probably more obscure. We don't need to mention
them, I think.
> +.BR timeradd (3)
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-15 21:30 ` Michael Kerrisk (man-pages)
@ 2020-09-16 0:59 ` Thorsten Glaser
2020-09-16 8:03 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 51+ messages in thread
From: Thorsten Glaser @ 2020-09-16 0:59 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Alejandro Colomar, fweimer, linux-man, jwilk, libbsd
Michael Kerrisk (man-pages) dixit:
>> +.\" %%%LICENSE_START(VERBATIM)
>> +.\" Permission is granted to make and distribute verbatim copies of this
>> +.\" manual provided the copyright notice and this permission notice are
>> +.\" preserved on all copies.
>> +.\"
>> +.\" Permission is granted to copy and distribute modified versions of this
>> +.\" manual under the conditions for verbatim copying, provided that the
>> +.\" entire resulting derived work is distributed under the terms of a
>> +.\" permission notice identical to this one.
>> +.\"
>> +.\" Since the Linux kernel and libraries are constantly changing, this
>> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
>> +.\" responsibility for errors or omissions, or for damages resulting from
>> +.\" the use of the information contained herein. The author(s) may not
>> +.\" have taken the same level of care in the production of this manual,
>> +.\" which is licensed free of charge, as they might when working
>> +.\" professionally.
>> +.\"
>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>> +.\" the source, must acknowledge the copyright and authors of this work.
>> +.\" %%%LICENSE_END
I severely object.
This licence doesn’t even have an SPDX identifier, nor is it
OSI certified.
Please use a standard Open Source licence, *especially* as you
are introducing new material here.
Before submitting this eMail, I found
https://www.kernel.org/doc/man-pages/licenses.html
and if that is indeed the applicable document, please use BSD.
Thanks,
//mirabilos
--
I believe no one can invent an algorithm. One just happens to hit upon it
when God enlightens him. Or only God invents algorithms, we merely copy them.
If you don't believe in God, just consider God as Nature if you won't deny
existence. -- Coywolf Qi Hunt
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-16 0:59 ` Thorsten Glaser
@ 2020-09-16 8:03 ` Michael Kerrisk (man-pages)
2020-09-16 10:06 ` Andries E. Brouwer
0 siblings, 1 reply; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-16 8:03 UTC (permalink / raw)
To: Thorsten Glaser
Cc: mtk.manpages, Alejandro Colomar, fweimer, linux-man, jwilk,
libbsd, Andries Brouwer
[CC += AEB]
On 9/16/20 2:59 AM, Thorsten Glaser wrote:
> Michael Kerrisk (man-pages) dixit:
>
>>> +.\" %%%LICENSE_START(VERBATIM)
>>> +.\" Permission is granted to make and distribute verbatim copies of this
>>> +.\" manual provided the copyright notice and this permission notice are
>>> +.\" preserved on all copies.
>>> +.\"
>>> +.\" Permission is granted to copy and distribute modified versions of this
>>> +.\" manual under the conditions for verbatim copying, provided that the
>>> +.\" entire resulting derived work is distributed under the terms of a
>>> +.\" permission notice identical to this one.
>>> +.\"
>>> +.\" Since the Linux kernel and libraries are constantly changing, this
>>> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
>>> +.\" responsibility for errors or omissions, or for damages resulting from
>>> +.\" the use of the information contained herein. The author(s) may not
>>> +.\" have taken the same level of care in the production of this manual,
>>> +.\" which is licensed free of charge, as they might when working
>>> +.\" professionally.
>>> +.\"
>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>>> +.\" the source, must acknowledge the copyright and authors of this work.
>>> +.\" %%%LICENSE_END
>
> I severely object.
And as someone with no history of involvement with the man-pages project
(at least as far as I am aware), and seemingly little awareness of the
history or practices of the project, we should listen to you because...?
To be clear: I ask that provocative question because the strident,
demanding tone of your mail rubs me the wrong way. Please take it
somewhere else than this list.
> This licence doesn’t even have an SPDX identifier, nor is it
> OSI certified.
True, though OSI is in the business of certifying software
licenses, not documentation licenses. That said, I'd have
no problem with someone attempting OSI certification of the
license or doing the mechanics of obtaining an SPDX identifier
for it.
> Please use a standard Open Source licence, *especially* as you
> are introducing new material here.
The "verbatim" license has been the most widely used license in
manual pages, almost since the inception of the project 27 years
ago. (Currently more than half of the pages carry this license.)
I don't know the origin of the license (perhaps AEB does),
but as far as I'm concerned, it is a satisfactory license for
its purpose. And since on the one hand it is, and has been, the
most widely used license and, on the other hand, I am interested
to avoid license proliferation, it's my preferred choice for new
pages. But, as you note, there are other choices:
> Before submitting this eMail, I found
> https://www.kernel.org/doc/man-pages/licenses.html
> and if that is indeed the applicable document, please use BSD.
(Obviously) I have no objection to this license, but currently
about 5% of pages in the project use some flavor of BSD license,
and then mainly because they were lifted straight from a BSD.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-16 8:03 ` Michael Kerrisk (man-pages)
@ 2020-09-16 10:06 ` Andries E. Brouwer
2020-09-16 11:00 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 51+ messages in thread
From: Andries E. Brouwer @ 2020-09-16 10:06 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: Thorsten Glaser, Alejandro Colomar, fweimer, linux-man, jwilk,
libbsd, Andries Brouwer
On Wed, Sep 16, 2020 at 10:03:13AM +0200, Michael Kerrisk (man-pages) wrote:
> [CC += AEB]
>
>> Michael Kerrisk (man-pages) dixit:
>>
>>>> +.\" %%%LICENSE_START(VERBATIM)
>>>> +.\" Permission is granted to make and distribute verbatim copies of this
>>>> +.\" manual provided the copyright notice and this permission notice are
>>>> +.\" preserved on all copies.
>>>> +.\"
>>>> +.\" Permission is granted to copy and distribute modified versions of this
>>>> +.\" manual under the conditions for verbatim copying, provided that the
>>>> +.\" entire resulting derived work is distributed under the terms of a
>>>> +.\" permission notice identical to this one.
>>>> +.\"
>>>> +.\" Since the Linux kernel and libraries are constantly changing, this
>>>> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
>>>> +.\" responsibility for errors or omissions, or for damages resulting from
>>>> +.\" the use of the information contained herein. The author(s) may not
>>>> +.\" have taken the same level of care in the production of this manual,
>>>> +.\" which is licensed free of charge, as they might when working
>>>> +.\" professionally.
>>>> +.\"
>>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
>>>> +.\" the source, must acknowledge the copyright and authors of this work.
>>>> +.\" %%%LICENSE_END
>>
>> I severely object.
>
> The "verbatim" license has been the most widely used license in
> manual pages, almost since the inception of the project 27 years
> ago. (Currently more than half of the pages carry this license.)
>
> I don't know the origin of the license (perhaps AEB does),
Digging through old sources reveals:
I started maintaing man-pages in 1995.
My first release was man-pages-1.6.
That release contained 245 man pages with the above license.
The first release that had the above license was man-pages-1.4,
released Sep 1994 by Rik Faith.
It contained 234 man pages with the above license.
man-pages-1.4.Announce describes that there are now
238 pages with "verbatim copying" and
41 pages with "GNU General Public License".
Earlier, man-pages-1.3 (released Jun 1994) by Rik Faith had
messy copyright statements or nothing at all, and Rik Faith made
for 1.4 a serious attempt at providing each page with a proper license.
So, this text came from Rik Faith.
It mentions "this manual page", so was probably written
especially for this manpage collection.
You might ask him for further details.
Andries
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval
2020-09-16 10:06 ` Andries E. Brouwer
@ 2020-09-16 11:00 ` Michael Kerrisk (man-pages)
0 siblings, 0 replies; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-16 11:00 UTC (permalink / raw)
To: Andries E. Brouwer
Cc: Thorsten Glaser, Alejandro Colomar, Florian Weimer, linux-man,
Jakub Wilk, libbsd
Hello Andries,
It's kind of you to reply; thank you!
On Wed, 16 Sep 2020 at 12:06, Andries E. Brouwer <Andries.Brouwer@cwi.nl> wrote:
>
> On Wed, Sep 16, 2020 at 10:03:13AM +0200, Michael Kerrisk (man-pages) wrote:
> > [CC += AEB]
> >
> >> Michael Kerrisk (man-pages) dixit:
> >>
> >>>> +.\" %%%LICENSE_START(VERBATIM)
> >>>> +.\" Permission is granted to make and distribute verbatim copies of this
> >>>> +.\" manual provided the copyright notice and this permission notice are
> >>>> +.\" preserved on all copies.
> >>>> +.\"
> >>>> +.\" Permission is granted to copy and distribute modified versions of this
> >>>> +.\" manual under the conditions for verbatim copying, provided that the
> >>>> +.\" entire resulting derived work is distributed under the terms of a
> >>>> +.\" permission notice identical to this one.
> >>>> +.\"
> >>>> +.\" Since the Linux kernel and libraries are constantly changing, this
> >>>> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> >>>> +.\" responsibility for errors or omissions, or for damages resulting from
> >>>> +.\" the use of the information contained herein. The author(s) may not
> >>>> +.\" have taken the same level of care in the production of this manual,
> >>>> +.\" which is licensed free of charge, as they might when working
> >>>> +.\" professionally.
> >>>> +.\"
> >>>> +.\" Formatted or processed versions of this manual, if unaccompanied by
> >>>> +.\" the source, must acknowledge the copyright and authors of this work.
> >>>> +.\" %%%LICENSE_END
> >>
> >> I severely object.
> >
> > The "verbatim" license has been the most widely used license in
> > manual pages, almost since the inception of the project 27 years
> > ago. (Currently more than half of the pages carry this license.)
> >
> > I don't know the origin of the license (perhaps AEB does),
>
> Digging through old sources reveals:
>
> I started maintaing man-pages in 1995.
> My first release was man-pages-1.6.
> That release contained 245 man pages with the above license.
>
> The first release that had the above license was man-pages-1.4,
> released Sep 1994 by Rik Faith.
> It contained 234 man pages with the above license.
> man-pages-1.4.Announce describes that there are now
> 238 pages with "verbatim copying" and
> 41 pages with "GNU General Public License".
>
> Earlier, man-pages-1.3 (released Jun 1994) by Rik Faith had
> messy copyright statements or nothing at all, and Rik Faith made
> for 1.4 a serious attempt at providing each page with a proper license.
>
> So, this text came from Rik Faith.
> It mentions "this manual page", so was probably written
> especially for this manpage collection.
Thanks for the insight. I had noticed that the license wasn't there
right at the start, but that it appeared very soon afterwards. It
hadn't occurred to me that perhaps Rik might be the author of the
license.
> You might ask him for further details.
I tried a few times over the years to contact Rik on other matters,
but either I was using the wrong channels, or he didn't reply. I'll
try again via another channel.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-14 10:22 ` Alejandro Colomar
` (2 preceding siblings ...)
2020-09-15 13:33 ` [RFC v4] system_data_types.7: Document sigval, ssize_t, suseconds_t, time_t, timer_t, timespec & timeval Alejandro Colomar
@ 2020-09-16 10:52 ` Alejandro Colomar
2020-09-16 10:56 ` Alejandro Colomar
2020-09-16 11:01 ` [RFC v6] " Alejandro Colomar
` (9 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-16 10:52 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
Changelog since v4:
- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers
On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
> Okay. Time to nit pick:-). Do not be too dispirited,
> I think we started with some of the most difficult types...
I was waiting for it :-).
> I soppose what I meant is that POSIX defers to the C standard
> in the cases where they overlap, and I'd expect that the set
> of headers specified in the C standard and in POSIX might be the
> same, but where they're not, I suspect the list of POSIX headers
> would always be a superset of the C headers. So, just make a
> single list of those headers, followed by 3 and 4 (merged)
See updated comment in the page.
> I suggest dropping the pages marked XX. The remaining can serve
> as the (commonly used) exemplars of APIs that use this type.
Done. I don't have experience enough to subjectively decide
which ones should stay and which ones we should drop, so...
> Okay, now I look closer at these lists. How have you determined them?
I kept references to all APIs that use the type in the prototype.
And for the headers list:
I started reading the contents of the headers, but all I had seen
did actually define the type, so I guessed that all the remaining
grep appearances would also define the type. Clearly, I guessed wrong.
> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
> tell! I'm not sure how/if we want to represent that detail.
I added a Notes section for that type. You like it?
> But size_t is not in this page (yet). Is it in your tree?
Not yet. In my tree I didn't forget to comment it, though. As you can
guess, It'll be the next type to document, and then ptrdiff_t.
> Today I learned: size_t is in C99, but ssize_t is not!
:)
Cheers,
Alex.
man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
1 file changed, 304 insertions(+)
create mode 100644 man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..1616d858c
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,304 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Curate "See also"
+.\" Layout:
+.\" A list of type names (the struct/union keyword will be omitted).
+.\" Each entry will have the following parts:
+.\" * Include
+.\" The headers will be in the following order:
+.\" 1) The header(s) that shall define the type
+.\" according to the C standard,
+.\" in alphabetical order.
+.\" 2) The header that shall define the type
+.\" according to POSIX.
+.\" 3) All other headers that shall define the type
+.\" as described in the previous header
+.\" according to POSIX,
+.\" and
+.\" all other headers that define the type
+.\" that are Linux specific,
+.\" in alphabetical order.
+.\"
+.\" * Definition (no "Definition" header)
+.\" Only struct/union types will have definition;
+.\" typedefs will remain opaque.
+.\"
+.\" * Description (no "Description" header)
+.\" A few lines describing the type.
+.\"
+.\" * Conforming to
+.\" Format: CXY and later; POSIX.1-XXXX and later.
+.\" Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\" * Notes (optional)
+.\"
+.\" * See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR mq_notify (3),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <limits.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <regex.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR copy_file_range (2),
+.BR getrandom (2),
+.BR getxattr (2),
+.BR listxattr (2),
+.BR msgrcv (2),
+.BR pread (2),
+.BR process_vm_readv (2),
+.BR read (2),
+.BR readahead (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR sendfile (2),
+.BR splice (2),
+.BR tee (2),
+.BR vmsplice (2),
+.BR write (2),
+.BR aio_return (3),
+.BR getdirentries (3),
+.BR getline (3),
+.BR mq_receive (3),
+.BR strfmon (3),
+.BR swab (3),
+.BR mq_receive (3)
+.\".IP FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+or
+.I <unistd.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.\".IP
+.\"See also:
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <time.h>
+or
+.I <sys/types.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR timer_settime (2),
+.BR ctime (3),
+.BR difftime (3),
+.BR timegm (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <pthread.h>
+or
+.I <sched.h>
+or
+.I <semaphore.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+or
+.I <trace.h>
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR futimesat (2),
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR rpc (3),
+.BR rtime (3),
+.BR timeradd (3)
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 10:52 ` [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
@ 2020-09-16 10:56 ` Alejandro Colomar
0 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-16 10:56 UTC (permalink / raw)
To: mtk.manpages; +Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
Sorry, this patch is old.
Somehow I mixed the new version with this.
I'll resend it correctly in a few minutes as v6
Alex
On 2020-09-16 12:52, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> Changelog since v4:
>
> - Comment "See also" about yet undocumented size_t
> - Simplify header ordering
> - Curate See also
> - Remove incorrect headers
>
>
> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
>> Okay. Time to nit pick:-). Do not be too dispirited,
>> I think we started with some of the most difficult types...
>
> I was waiting for it :-).
>
>> I soppose what I meant is that POSIX defers to the C standard
>> in the cases where they overlap, and I'd expect that the set
>> of headers specified in the C standard and in POSIX might be the
>> same, but where they're not, I suspect the list of POSIX headers
>> would always be a superset of the C headers. So, just make a
>> single list of those headers, followed by 3 and 4 (merged)
>
> See updated comment in the page.
>
>> I suggest dropping the pages marked XX. The remaining can serve
>> as the (commonly used) exemplars of APIs that use this type.
>
> Done. I don't have experience enough to subjectively decide
> which ones should stay and which ones we should drop, so...
>
>> Okay, now I look closer at these lists. How have you determined them?
>
> I kept references to all APIs that use the type in the prototype.
>
> And for the headers list:
>
> I started reading the contents of the headers, but all I had seen
> did actually define the type, so I guessed that all the remaining
> grep appearances would also define the type. Clearly, I guessed wrong.
>
>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
>> tell! I'm not sure how/if we want to represent that detail.
>
> I added a Notes section for that type. You like it?
>
>> But size_t is not in this page (yet). Is it in your tree?
>
> Not yet. In my tree I didn't forget to comment it, though. As you can
> guess, It'll be the next type to document, and then ptrdiff_t.
>
>> Today I learned: size_t is in C99, but ssize_t is not!
>
> :)
>
> Cheers,
>
> Alex.
>
> man7/system_data_types.7 | 304 +++++++++++++++++++++++++++++++++++++++
> 1 file changed, 304 insertions(+)
> create mode 100644 man7/system_data_types.7
>
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> new file mode 100644
> index 000000000..1616d858c
> --- /dev/null
> +++ b/man7/system_data_types.7
> @@ -0,0 +1,304 @@
> +.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
> +.\"
> +.\" %%%LICENSE_START(VERBATIM)
> +.\" Permission is granted to make and distribute verbatim copies of this
> +.\" manual provided the copyright notice and this permission notice are
> +.\" preserved on all copies.
> +.\"
> +.\" Permission is granted to copy and distribute modified versions of this
> +.\" manual under the conditions for verbatim copying, provided that the
> +.\" entire resulting derived work is distributed under the terms of a
> +.\" permission notice identical to this one.
> +.\"
> +.\" Since the Linux kernel and libraries are constantly changing, this
> +.\" manual page may be incorrect or out-of-date. The author(s) assume no
> +.\" responsibility for errors or omissions, or for damages resulting from
> +.\" the use of the information contained herein. The author(s) may not
> +.\" have taken the same level of care in the production of this manual,
> +.\" which is licensed free of charge, as they might when working
> +.\" professionally.
> +.\"
> +.\" Formatted or processed versions of this manual, if unaccompanied by
> +.\" the source, must acknowledge the copyright and authors of this work.
> +.\" %%%LICENSE_END
> +.\"
> +.\"
> +.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
> +.SH NAME
> +system_data_types \- overview of system data types
> +.SH DESCRIPTION
> +.\" TODO:
> +.\" * Add types
> +.\" * Curate "See also"
> +.\" Layout:
> +.\" A list of type names (the struct/union keyword will be omitted).
> +.\" Each entry will have the following parts:
> +.\" * Include
> +.\" The headers will be in the following order:
> +.\" 1) The header(s) that shall define the type
> +.\" according to the C standard,
> +.\" in alphabetical order.
> +.\" 2) The header that shall define the type
> +.\" according to POSIX.
> +.\" 3) All other headers that shall define the type
> +.\" as described in the previous header
> +.\" according to POSIX,
> +.\" and
> +.\" all other headers that define the type
> +.\" that are Linux specific,
> +.\" in alphabetical order.
> +.\"
> +.\" * Definition (no "Definition" header)
> +.\" Only struct/union types will have definition;
> +.\" typedefs will remain opaque.
> +.\"
> +.\" * Description (no "Description" header)
> +.\" A few lines describing the type.
> +.\"
> +.\" * Conforming to
> +.\" Format: CXY and later; POSIX.1-XXXX and later.
> +.\" Forget about pre-C99 C standards (i.e., C89/C90)
> +.\"
> +.\" * Notes (optional)
> +.\"
> +.\" * See also
> +.TP
> +.I sigval
> +.IP
> +Include:
> +.I <signal.h>
> +.IP
> +.EX
> +union sigval {
> + int sigval_int; /* Integer value */
> + void *sigval_ptr; /* Pointer value */
> +};
> +.EE
> +.IP
> +Data passed with a signal.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR rt_sigqueueinfo (2),
> +.BR sigaction (2),
> +.BR mq_notify (3),
> +.BR pthread_sigqueue (3),
> +.BR sigqueue (3),
> +.BR sigevent (7)
> +.TP
> +.I ssize_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <aio.h>
> +or
> +.I <limits.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <regex.h>
> +or
> +.I <stdio.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for a count of bytes or an error indication.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1,
> +.BR SSIZE_MAX ].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR copy_file_range (2),
> +.BR getrandom (2),
> +.BR getxattr (2),
> +.BR listxattr (2),
> +.BR msgrcv (2),
> +.BR pread (2),
> +.BR process_vm_readv (2),
> +.BR read (2),
> +.BR readahead (2),
> +.BR readlink (2),
> +.BR readv (2),
> +.BR recv (2),
> +.BR send (2),
> +.BR sendfile (2),
> +.BR splice (2),
> +.BR tee (2),
> +.BR vmsplice (2),
> +.BR write (2),
> +.BR aio_return (3),
> +.BR getdirentries (3),
> +.BR getline (3),
> +.BR mq_receive (3),
> +.BR strfmon (3),
> +.BR swab (3),
> +.BR mq_receive (3)
> +.\".IP FIXME: When size_t is added, uncomment
> +.\"See also the
> +.\".I size_t
> +.\"type in this page.
> +.TP
> +.I suseconds_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <unistd.h>
> +.IP
> +Used for time in microseconds.
> +According to POSIX, it shall be a signed integer type
> +capable of storing values at least in the range [-1, 1000000].
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.\".IP
> +.\"See also:
> +.IP
> +See also the
> +.I timeval
> +structure in this page.
> +.TP
> +.I time_t
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <sys/types.h>
> +or
> +.I <sched.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <sys/time.h>
> +or
> +.I <utime.h>
> +.IP
> +Used for time in seconds.
> +According to POSIX, it shall be an integer type.
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR stime (2),
> +.BR time (2),
> +.BR timer_settime (2),
> +.BR ctime (3),
> +.BR difftime (3),
> +.BR timegm (3)
> +.TP
> +.I timer_t
> +.IP
> +Include:
> +.I <sys/types.h>
> +or
> +.I <time.h>
> +.IP
> +Used for timer ID returned by
> +.BR timer_create (2).
> +According to POSIX,
> +there are no defined comparison or assignment operators for this type.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR timer_create (2),
> +.BR timer_delete (2),
> +.BR timer_getoverrun (2),
> +.BR timer_settime (2)
> +.TP
> +.I timespec
> +.IP
> +Include:
> +.I <time.h>
> +or
> +.I <aio.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <pthread.h>
> +or
> +.I <sched.h>
> +or
> +.I <semaphore.h>
> +or
> +.I <signal.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <sys/stat.h>
> +or
> +.I <trace.h>
> +.IP
> +.EX
> +struct timespec {
> + time_t tv_sec; /* Seconds */
> + long tv_nsec; /* Nanoseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and nanoseconds.
> +.IP
> +Conforming to: C11 and later; POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR clock_gettime (2),
> +.BR clock_nanosleep (2),
> +.BR nanosleep (2),
> +.BR timerfd_gettime (2),
> +.BR timer_gettime (2)
> +.TP
> +.I timeval
> +.IP
> +Include:
> +.I <sys/time.h>
> +or
> +.I <sys/resource.h>
> +or
> +.I <sys/select.h>
> +or
> +.I <utmpx.h>
> +.IP
> +.EX
> +struct timeval {
> + time_t tv_sec; /* Seconds */
> + suseconds_t tv_usec; /* Microseconds */
> +};
> +.EE
> +.IP
> +Describes times in seconds and microseconds.
> +.IP
> +Conforming to: POSIX.1-2001 and later.
> +.IP
> +See also:
> +.BR futimesat (2),
> +.BR gettimeofday (2),
> +.BR select (2),
> +.BR utimes (2),
> +.BR adjtime (3),
> +.BR futimes (3),
> +.BR rpc (3),
> +.BR rtime (3),
> +.BR timeradd (3)
>
^ permalink raw reply [flat|nested] 51+ messages in thread
* [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-14 10:22 ` Alejandro Colomar
` (3 preceding siblings ...)
2020-09-16 10:52 ` [RFC v5] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
@ 2020-09-16 11:01 ` Alejandro Colomar
2020-09-16 19:24 ` Michael Kerrisk (man-pages)
2020-09-17 10:42 ` [PATCH v7 0/8] Document system data types Alejandro Colomar
` (8 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-16 11:01 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
Hi Michael,
Changelog since v4:
- Comment "See also" about yet undocumented size_t
- Simplify header ordering
- Curate See also
- Remove incorrect headers
On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
> Okay. Time to nit pick:-). Do not be too dispirited,
> I think we started with some of the most difficult types...
I was waiting for it :-).
> I soppose what I meant is that POSIX defers to the C standard
> in the cases where they overlap, and I'd expect that the set
> of headers specified in the C standard and in POSIX might be the
> same, but where they're not, I suspect the list of POSIX headers
> would always be a superset of the C headers. So, just make a
> single list of those headers, followed by 3 and 4 (merged)
See updated comment in the page.
> I suggest dropping the pages marked XX. The remaining can serve
> as the (commonly used) exemplars of APIs that use this type.
Done. I don't have experience enough to subjectively decide
which ones should stay and which ones we should drop, so...
> Okay, now I look closer at these lists. How have you determined them?
I kept references to all APIs that use the type in the prototype.
And for the headers list:
I started reading the contents of the headers, but all I had seen
did actually define the type, so I guessed that all the remaining
grep appearances would also define the type. Clearly, I guessed wrong.
> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
> tell! I'm not sure how/if we want to represent that detail.
I added a Notes section for that type. You like it?
> But size_t is not in this page (yet). Is it in your tree?
Not yet. In my tree I didn't forget to comment it, though. As you can
guess, It'll be the next type to document, and then ptrdiff_t.
> Today I learned: size_t is in C99, but ssize_t is not!
:)
Cheers,
Alex.
man7/system_data_types.7 | 272 +++++++++++++++++++++++++++++++++++++++
1 file changed, 272 insertions(+)
create mode 100644 man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8fc827332
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,272 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Curate "See also"
+.\" Layout:
+.\" A list of type names (the struct/union keyword will be omitted).
+.\" Each entry will have the following parts:
+.\" * Include
+.\" The headers will be in the following order:
+.\" 1) The header(s) that shall define the type
+.\" according to the C standard,
+.\" and
+.\" the header that shall define the type
+.\" according to POSIX,
+.\" in alphabetical order.
+.\" 2) All other headers that shall define the type
+.\" as described in the previous header
+.\" according to POSIX,
+.\" in alphabetical order.
+.\" *) All headers that define the type
+.\" *if* the type is not defined by C nor POSIX,
+.\" in alphabetical order.
+.\"
+.\" * Definition (no "Definition" header)
+.\" Only struct/union types will have definition;
+.\" typedefs will remain opaque.
+.\"
+.\" * Description (no "Description" header)
+.\" A few lines describing the type.
+.\"
+.\" * Conforming to
+.\" Format: CXY and later; POSIX.1-XXXX and later.
+.\" Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\" * Notes (optional)
+.\"
+.\" * See also
+.TP
+.I sigval
+.IP
+Include:
+.I <signal.h>
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.TP
+.I ssize_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <aio.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <unistd.h>
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR read (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR write (2)
+.\".IP FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <sys/select.h>
+or
+.I <sys/time.h>
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.I <utime.h>
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+Notes:
+.I <sched.h>
+defines
+.I time_t
+since POSIX.1-2008.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR ctime (3),
+.BR difftime (3)
+.TP
+.I timer_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.I <time.h>
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.I <time.h>
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <sched.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.I <sys/stat.h>
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.I <sys/time.h>
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.I <utmpx.h>
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR timeradd (3)
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 11:01 ` [RFC v6] " Alejandro Colomar
@ 2020-09-16 19:24 ` Michael Kerrisk (man-pages)
2020-09-16 19:51 ` Alejandro Colomar
0 siblings, 1 reply; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-16 19:24 UTC (permalink / raw)
To: Alejandro Colomar
Cc: mtk.manpages, linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
Hello Alex,
On 9/16/20 1:01 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>
> Hi Michael,
>
> Changelog since v4:
>
> - Comment "See also" about yet undocumented size_t
> - Simplify header ordering
> - Curate See also
> - Remove incorrect headers
>
>
> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
>> Okay. Time to nit pick:-). Do not be too dispirited,
>> I think we started with some of the most difficult types...
>
> I was waiting for it :-).
>
>> I soppose what I meant is that POSIX defers to the C standard
>> in the cases where they overlap, and I'd expect that the set
>> of headers specified in the C standard and in POSIX might be the
>> same, but where they're not, I suspect the list of POSIX headers
>> would always be a superset of the C headers. So, just make a
>> single list of those headers, followed by 3 and 4 (merged)
>
> See updated comment in the page.
It looks good to me.
>> I suggest dropping the pages marked XX. The remaining can serve
>> as the (commonly used) exemplars of APIs that use this type.
>
> Done. I don't have experience enough to subjectively decide
> which ones should stay and which ones we should drop, so...
>
>> Okay, now I look closer at these lists. How have you determined them?
>
> I kept references to all APIs that use the type in the prototype.
>
> And for the headers list:
>
> I started reading the contents of the headers, but all I had seen
> did actually define the type, so I guessed that all the remaining
> grep appearances would also define the type. Clearly, I guessed wrong.
What I did was read the specifications of the .h files in the
standard, to see which ones said "shall define type XXX".
I think that's the way we should go, at least for types that
are in the standards.
>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
>> tell! I'm not sure how/if we want to represent that detail.
>
> I added a Notes section for that type. You like it?
Yes.
>> But size_t is not in this page (yet). Is it in your tree?
>
> Not yet. In my tree I didn't forget to comment it, though. As you can
> guess, It'll be the next type to document, and then ptrdiff_t.
>
>> Today I learned: size_t is in C99, but ssize_t is not!
[...]
I have no comments on the page. It looks great! I'm happy to
merge it now, unless you have something you want to change first.
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 19:24 ` Michael Kerrisk (man-pages)
@ 2020-09-16 19:51 ` Alejandro Colomar
2020-09-16 21:32 ` Thorsten Glaser
2020-09-17 10:27 ` Michael Kerrisk (man-pages)
0 siblings, 2 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-16 19:51 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
Hello Michael
On 2020-09-16 21:24, Michael Kerrisk (man-pages) wrote:
> Hello Alex,
>
> On 9/16/20 1:01 PM, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> Hi Michael,
>>
>> Changelog since v4:
>>
>> - Comment "See also" about yet undocumented size_t
>> - Simplify header ordering
>> - Curate See also
>> - Remove incorrect headers
>>
>>
>> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
>>> Okay. Time to nit pick:-). Do not be too dispirited,
>>> I think we started with some of the most difficult types...
>>
>> I was waiting for it :-).
>>
>>> I soppose what I meant is that POSIX defers to the C standard
>>> in the cases where they overlap, and I'd expect that the set
>>> of headers specified in the C standard and in POSIX might be the
>>> same, but where they're not, I suspect the list of POSIX headers
>>> would always be a superset of the C headers. So, just make a
>>> single list of those headers, followed by 3 and 4 (merged)
>>
>> See updated comment in the page.
>
> It looks good to me.
It still doesn't convince me.
Let's see how the standards define the types:
C has a ¿main? header that defines a type
(for example, for 'time_t' it would be <time.h>;
for 'size_t' it would be <stddef.h>),
and then there may be other headers that shall also define the type
(for example, 'size_t' is also defined in <stdio.h> and others).
POSIX does more or less the same:
It has a ¿main? header where the type is defined
(for 'time_t' it is <sys/types>,
which as you can it sometimes see differs from C),
and then there may be other headers that shall define the type.
I think we should differentiate those 1 or 2 headers
by putting them the first ones,
and then the rest could be merged together
(and maybe use a comma or something to differentiate them?).
Such as (for 'time_t'):
Include: <sys/types.h> or <time.h>, or <sched.h> or <sys/msg.h> or
<sys/select.h> or <sys/sem.h> or <sys/shm.h> or <sys/stat.h> or
<sys/time.h> or <utime.h>
However this still doesn't convince me...
I don't see a perfect way to express that.
Also, should we put a dot at the end of the includes?
Include: <sys/types.h> or <time.h>¿.?
>
>>> I suggest dropping the pages marked XX. The remaining can serve
>>> as the (commonly used) exemplars of APIs that use this type.
>>
>> Done. I don't have experience enough to subjectively decide
>> which ones should stay and which ones we should drop, so...
>>
>>> Okay, now I look closer at these lists. How have you determined them?
>>
>> I kept references to all APIs that use the type in the prototype.
>>
>> And for the headers list:
>>
>> I started reading the contents of the headers, but all I had seen
>> did actually define the type, so I guessed that all the remaining
>> grep appearances would also define the type. Clearly, I guessed wrong.
>
> What I did was read the specifications of the .h files in the
> standard, to see which ones said "shall define type XXX".
> I think that's the way we should go, at least for types that
> are in the standards.
Yeah, that's what I wanted to do.
But I was too lazy, and at some point stopped doing it :(
I'll do it from now on...
>
>>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
>>> tell! I'm not sure how/if we want to represent that detail.
>>
>> I added a Notes section for that type. You like it?
>
> Yes.
>
>>> But size_t is not in this page (yet). Is it in your tree?
>>
>> Not yet. In my tree I didn't forget to comment it, though. As you can
>> guess, It'll be the next type to document, and then ptrdiff_t.
>>
>>> Today I learned: size_t is in C99, but ssize_t is not!
>
> [...]
>
> I have no comments on the page. It looks great! I'm happy to
> merge it now, unless you have something you want to change first.
See above. That's the only thing that I don't fully like.
Also there are a few cosmetic fixes that I have in my tree already.
And, I trimmed a bit more the 'sigval' See also section.
Here's what I already applied to my tree. I will show you the diff as
it is very short so you have an idea off what is coming:
$ git diff types_draft_6
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 8fc827332..ffdcc9793 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -38,7 +38,7 @@ system_data_types \- overview of system data types
.\" 1) The header(s) that shall define the type
.\" according to the C standard,
.\" and
-.\" the header that shall define the type
+.\" the main header that shall define the type
.\" according to POSIX,
.\" in alphabetical order.
.\" 2) All other headers that shall define the type
(inline comment): Actually this still doesn't convince me, as I already
said.
@@ -81,11 +81,15 @@ Data passed with a signal.
Conforming to: POSIX.1-2001 and later.
.IP
See also:
-.BR rt_sigqueueinfo (2),
-.BR sigaction (2),
.BR pthread_sigqueue (3),
.BR sigqueue (3),
.BR sigevent (7)
+.\".IP
+.\"See also the
+.\".I sigevent
+.\"structure and the
+.\".I siginfo_t
+.\"type in this page.
.TP
.I ssize_t
.IP
Those 2 man pages aren't very related to this type,
and instead are related to 'siginfo_t', which contains a member of
type 'union sigval'.
So I prefer to refer to 'siginfo_t',
and there we will refer to those pages.
>
> Thanks,
>
> Michael
>
Thanks,
Alex
^ permalink raw reply related [flat|nested] 51+ messages in thread
* Re: [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 19:51 ` Alejandro Colomar
@ 2020-09-16 21:32 ` Thorsten Glaser
2020-09-17 9:23 ` Alejandro Colomar
2020-09-17 10:27 ` Michael Kerrisk (man-pages)
1 sibling, 1 reply; 51+ messages in thread
From: Thorsten Glaser @ 2020-09-16 21:32 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Michael Kerrisk (man-pages),
fweimer, linux-man, Andries.Brouwer, jwilk, libbsd
Alejandro Colomar dixit:
> POSIX does more or less the same:
> It has a ¿main? header where the type is defined
It does?
When I look at one of the headers, for example…
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html
… I see a number of types being defined, but the types don’t have
their own pages nor is described which is the “main” header (the same
goes for constants, e.g. NULL is defined by several headers).
Or is wording like…
The <stdlib.h> header shall define NULL as described in [10]<stddef.h>.
… where you get the notion of a “main header” from?
If so, where in the standard is this expectation documented?
Curious,
//mirabilos
--
“It is inappropriate to require that a time represented as
seconds since the Epoch precisely represent the number of
seconds between the referenced time and the Epoch.”
-- IEEE Std 1003.1b-1993 (POSIX) Section B.2.2.2
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 21:32 ` Thorsten Glaser
@ 2020-09-17 9:23 ` Alejandro Colomar
0 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 9:23 UTC (permalink / raw)
To: tg
Cc: Andries.Brouwer, colomar.6.4.3, fweimer, jwilk, libbsd,
linux-man, mtk.manpages
Hi Thorsten,
>> POSIX does more or less the same:
>> It has a ¿main? header where the type is defined
>
> It does?
It doesn't explicitly say so (AFACS; I didn't read the standard so deep).
But it hints so.
> When I look at one of the headers, for example…
> https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_time.h.html
> … I see a number of types being defined, but the types don’t have
> their own pages nor is described which is the “main” header (the same
> goes for constants, e.g. NULL is defined by several headers).
>
> Or is wording like…
>
> The <stdlib.h> header shall define NULL as described in
[10]<stddef.h>.
Yes, the POSIX standard defines types (and in general everything) in
one header. And then other headers refer the definition to that header,
with that wording you extracted.
The C standard does more or less the same thing:
Extracts from C18:
§ 6.5.3.3 (5)
"The value of the result of both operators is implementation-defined,
and its type (an unsignedinteger type) is size_t, defined
in <stddef.h> (and other headers)."
§ 7.19
" Common definitions <stddef.h>
The header <stddef.h> defines the following macros and declares the
following types. Some are also defined in other headers, as noted in
their respective subclauses.
The types are
[...]
size_t
which is the unsigned integer type of the result of the sizeof operator;
[...]
"
§ 7.21
" Input/output <stdio.h>
Introduction
The header <stdio.h> defines several macros, and declares three types
and many functions for performing input and output.
The types declared are size_t (described in 7.19);
[...]
"
> … where you get the notion of a “main header” from?
> If so, where in the standard is this expectation documented?
It's not that the standards document it, but in practice it is so.
The main point of differentiating those headers from the rest would be:
- It is likely that it's the lightest header you need to get that type
(usually most types are in <stddef.h> or <sys/types.h> or <sys/time.h>
or <stdint.h>, which are very light headers, and the rest of the
headers just need the types the many function prototypes, which
you don't need).
- If one wants to find the actual documentation for a type, it's easier
if you know which header you should look at, although I have to admit
that if you see any of the other headers, it clearly redirects you,
so not very important.
- If you just include any of the headers in the list for just getting
one type (e.g., you included <monetary.h> to get 'ssize_t'),
a reader of the code might spend a few minutes wondering why the hell
is that header included. It's ok if you need monetary for something
else, and you also happen to need 'ssize_t' and omit <sys/types.h>
because you happen to have the definition already, but including that
header just for 'ssize_t' would be a shooting offense, IMO.
Thanks,
Alex
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [RFC v6] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-16 19:51 ` Alejandro Colomar
2020-09-16 21:32 ` Thorsten Glaser
@ 2020-09-17 10:27 ` Michael Kerrisk (man-pages)
1 sibling, 0 replies; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-17 10:27 UTC (permalink / raw)
To: Alejandro Colomar
Cc: mtk.manpages, linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
Hello Alex,
On 9/16/20 9:51 PM, Alejandro Colomar wrote:
> Hello Michael
>
> On 2020-09-16 21:24, Michael Kerrisk (man-pages) wrote:
> > Hello Alex,
> >
> > On 9/16/20 1:01 PM, Alejandro Colomar wrote:
> >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> >> ---
> >>
> >> Hi Michael,
> >>
> >> Changelog since v4:
> >>
> >> - Comment "See also" about yet undocumented size_t
> >> - Simplify header ordering
> >> - Curate See also
> >> - Remove incorrect headers
> >>
> >>
> >> On 2020-09-15 23:30, Michael Kerrisk (man-pages) wrote:
> >>> Okay. Time to nit pick:-). Do not be too dispirited,
> >>> I think we started with some of the most difficult types...
> >>
> >> I was waiting for it :-).
> >>
> >>> I soppose what I meant is that POSIX defers to the C standard
> >>> in the cases where they overlap, and I'd expect that the set
> >>> of headers specified in the C standard and in POSIX might be the
> >>> same, but where they're not, I suspect the list of POSIX headers
> >>> would always be a superset of the C headers. So, just make a
> >>> single list of those headers, followed by 3 and 4 (merged)
> >>
> >> See updated comment in the page.
> >
> > It looks good to me.
>
> It still doesn't convince me.
>
> Let's see how the standards define the types:
>
> C has a ¿main? header that defines a type
> (for example, for 'time_t' it would be <time.h>;
> for 'size_t' it would be <stddef.h>),
> and then there may be other headers that shall also define the type
> (for example, 'size_t' is also defined in <stdio.h> and others).
>
> POSIX does more or less the same:
> It has a ¿main? header where the type is defined
> (for 'time_t' it is <sys/types>,
> which as you can it sometimes see differs from C),
> and then there may be other headers that shall define the type.
>
> I think we should differentiate those 1 or 2 headers
> by putting them the first ones,
> and then the rest could be merged together
> (and maybe use a comma or something to differentiate them?).
Maybe a semicolon (;), just because more visually obvious?
> Such as (for 'time_t'):
>
> Include: <sys/types.h> or <time.h>, or <sched.h> or <sys/msg.h> or
> <sys/select.h> or <sys/sem.h> or <sys/shm.h> or <sys/stat.h> or
> <sys/time.h> or <utime.h>
>
> However this still doesn't convince me...
> I don't see a perfect way to express that.
Maybe not perfect, but I don't think we have to come up with
the perfect solution (yet). I think things are okay as you
propose them currently.
> Also, should we put a dot at the end of the includes?
Yes, perhaps a little tidier.
>
> Include: <sys/types.h> or <time.h>¿.?
[...]
> >>> <sched.h> only defines time_t since POSIX.1-2008, as far as I can
> >>> tell! I'm not sure how/if we want to represent that detail.
> >>
> >> I added a Notes section for that type. You like it?
> >
> > Yes.
> >
> >>> But size_t is not in this page (yet). Is it in your tree?
> >>
> >> Not yet. In my tree I didn't forget to comment it, though. As you can
> >> guess, It'll be the next type to document, and then ptrdiff_t.
> >>
> >>> Today I learned: size_t is in C99, but ssize_t is not!
> >
> > [...]
> >
> > I have no comments on the page. It looks great! I'm happy to
> > merge it now, unless you have something you want to change first.
>
> See above. That's the only thing that I don't fully like.
>
> Also there are a few cosmetic fixes that I have in my tree already.
>
> And, I trimmed a bit more the 'sigval' See also section.
>
> Here's what I already applied to my tree. I will show you the diff as
> it is very short so you have an idea off what is coming:
>
> $ git diff types_draft_6
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 8fc827332..ffdcc9793 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -38,7 +38,7 @@ system_data_types \- overview of system data types
> .\" 1) The header(s) that shall define the type
> .\" according to the C standard,
> .\" and
> -.\" the header that shall define the type
> +.\" the main header that shall define the type
> .\" according to POSIX,
> .\" in alphabetical order.
> .\" 2) All other headers that shall define the type
>
> (inline comment): Actually this still doesn't convince me, as I already
> said.
>
> @@ -81,11 +81,15 @@ Data passed with a signal.
> Conforming to: POSIX.1-2001 and later.
> .IP
> See also:
> -.BR rt_sigqueueinfo (2),
> -.BR sigaction (2),
> .BR pthread_sigqueue (3),
> .BR sigqueue (3),
> .BR sigevent (7)
> +.\".IP
> +.\"See also the
> +.\".I sigevent
> +.\"structure and the
> +.\".I siginfo_t
> +.\"type in this page.
> .TP
> .I ssize_t
> .IP
>
> Those 2 man pages aren't very related to this type,
> and instead are related to 'siginfo_t', which contains a member of
> type 'union sigval'.
> So I prefer to refer to 'siginfo_t',
> and there we will refer to those pages.
That sounds okay to me. I presume you plan to uncomment the
lines above that mention sigevent and siginfo_t, right?
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* [PATCH v7 0/8] Document system data types
2020-09-14 10:22 ` Alejandro Colomar
` (4 preceding siblings ...)
2020-09-16 11:01 ` [RFC v6] " Alejandro Colomar
@ 2020-09-17 10:42 ` Alejandro Colomar
2020-09-17 21:05 ` Michael Kerrisk (man-pages)
2020-09-17 10:42 ` [PATCH v7 1/8] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
` (7 subsequent siblings)
13 siblings, 1 reply; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:42 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Hi Michael,
I'm proud enough of the result to commit it now :-}.
Changelog since v6:
- ffix
- wsfix
- wfix
- Change ordering of headers (no actual change)
- Curate See also (sigval)
- Add NOTES section (about structures)
On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
> That sounds okay to me. I presume you plan to uncomment the
> lines above that mention sigevent and siginfo_t, right?
Right.
Cheers,
Alex
Alejandro Colomar (8):
system_data_types.7: Document types: sigval, ssize_t, suseconds_t,
time_t, timer_t, timespec, timeval
sigval.3: Add link page
ssize_t.3: Add link page
suseconds_t.3: Add link page
time_t.3: Add link page
timer_t.3: Add link page
timespec.3: Add link page
timeval.3: Add link page
man3/sigval.3 | 1 +
man3/ssize_t.3 | 1 +
man3/suseconds_t.3 | 1 +
man3/time_t.3 | 1 +
man3/timer_t.3 | 1 +
man3/timespec.3 | 1 +
man3/timeval.3 | 1 +
man7/system_data_types.7 | 280 +++++++++++++++++++++++++++++++++++++++
8 files changed, 287 insertions(+)
create mode 100644 man3/sigval.3
create mode 100644 man3/ssize_t.3
create mode 100644 man3/suseconds_t.3
create mode 100644 man3/time_t.3
create mode 100644 man3/timer_t.3
create mode 100644 man3/timespec.3
create mode 100644 man3/timeval.3
create mode 100644 man7/system_data_types.7
--
2.28.0
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [PATCH v7 0/8] Document system data types
2020-09-17 10:42 ` [PATCH v7 0/8] Document system data types Alejandro Colomar
@ 2020-09-17 21:05 ` Michael Kerrisk (man-pages)
2020-09-17 21:16 ` Alejandro Colomar
0 siblings, 1 reply; 51+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-09-17 21:05 UTC (permalink / raw)
To: Alejandro Colomar
Cc: mtk.manpages, linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
Hello Alex
On 9/17/20 12:42 PM, Alejandro Colomar wrote:
> Hi Michael,
>
> I'm proud enough of the result to commit it now :-}.
And fair enough! It's been a great piece of work!
> Changelog since v6:
>
> - ffix
> - wsfix
> - wfix
> - Change ordering of headers (no actual change)
> - Curate See also (sigval)
> - Add NOTES section (about structures)
I've merged all of the patches. However, I then squashed
all the patches adding the links into a single commit.
> On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
>> That sounds okay to me. I presume you plan to uncomment the
>> lines above that mention sigevent and siginfo_t, right?
>
> Right.
Did you actually do that.? It seems not. Wanna send me
a patch?
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 51+ messages in thread
* Re: [PATCH v7 0/8] Document system data types
2020-09-17 21:05 ` Michael Kerrisk (man-pages)
@ 2020-09-17 21:16 ` Alejandro Colomar
0 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 21:16 UTC (permalink / raw)
To: Michael Kerrisk (man-pages)
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer
On 2020-09-17 23:05, Michael Kerrisk (man-pages) wrote:
> Hello Alex
>
> On 9/17/20 12:42 PM, Alejandro Colomar wrote:
>> Hi Michael,
>>
>> I'm proud enough of the result to commit it now :-}.
>
> And fair enough! It's been a great piece of work!
Thank you, Michael!
>
>> Changelog since v6:
>>
>> - ffix
>> - wsfix
>> - wfix
>> - Change ordering of headers (no actual change)
>> - Curate See also (sigval)
>> - Add NOTES section (about structures)
>
> I've merged all of the patches. However, I then squashed
> all the patches adding the links into a single commit.
That's fine.
>
>> On 2020-09-17 12:27, Michael Kerrisk (man-pages) wrote:
>>> That sounds okay to me. I presume you plan to uncomment the
>>> lines above that mention sigevent and siginfo_t, right?
>>
>> Right.
>
> Did you actually do that.? It seems not. Wanna send me
> a patch?
Oh, I meant that I plan to uncomment those lines when we document those
other types (to not have broken references).
>
> Thanks,
>
> Michael
>
>
Cheers,
Alex.
^ permalink raw reply [flat|nested] 51+ messages in thread
* [PATCH v7 1/8] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval
2020-09-14 10:22 ` Alejandro Colomar
` (5 preceding siblings ...)
2020-09-17 10:42 ` [PATCH v7 0/8] Document system data types Alejandro Colomar
@ 2020-09-17 10:42 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 2/8] sigval.3: Add link page Alejandro Colomar
` (6 subsequent siblings)
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:42 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man7/system_data_types.7 | 280 +++++++++++++++++++++++++++++++++++++++
1 file changed, 280 insertions(+)
create mode 100644 man7/system_data_types.7
diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
new file mode 100644
index 000000000..8072f739b
--- /dev/null
+++ b/man7/system_data_types.7
@@ -0,0 +1,280 @@
+.\" Copyright (c) 2020 by Alejandro Colomar <colomar.6.4.3@gmail.com>
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date. The author(s) assume no
+.\" responsibility for errors or omissions, or for damages resulting from
+.\" the use of the information contained herein. The author(s) may not
+.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by
+.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.\"
+.TH SYSTEM_DATA_TYPES 7 2020-09-13 "Linux" "Linux Programmer's Manual"
+.SH NAME
+system_data_types \- overview of system data types
+.SH DESCRIPTION
+.\" TODO:
+.\" * Add types
+.\" * Curate "See also"
+.\" Layout:
+.\" A list of type names (the struct/union keyword will be omitted).
+.\" Each entry will have the following parts:
+.\" * Include
+.\" The headers will be in the following order:
+.\" 1) The main header that shall define the type
+.\" according to the C Standard,
+.\" and
+.\" the main header that shall define the type
+.\" according to POSIX,
+.\" in alphabetical order.
+.\" ;
+.\" 2) All other headers that shall define the type
+.\" as described in the previous header(s)
+.\" according to the C Standard or POSIX,
+.\" in alphabetical order.
+.\" *) All headers that define the type
+.\" *if* the type is not defined by C nor POSIX,
+.\" in alphabetical order.
+.\"
+.\" * Definition (no "Definition" header)
+.\" Only struct/union types will have definition;
+.\" typedefs will remain opaque.
+.\"
+.\" * Description (no "Description" header)
+.\" A few lines describing the type.
+.\"
+.\" * Conforming to
+.\" Format: CXY and later; POSIX.1-XXXX and later.
+.\" Forget about pre-C99 C standards (i.e., C89/C90)
+.\"
+.\" * Notes (optional)
+.\"
+.\" * See also
+.TP
+.I sigval
+.IP
+Include:
+.IR <signal.h> .
+.IP
+.EX
+union sigval {
+ int sigval_int; /* Integer value */
+ void *sigval_ptr; /* Pointer value */
+};
+.EE
+.IP
+Data passed with a signal.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR pthread_sigqueue (3),
+.BR sigqueue (3),
+.BR sigevent (7)
+.\".IP
+.\"See also the
+.\".I sigevent
+.\"structure and the
+.\".I siginfo_t
+.\"type in this page.
+.TP
+.I ssize_t
+.IP
+Include:
+.IR <sys/types.h> ;
+or
+.I <aio.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <stdio.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.IR <unistd.h> .
+.IP
+Used for a count of bytes or an error indication.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1,
+.BR SSIZE_MAX ].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR read (2),
+.BR readlink (2),
+.BR readv (2),
+.BR recv (2),
+.BR send (2),
+.BR write (2)
+.\".IP FIXME: When size_t is added, uncomment
+.\"See also the
+.\".I size_t
+.\"type in this page.
+.TP
+.I suseconds_t
+.IP
+Include:
+.IR <sys/types.h> ;
+or
+.I <sys/select.h>
+or
+.IR <sys/time.h> .
+.IP
+Used for time in microseconds.
+According to POSIX, it shall be a signed integer type
+capable of storing values at least in the range [-1, 1000000].
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also the
+.I timeval
+structure in this page.
+.TP
+.I time_t
+.IP
+Include:
+.I <sys/types.h>
+or
+.IR <time.h> ;
+or
+.I <sched.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/select.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/stat.h>
+or
+.I <sys/time.h>
+or
+.IR <utime.h> .
+.IP
+Used for time in seconds.
+According to POSIX, it shall be an integer type.
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+Notes:
+.I <sched.h>
+defines
+.I time_t
+since POSIX.1-2008.
+.IP
+See also:
+.BR stime (2),
+.BR time (2),
+.BR ctime (3),
+.BR difftime (3)
+.TP
+.I timer_t
+.IP
+Include:
+.IR <sys/types.h> ;
+or
+.IR <time.h> .
+.IP
+Used for timer ID returned by
+.BR timer_create (2).
+According to POSIX,
+there are no defined comparison or assignment operators for this type.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR timer_create (2),
+.BR timer_delete (2),
+.BR timer_getoverrun (2),
+.BR timer_settime (2)
+.TP
+.I timespec
+.IP
+Include:
+.IR <time.h> ;
+or
+.I <aio.h>
+or
+.I <mqueue.h>
+or
+.I <sched.h>
+or
+.I <signal.h>
+or
+.I <sys/select.h>
+or
+.IR <sys/stat.h> .
+.IP
+.EX
+struct timespec {
+ time_t tv_sec; /* Seconds */
+ long tv_nsec; /* Nanoseconds */
+};
+.EE
+.IP
+Describes times in seconds and nanoseconds.
+.IP
+Conforming to: C11 and later; POSIX.1-2001 and later.
+.IP
+See also:
+.BR clock_gettime (2),
+.BR clock_nanosleep (2),
+.BR nanosleep (2),
+.BR timerfd_gettime (2),
+.BR timer_gettime (2)
+.TP
+.I timeval
+.IP
+Include:
+.IR <sys/time.h> ;
+or
+.I <sys/resource.h>
+or
+.I <sys/select.h>
+or
+.IR <utmpx.h> .
+.IP
+.EX
+struct timeval {
+ time_t tv_sec; /* Seconds */
+ suseconds_t tv_usec; /* Microseconds */
+};
+.EE
+.IP
+Describes times in seconds and microseconds.
+.IP
+Conforming to: POSIX.1-2001 and later.
+.IP
+See also:
+.BR gettimeofday (2),
+.BR select (2),
+.BR utimes (2),
+.BR adjtime (3),
+.BR futimes (3),
+.BR timeradd (3)
+.SH NOTES
+The structures described in this manual page shall contain,
+at least, the members shown in their definition, in no particular order.
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 2/8] sigval.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (6 preceding siblings ...)
2020-09-17 10:42 ` [PATCH v7 1/8] system_data_types.7: Document types: sigval, ssize_t, suseconds_t, time_t, timer_t, timespec, timeval Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 3/8] ssize_t.3: " Alejandro Colomar
` (5 subsequent siblings)
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/sigval.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/sigval.3
diff --git a/man3/sigval.3 b/man3/sigval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/sigval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 3/8] ssize_t.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (7 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 2/8] sigval.3: Add link page Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 4/8] suseconds_t.3: " Alejandro Colomar
` (4 subsequent siblings)
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/ssize_t.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/ssize_t.3
diff --git a/man3/ssize_t.3 b/man3/ssize_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/ssize_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 4/8] suseconds_t.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (8 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 3/8] ssize_t.3: " Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 5/8] time_t.3: " Alejandro Colomar
` (3 subsequent siblings)
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/suseconds_t.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/suseconds_t.3
diff --git a/man3/suseconds_t.3 b/man3/suseconds_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/suseconds_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 5/8] time_t.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (9 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 4/8] suseconds_t.3: " Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 6/8] timer_t.3: " Alejandro Colomar
` (2 subsequent siblings)
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/time_t.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/time_t.3
diff --git a/man3/time_t.3 b/man3/time_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/time_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 6/8] timer_t.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (10 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 5/8] time_t.3: " Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 7/8] timespec.3: " Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 8/8] timeval.3: " Alejandro Colomar
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/timer_t.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/timer_t.3
diff --git a/man3/timer_t.3 b/man3/timer_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timer_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 7/8] timespec.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (11 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 6/8] timer_t.3: " Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
2020-09-17 10:43 ` [PATCH v7 8/8] timeval.3: " Alejandro Colomar
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/timespec.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/timespec.3
diff --git a/man3/timespec.3 b/man3/timespec.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timespec.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread
* [PATCH v7 8/8] timeval.3: Add link page
2020-09-14 10:22 ` Alejandro Colomar
` (12 preceding siblings ...)
2020-09-17 10:43 ` [PATCH v7 7/8] timespec.3: " Alejandro Colomar
@ 2020-09-17 10:43 ` Alejandro Colomar
13 siblings, 0 replies; 51+ messages in thread
From: Alejandro Colomar @ 2020-09-17 10:43 UTC (permalink / raw)
To: mtk.manpages
Cc: linux-man, tg, fweimer, jwilk, libbsd, Andries.Brouwer,
Alejandro Colomar
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
man3/timeval.3 | 1 +
1 file changed, 1 insertion(+)
create mode 100644 man3/timeval.3
diff --git a/man3/timeval.3 b/man3/timeval.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/timeval.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
--
2.28.0
^ permalink raw reply related [flat|nested] 51+ messages in thread