[PATCH 0/2] Document size_t

[PATCH 0/2] Document size_t

[Alejandro Colomar]

Hi Michael,

I documented size_t.

There is a minor thing with this patch:
It references to a not yet documented type: ptrdiff_t
It's just that I'm going to document it next...

In the See also, I just put a few important pages.
Maybe you want to include a few more.

Thanks,

Alex


Alejandro Colomar (2):
  system_data_types.7: Document size_t
  size_t.3: New link to new documented type in system_data_types(7)

 man3/size_t.3            |   1 +
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 100 insertions(+), 4 deletions(-)
 create mode 100644 man3/size_t.3

-- 
2.28.0

[PATCH 1/2] system_data_types.7: Document size_t

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 84fea85b9..041e7e243 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -92,6 +92,101 @@ See also:
 .\".I siginfo_t
 .\"type in this page.
 .TP
+.I size_t
+.IP
+Include:
+.I <stddef.h>
+or
+.IR <sys/types.h> ;
+or
+.I <aio.h>
+or
+.I <glob.h>
+or
+.I <grp.h>
+or
+.I <iconv.h>
+or
+.I <monetary.h>
+or
+.I <mqueue.h>
+or
+.I <ndbm.h>
+or
+.I <pwd.h>
+or
+.I <regex.h>
+or
+.I <search.h>
+or
+.I <signal.h>
+or
+.I <stdio.h>
+or
+.I <stdlib.h>
+or
+.I <string.h>
+or
+.I <strings.h>
+or
+.I <sys/mman.h>
+or
+.I <sys/msg.h>
+or
+.I <sys/sem.h>
+or
+.I <sys/shm.h>
+or
+.I <sys/socket.h>
+or
+.I <sys/uio.h>
+or
+.I <time.h>
+or
+.I <unistd.h>
+or
+.I <wchar.h>
+or
+.IR <wordexp.h> .
+.IP
+Used for a count of bytes.  It is the result of the
+.I sizeof
+operator.
+According to the C language standard,
+it shall be an unsigned integer type
+capable of storing values in the range [0,
+.BR SIZE_MAX ].
+.IP
+Conforming to: C99 and later; POSIX.1-2001 and later.
+.IP
+Notes:
+.IR <aio.h> ,
+.IR <glob.h> ,
+.IR <grp.h> ,
+.IR <iconv.h> ,
+.IR <mqueue.h> ,
+.IR <pwd.h> ,
+.IR <signal.h>
+and
+.IR <sys/socket.h>
+define
+.I size_t
+since POSIX.1-2008.
+.IP
+See also:
+.BR fread (3),
+.BR fwrite (3),
+.BR memcmp (3),
+.BR memcpy (3),
+.BR memset (3),
+.BR offsetof (3)
+.IP
+See also the
+.I ssize_t
+and
+.I ptrdiff_t
+types in this page.
+.TP
 .I ssize_t
 .IP
 Include:
@@ -127,10 +222,10 @@ See also:
 .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.
+.IP
+See also the
+.I size_t
+type in this page.
 .TP
 .I suseconds_t
 .IP
-- 
2.28.0

[PATCH 2/2] size_t.3: New link to new documented type in system_data_types(7)

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---
 man3/size_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/size_t.3

diff --git a/man3/size_t.3 b/man3/size_t.3
new file mode 100644
index 000000000..db50c0f09
--- /dev/null
+++ b/man3/size_t.3
@@ -0,0 +1 @@
+.so man7/system_data_types.7
-- 
2.28.0

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Florian Weimer]

* Alejandro Colomar via Libc-alpha:

> +Used for a count of bytes.  It is the result of the
> +.I sizeof
> +operator.
> +According to the C language standard,
> +it shall be an unsigned integer type
> +capable of storing values in the range [0,
> +.BR SIZE_MAX ].

Thanks for working on this.

Maybe add that this commonly maps to unsigned int or unsigned long, and
that the length modifier for printf and scanf is z, commently used as
%zu or %zx (%zd is for ssize_t).

Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Alejandro Colomar]

Hello Florian,

On 2020-09-18 16:34, Florian Weimer wrote:
 > * Alejandro Colomar via Libc-alpha:
 >
 >> +Used for a count of bytes.  It is the result of the
 >> +.I sizeof
 >> +operator.
 >> +According to the C language standard,
 >> +it shall be an unsigned integer type
 >> +capable of storing values in the range [0,
 >> +.BR SIZE_MAX ].
 >
 > Thanks for working on this.

:-)

 > Maybe add that this commonly maps to unsigned int or unsigned long, and

I thought the same in the beginning,
but then Michael convinced me to not do it.

On 2020-09-13 22:20, Michael Kerrisk (man-pages) wrote:
 >>>> Is it a 32-bit or 64-bit or may vary? Is it signed or unsigned?
 >>> POSIX doesn't specify, I think.>
 >>> One other thing the page should show of course is definition of the
 >>> structure types.
 >> Yes.
 >>
 >>
 >>      timer_t     <time.h> or <sys/types.h>
 >>          POSIX timer ID.
 >>
 >>          typedef void *timer_t;
 > Here I would *not* show these kinds of typedefs. The point is
 > that these types should be treated as being somewhat unknown
 > (e.g., for casts in printf()). Here, I think instead maybe we
 > just have a statement that POSIX makes no specific requirements
 > for the representation of this type.

I think I prefer to leave it opaque, showing only the requirements
that POSIX and C make.

There's really not much gain (basically uint and ulong cover most of the
possibilities; and still it's not a guarantee).
And readers might write non-portable code because of reading that.

On 2020-09-18 16:34, Florian Weimer wrote:
 > that the length modifier for printf and scanf is z, commently used as
 > %zu or %zx (%zd is for ssize_t).

Good idea.

Would you prefer that, or just refer to printf(3) in See also?.

 >
 > Florian
 >

Thanks,

Alex

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Florian Weimer]

* Alejandro Colomar:

> I think I prefer to leave it opaque, showing only the requirements
> that POSIX and C make.
>
> There's really not much gain (basically uint and ulong cover most of the
> possibilities; and still it's not a guarantee).
> And readers might write non-portable code because of reading that.

My idea was it that it stresses that you have to use %zu in order to be
portable.  %lu works almost everywhere, so that's any easy mistake to
make because it still leads to -Werror build failures on s390 (31-bit).
Likewise for %ld for ptrdiff_t, it should be %td.

> On 2020-09-18 16:34, Florian Weimer wrote:
>> that the length modifier for printf and scanf is z, commently used as
>> %zu or %zx (%zd is for ssize_t).
>
> Good idea.
>
> Would you prefer that, or just refer to printf(3) in See also?.

I think it makes sense to spell out %zu and %zx explicitly.

Thanks,
Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Paul Eggert]

On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
> the length modifier for printf and scanf is z, commently used as
> %zu or %zx (%zd is for ssize_t).

While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work, 
as ssize_t might not have the same width as size_t. (If memory serves this goes 
back to the bad old days when size_t was 64 bits and ssize_t 32 bits on some 
platforms.) So if we document %zd we should say it's a GNU extension to POSIX, 
or something like that.

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Florian Weimer]

* Paul Eggert:

> On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
>> the length modifier for printf and scanf is z, commently used as
>> %zu or %zx (%zd is for ssize_t).
>
> While %zd works for ssize_t in glibc, POSIX doesn't guarantee that
> it'll work, as ssize_t might not have the same width as size_t. (If
> memory serves this goes back to the bad old days when size_t was 64
> bits and ssize_t 32 bits on some platforms.) So if we document %zd we
> should say it's a GNU extension to POSIX, or something like that.

I didn't know that.  It's a good suggestion, thanks.

Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH 0/2] Document size_t

[Michael Kerrisk (man-pages)]

On 9/18/20 1:27 PM, Alejandro Colomar wrote:
> Hi Michael,
> 
> I documented size_t.
> 
> There is a minor thing with this patch:
> It references to a not yet documented type: ptrdiff_t
> It's just that I'm going to document it next...

No problem.

I realize you may want to add some pieces, after the comments from 
Florian and Paul, but this patch series is good for merging as is, and 
I'm merging it. You can send a follow-up patch mentioning %zd and %zu
when ready.


> In the See also, I just put a few important pages.
> Maybe you want to include a few more.

I added read(2) and write(2).

Thanks,

Michael



> Alejandro Colomar (2):
>   system_data_types.7: Document size_t
>   size_t.3: New link to new documented type in system_data_types(7)
> 
>  man3/size_t.3            |   1 +
>  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>  2 files changed, 100 insertions(+), 4 deletions(-)
>  create mode 100644 man3/size_t.3
> 


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

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Michael Kerrisk (man-pages)]

On 9/18/20 1:27 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Merged.

Thanks,

Michael

> ---
>  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 99 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 84fea85b9..041e7e243 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -92,6 +92,101 @@ See also:
>  .\".I siginfo_t
>  .\"type in this page.
>  .TP
> +.I size_t
> +.IP
> +Include:
> +.I <stddef.h>
> +or
> +.IR <sys/types.h> ;
> +or
> +.I <aio.h>
> +or
> +.I <glob.h>
> +or
> +.I <grp.h>
> +or
> +.I <iconv.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>
> +or
> +.I <ndbm.h>
> +or
> +.I <pwd.h>
> +or
> +.I <regex.h>
> +or
> +.I <search.h>
> +or
> +.I <signal.h>
> +or
> +.I <stdio.h>
> +or
> +.I <stdlib.h>
> +or
> +.I <string.h>
> +or
> +.I <strings.h>
> +or
> +.I <sys/mman.h>
> +or
> +.I <sys/msg.h>
> +or
> +.I <sys/sem.h>
> +or
> +.I <sys/shm.h>
> +or
> +.I <sys/socket.h>
> +or
> +.I <sys/uio.h>
> +or
> +.I <time.h>
> +or
> +.I <unistd.h>
> +or
> +.I <wchar.h>
> +or
> +.IR <wordexp.h> .
> +.IP
> +Used for a count of bytes.  It is the result of the
> +.I sizeof
> +operator.
> +According to the C language standard,
> +it shall be an unsigned integer type
> +capable of storing values in the range [0,
> +.BR SIZE_MAX ].
> +.IP
> +Conforming to: C99 and later; POSIX.1-2001 and later.
> +.IP
> +Notes:
> +.IR <aio.h> ,
> +.IR <glob.h> ,
> +.IR <grp.h> ,
> +.IR <iconv.h> ,
> +.IR <mqueue.h> ,
> +.IR <pwd.h> ,
> +.IR <signal.h>
> +and
> +.IR <sys/socket.h>
> +define
> +.I size_t
> +since POSIX.1-2008.
> +.IP
> +See also:
> +.BR fread (3),
> +.BR fwrite (3),
> +.BR memcmp (3),
> +.BR memcpy (3),
> +.BR memset (3),
> +.BR offsetof (3)
> +.IP
> +See also the
> +.I ssize_t
> +and
> +.I ptrdiff_t
> +types in this page.
> +.TP
>  .I ssize_t
>  .IP
>  Include:
> @@ -127,10 +222,10 @@ See also:
>  .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.
> +.IP
> +See also the
> +.I size_t
> +type in this page.
>  .TP
>  .I suseconds_t
>  .IP
> 


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

Re: [PATCH 2/2] size_t.3: New link to new documented type in system_data_types(7)

[Michael Kerrisk (man-pages)]

On 9/18/20 1:27 PM, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>

Merged.

Thanks,

Michael

> ---
>  man3/size_t.3 | 1 +
>  1 file changed, 1 insertion(+)
>  create mode 100644 man3/size_t.3
> 
> diff --git a/man3/size_t.3 b/man3/size_t.3
> new file mode 100644
> index 000000000..db50c0f09
> --- /dev/null
> +++ b/man3/size_t.3
> @@ -0,0 +1 @@
> +.so man7/system_data_types.7
> 


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

Re: [PATCH 0/2] Document size_t

[Alejandro Colomar]

On 2020-09-18 22:13, Michael Kerrisk (man-pages) wrote:
> I realize you may want to add some pieces, after the comments from
> Florian and Paul, but this patch series is good for merging as is, and
> I'm merging it. You can send a follow-up patch mentioning %zd and %zu
> when ready.

Yes, I've started a new thread; I also thought this patch was already 
complete.

> 
> 
>> In the See also, I just put a few important pages.
>> Maybe you want to include a few more.
> 
> I added read(2) and write(2).

Fine.  I didn't remember their arguments are 'size_t'.  I was under the 
idea that they used 'ssize_t'.

Thanks,

Alex

Re: [PATCH 0/2] Document size_t

[Florian Weimer]

* Alejandro Colomar:

>>> In the See also, I just put a few important pages.
>>> Maybe you want to include a few more.
>> I added read(2) and write(2).
>
> Fine.  I didn't remember their arguments are 'size_t'.  I was under
> the idea that they used 'ssize_t'.

The outliers are readv and writev, which use int for the array length
argument (at least in POSIX).

Thanks,
Florian
-- 
Red Hat GmbH, https://de.redhat.com/ , Registered seat: Grasbrunn,
Commercial register: Amtsgericht Muenchen, HRB 153243,
Managing Directors: Charles Cachera, Brian Klemm, Laurie Krebs, Michael O'Neill

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Dave Martin]

On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote:
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
>  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>  1 file changed, 99 insertions(+), 4 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 84fea85b9..041e7e243 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7

The distinction might not be worth highlighting here, but types like
size_t are a bit special in that they come from the C standards and
assumptions about them are really built into the compiler.

The system can define its own size_t, but it had better be equivalent
to the compiler's definition otherwise bad things will
happen...


> @@ -92,6 +92,101 @@ See also:
>  .\".I siginfo_t
>  .\"type in this page.
>  .TP
> +.I size_t
> +.IP
> +Include:
> +.I <stddef.h>
> +or

Where does this arbitrary-looking list of headers come from?

From the C standards at least, <stddef.h> seems to be the canonical
header for this type.


> +.IR <sys/types.h> ;
> +or
> +.I <aio.h>
> +or
> +.I <glob.h>
> +or
> +.I <grp.h>
> +or
> +.I <iconv.h>
> +or
> +.I <monetary.h>
> +or
> +.I <mqueue.h>

[...]

Cheers
---Dave

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Alejandro Colomar]

Hi Dave,

On 2020-09-28 15:41, Dave Martin wrote:
> On Fri, Sep 18, 2020 at 01:27:55PM +0200, Alejandro Colomar wrote:
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>   man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
>>   1 file changed, 99 insertions(+), 4 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 84fea85b9..041e7e243 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
> 
> The distinction might not be worth highlighting here, but types like
> size_t are a bit special in that they come from the C standards and
> assumptions about them are really built into the compiler.
> 
> The system can define its own size_t, but it had better be equivalent
> to the compiler's definition otherwise bad things will
> happen...
> 
> 
>> @@ -92,6 +92,101 @@ See also:
>>   .\".I siginfo_t
>>   .\"type in this page.
>>   .TP
>> +.I size_t
>> +.IP
>> +Include:
>> +.I <stddef.h>
>> +or
> 
> Where does this arbitrary-looking list of headers come from?

There are two parts:  left to the ';', and right to the ';'.

Left: The canonical C standard header, and the canonical POSIX header, 
in alphabetical order.

Right: All other headers that shall define the header, according to 
either the C or the POSIX standards, in alphabetical order.

Cheers,

Alex

> 
>  From the C standards at least, <stddef.h> seems to be the canonical
> header for this type.
> 
> 
>> +.IR <sys/types.h> ;
>> +or
>> +.I <aio.h>
>> +or
>> +.I <glob.h>
>> +or
>> +.I <grp.h>
>> +or
>> +.I <iconv.h>
>> +or
>> +.I <monetary.h>
>> +or
>> +.I <mqueue.h>
> 
> [...]
> 
> Cheers
> ---Dave
> 

Re: [PATCH 1/2] system_data_types.7: Document size_t

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 934 bytes --]

Hi, Alex!

At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > Where does this arbitrary-looking list of headers come from?
> 
> There are two parts:  left to the ';', and right to the ';'.
> 
> Left: The canonical C standard header, and the canonical POSIX header,
> in alphabetical order.
> 
> Right: All other headers that shall define the header, according to
> either the C or the POSIX standards, in alphabetical order.

That's not a bad scheme but it is not inferable from the current man
page text; I almost commented on the inconsistency in one of my earlier
messages but deemed it out of scope.  Please document it, perhaps in an
introductory paragraph at the top of the Description section.

Or, you could spend a word to do the same work:

gid_t   Include: <sys/types.h>.  Alternatively, <grp.h>, <pwd.h>,
<signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>.

Regards,
Branden

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Dave Martin]

On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
> Hi, Alex!
> 
> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > > Where does this arbitrary-looking list of headers come from?
> > 
> > There are two parts:  left to the ';', and right to the ';'.
> > 
> > Left: The canonical C standard header, and the canonical POSIX header,
> > in alphabetical order.
> > 
> > Right: All other headers that shall define the header, according to
> > either the C or the POSIX standards, in alphabetical order.

To clarify, does POSIX _guarantee_ that all of those headers define this
type?  (I admit I'm too lazy to search through the POSIX standard for an
answer to this).

If not, this list would serve only to legitimise bad habits and it may
be better to leave it out.


> That's not a bad scheme but it is not inferable from the current man
> page text; I almost commented on the inconsistency in one of my earlier
> messages but deemed it out of scope.  Please document it, perhaps in an
> introductory paragraph at the top of the Description section.

Ack, I think it would be better to state this explicity rather than
having some terse syntax that people need to understand.


IIUC, a program intended to be fully portable between C implementations
must include <stddef.h>, not rely on one of the others.

(In practice it seems reasonable to include any header that is specified
to declare types or function prototypes that themselves require a
definition of size_t, but this is awkward to describe, and not explicit
in the standard.)

[...]

Cheers
---Dave

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Alejandro Colomar]

Hi Branden,

On 2020-09-28 15:55, G. Branden Robinson wrote:
 > Hi, Alex!
 >
 > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
 >>> Where does this arbitrary-looking list of headers come from?
 >>
 >> There are two parts:  left to the ';', and right to the ';'.
 >>
 >> Left: The canonical C standard header, and the canonical POSIX header,
 >> in alphabetical order.
 >>
 >> Right: All other headers that shall define the header, according to
 >> either the C or the POSIX standards, in alphabetical order.
 >
 > That's not a bad scheme but it is not inferable from the current man
 > page text; I almost commented on the inconsistency in one of my earlier
 > messages but deemed it out of scope.  Please document it, perhaps in an
 > introductory paragraph at the top of the Description section.
 >
 > Or, you could spend a word to do the same work:
 >
 > gid_t   Include: <sys/types.h>.  Alternatively, <grp.h>, <pwd.h>,
 > <signal.h>, <stropts.h>, <sys/ipc.h>, <sys/stat.h>, or <unistd.h>.
 >
 > Regards,
 > Branden
 >
Thanks!

We talked about it. I wasn't convinced by my scheme,
but we couldn't come up with a better solution, so we kept that.

For the readers, it wasn't clear, but for the developers of the page,
I wrote a comment at the beginning of the page,
which I hope was clear enough:

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

But I like very much your "Alternatively, " wording.  I'll use it!

Thanks,

Alex

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Alejandro Colomar]

Hi Dave!

On 2020-09-28 16:15, Dave Martin wrote:
> On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
>> Hi, Alex!
>>
>> At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
>>>> Where does this arbitrary-looking list of headers come from?
>>>
>>> There are two parts:  left to the ';', and right to the ';'.
>>>
>>> Left: The canonical C standard header, and the canonical POSIX header,
>>> in alphabetical order.
>>>
>>> Right: All other headers that shall define the header, according to
>>> either the C or the POSIX standards, in alphabetical order.
> 
> To clarify, does POSIX _guarantee_ that all of those headers define this
> type?  (I admit I'm too lazy to search through the POSIX standard for an
> answer to this).

Yes, POSIX does guarantee that all those headers define the type.

> 
> If not, this list would serve only to legitimise bad habits and it may
> be better to leave it out.
> 
> 
>> That's not a bad scheme but it is not inferable from the current man
>> page text; I almost commented on the inconsistency in one of my earlier
>> messages but deemed it out of scope.  Please document it, perhaps in an
>> introductory paragraph at the top of the Description section.
> 
> Ack, I think it would be better to state this explicity rather than
> having some terse syntax that people need to understand.

Would you like to propose something?

> 
> 
> IIUC, a program intended to be fully portable between C implementations
> must include <stddef.h>, not rely on one of the others.

Yes, in principle, programmers should use the first header in the list.
However, we listed all of them for completeness.  We only listed headers 
that guarantee to define the type, thogh, either by C or POSIX:


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

> 
> (In practice it seems reasonable to include any header that is specified
> to declare types or function prototypes that themselves require a
> definition of size_t, but this is awkward to describe, and not explicit
> in the standard.)
> 
> [...]
> 
> Cheers
> ---Dave
> 

Cheers,

Alex

[RFC] system_data_types.7: wfix + ffix

[Alejandro Colomar]

The previous format/wording for the includes wasn't very clear.
Improve it a bit following Branden's proposal.

Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi,

What do you think about this?

Would you change something?

Thanks,

Alex


 man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 172 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 16930985e..dc4a3bae4 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -33,20 +33,21 @@ system_data_types \- overview of system data types
 .\"	Each entry will have the following parts:
 .\"		* Include
 .\"			The headers will be in the following order:
+.\"			"Include:"
 .\"			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
+.\"			   according to the C Standard.
+.\"			["or"]
+.\"			2) The main header that shall define the type
+.\"			   according to POSIX.
+.\"			[". Alternatively,"]
+.\"			3) 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;
@@ -203,8 +204,8 @@ See also:
 .RS
 .br
 Include:
-.IR <stdio.h> ;
-or
+.IR <stdio.h> .
+Alternatively,
 .IR <wchar.h> .
 .PP
 An object type used for streams.
@@ -268,19 +269,14 @@ type in this page.
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <grp.h>
-or
-.I <pwd.h>
-or
-.I <signal.h>
-or
-.I <stropts.h>
-or
-.I <sys/ipc.h>
-or
-.I <sys/stat.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <grp.h> ,
+.IR <pwd.h> ,
+.IR <signal.h> ,
+.IR <stropts.h> ,
+.IR <sys/ipc.h> ,
+.IR <sys/stat.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -305,8 +301,8 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
+.IR <sys/types.h> .
+Alternatively,
 .IR <sys/resource.h> .
 .PP
 A type used to hold a general identifier.
@@ -450,29 +446,19 @@ See also:
 .RS
 .br
 Include
-.IR <sys/types.h> ;
-or
-.I <fcntl.h>
-or
-.I <sched.h>
-or
-.I <signal.h>
-or
-.I <spawn.h>
-or
-.I <sys/msg.h>
-or
-.I <sys/sem.h>
-or
-.I <sys/shm.h>
-or
-.I <sys/wait.h>
-or
-.I <termios.h>
-or
-.I <time.h>
-or
-.I <unistd.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <fcntl.h> ,
+.IR <sched.h> ,
+.IR <signal.h> ,
+.IR <spawn.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/wait.h> ,
+.IR <termios.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
 or
 .IR <utmpx.h> .
 .PP
@@ -602,11 +588,10 @@ types in this page.
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
-.I <aio.h>
-or
-.I <mqueue.h>
+.IR <signal.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <mqueue.h> ,
 or
 .IR <time.h> .
 .PP
@@ -651,8 +636,8 @@ structure in this page.
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
+.IR <signal.h> .
+Alternatively,
 .IR <sys/wait.h> .
 .PP
 .EX
@@ -687,9 +672,9 @@ See also:
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
-.I <spawn.h>
+.IR <signal.h> .
+Alternatively,
+.IR <spawn.h> ,
 or
 .IR <sys/select.h> .
 .PP
@@ -750,55 +735,32 @@ in this page.
 Include:
 .I <stddef.h>
 or
-.IR <sys/types.h> ;
-or
-.I <aio.h>
-or
-.I <glob.h>
-or
-.I <grp.h>
-or
-.I <iconv.h>
-or
-.I <monetary.h>
-or
-.I <mqueue.h>
-or
-.I <ndbm.h>
-or
-.I <pwd.h>
-or
-.I <regex.h>
-or
-.I <search.h>
-or
-.I <signal.h>
-or
-.I <stdio.h>
-or
-.I <stdlib.h>
-or
-.I <string.h>
-or
-.I <strings.h>
-or
-.I <sys/mman.h>
-or
-.I <sys/msg.h>
-or
-.I <sys/sem.h>
-or
-.I <sys/shm.h>
-or
-.I <sys/socket.h>
-or
-.I <sys/uio.h>
-or
-.I <time.h>
-or
-.I <unistd.h>
-or
-.I <wchar.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <glob.h> ,
+.IR <grp.h> ,
+.IR <iconv.h> ,
+.IR <monetary.h> ,
+.IR <mqueue.h> ,
+.IR <ndbm.h> ,
+.IR <pwd.h> ,
+.IR <regex.h> ,
+.IR <search.h> ,
+.IR <signal.h> ,
+.IR <stdio.h> ,
+.IR <stdlib.h> ,
+.IR <string.h> ,
+.IR <strings.h> ,
+.IR <sys/mman.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/socket.h> ,
+.IR <sys/uio.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
+.IR <wchar.h> ,
 or
 .IR <wordexp.h> .
 .PP
@@ -871,21 +833,15 @@ types in this page.
 .RS
 .br
 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>
+.IR <sys/types.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <monetary.h> ,
+.IR <mqueue.h> ,
+.IR <stdio.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/socket.h> ,
+.IR <sys/uio.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -947,9 +903,9 @@ types in this page.
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <sys/select.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <sys/select.h> ,
 or
 .IR <sys/time.h> .
 .PP
@@ -974,23 +930,17 @@ structure in this page.
 .RS
 .br
 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>
+.I <time.h>
 or
-.I <sys/time.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <sched.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/select.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/stat.h> ,
+.IR <sys/time.h> ,
 or
 .IR <utime.h> .
 .PP
@@ -1017,8 +967,8 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
+.IR <sys/types.h> .
+Alternatively,
 .IR <time.h> .
 .PP
 Used for timer ID returned by
@@ -1040,17 +990,13 @@ See also:
 .RS
 .br
 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>
+.IR <time.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <mqueue.h> ,
+.IR <sched.h> ,
+.IR <signal.h> ,
+.IR <sys/select.h> ,
 or
 .IR <sys/stat.h> .
 .PP
@@ -1078,11 +1024,10 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/time.h> ;
-or
-.I <sys/resource.h>
-or
-.I <sys/select.h>
+.IR <sys/time.h> .
+Alternatively,
+.IR <sys/resource.h> ,
+.IR <sys/select.h> ,
 or
 .IR <utmpx.h> .
 .PP
@@ -1111,17 +1056,13 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <pwd.h>
-or
-.I <signal.h>
-or
-.I <stropts.h>
-or
-.I <sys/ipc.h>
-or
-.I <sys/stat.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <pwd.h> ,
+.IR <signal.h> ,
+.IR <stropts.h> ,
+.IR <sys/ipc.h> ,
+.IR <sys/stat.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -1145,9 +1086,9 @@ See also:
 .RS
 .br
 Include:
-.IR <stdarg> ;
-or
-.I <stdio.h>
+.IR <stdarg> .
+Alternatively,
+.IR <stdio.h> ,
 or
 .IR <wchar.h> .
 .PP
-- 
2.28.0

Re: [RFC] system_data_types.7: wfix + ffix

[Dave Martin]

On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote:
> The previous format/wording for the includes wasn't very clear.
> Improve it a bit following Branden's proposal.
> 
> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi,
> 
> What do you think about this?
> 
> Would you change something?

Why should the user of a man page have to go look at the comments in the
page source in order to find an explanation of what the notation in the
page means?  That seems very strange.

> 
> Thanks,
> 
> Alex
> 
> 
>  man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
>  1 file changed, 113 insertions(+), 172 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index 16930985e..dc4a3bae4 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -33,20 +33,21 @@ system_data_types \- overview of system data types
>  .\"	Each entry will have the following parts:
>  .\"		* Include
>  .\"			The headers will be in the following order:
> +.\"			"Include:"
>  .\"			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
> +.\"			   according to the C Standard.
> +.\"			["or"]
> +.\"			2) The main header that shall define the type
> +.\"			   according to POSIX.
> +.\"			[". Alternatively,"]
> +.\"			3) 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.
> +.\"			"."

It is fine to have notes about page maintenance here -- i.e., which
headers should be placed where in the list, and what order to sort them
in.

However, I think that statements about which header(s) provide the type
under which standard need to be in the actual page text.  Programmers
need this information.

>  .\"
>  .\"		* Definition (no "Definition" header)
>  .\"			Only struct/union types will have definition;
> @@ -203,8 +204,8 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <stdio.h> ;
> -or
> +.IR <stdio.h> .
> +Alternatively,
>  .IR <wchar.h> .
>  .PP
>  An object type used for streams.
> @@ -268,19 +269,14 @@ type in this page.
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> -.I <grp.h>
> -or
> -.I <pwd.h>
> -or
> -.I <signal.h>
> -or
> -.i <stropts.h>
> -or
> -.I <sys/ipc.h>
> -or
> -.I <sys/stat.h>
> +.IR <sys/types.h> .
> +Alternatively,

How does the reader of the page know that "alternatively" here has a
specific and different meaning from "or"?

Can we describe this somehow along the lines of:

The C standards specify this type in the following header:

	<stddef.h>

In POSIX environments, it is sufficient instead to include any of the
following headers, but the resulting program may not be portable to
other C implementations unless <stddef.h> is also included:

	[etc.]


(I'm not sure this is 100% true, but it seems a safe recommendation.
I'm also being lazy by writing "the C standards" and "POSIX
environments" here -- it would be better to be specific.)

[...]

Cheers
---Dave

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Michael Kerrisk (man-pages)]

Hi Dave,

On Mon, 28 Sep 2020 at 16:15, Dave Martin <Dave.Martin@arm.com> wrote:
>
> On Mon, Sep 28, 2020 at 11:55:08PM +1000, G. Branden Robinson wrote:
> > Hi, Alex!
> >
> > At 2020-09-28T15:48:14+0200, Alejandro Colomar wrote:
> > > > Where does this arbitrary-looking list of headers come from?
> > >
> > > There are two parts:  left to the ';', and right to the ';'.
> > >
> > > Left: The canonical C standard header, and the canonical POSIX header,
> > > in alphabetical order.
> > >
> > > Right: All other headers that shall define the header, according to
> > > either the C or the POSIX standards, in alphabetical order.
>
> To clarify, does POSIX _guarantee_ that all of those headers define this
> type?  (I admit I'm too lazy to search through the POSIX standard for an
> answer to this).
>
> If not, this list would serve only to legitimise bad habits and it may
> be better to leave it out.

As I think Alex has clarified, the info about headers is being taken from POSIX.

> > That's not a bad scheme but it is not inferable from the current man
> > page text; I almost commented on the inconsistency in one of my earlier
> > messages but deemed it out of scope.  Please document it, perhaps in an
> > introductory paragraph at the top of the Description section.
>
> Ack, I think it would be better to state this explicity rather than
> having some terse syntax that people need to understand.

Yes, I think some more explanatory text is probably needed. This page
is still very much a work in progress.

> IIUC, a program intended to be fully portable between C implementations
> must include <stddef.h>, not rely on one of the others.

Just to note a point here: my main concern is portability across POSIX systems.

Thanks,

Michael

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

Re: [RFC] system_data_types.7: wfix + ffix

[Michael Kerrisk (man-pages)]

Hi Alex, Dave,

[Alex, just to note: this patch doesn't apply against current master.]

On 9/29/20 12:37 PM, Dave Martin wrote:
> On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote:
>> The previous format/wording for the includes wasn't very clear.
>> Improve it a bit following Branden's proposal.
>>
>> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> Hi,
>>
>> What do you think about this?
>>
>> Would you change something?
> 
> Why should the user of a man page have to go look at the comments in the
> page source in order to find an explanation of what the notation in the
> page means?  That seems very strange.

I do agree that we need to add some help for the reader.

Alex, how about we start as follows. At the end of the NOTES Section,
let's add a "Conventions used in this page" subsection (.SS).

Some things to mention there:

* In "Conforming to" we only concern ourselves
  with POSIX.2001 and later and C99 and later.
  The type may be specified in earlier versions
  of one of these standards, but in the interests
  of simplicity we omit details from earlier standards.

* In "Include", we first note the "primary" header(s)
  that define the type according to either the C or POSIX.1
  standards. Under "Alternatively", we note additional headers
  that the standards specify shall define the type.

And then I have a question. Alex, did you so far find a case of
type where the C standard specified that a particular header
shall define the type, but PPOSIX.1 either did not have that
requirement or did not specify that header? I've been kind of
expecting that the set of headers specified by POSIX be a proper 
superset of the the set of headers specified by C, but maybe 
you have found otherwise.

>>  man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
>>  1 file changed, 113 insertions(+), 172 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 16930985e..dc4a3bae4 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -33,20 +33,21 @@ system_data_types \- overview of system data types
>>  .\"	Each entry will have the following parts:
>>  .\"		* Include
>>  .\"			The headers will be in the following order:
>> +.\"			"Include:"
>>  .\"			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
>> +.\"			   according to the C Standard.
>> +.\"			["or"]
>> +.\"			2) The main header that shall define the type
>> +.\"			   according to POSIX.
>> +.\"			[". Alternatively,"]
>> +.\"			3) 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.
>> +.\"			"."
> 
> It is fine to have notes about page maintenance here -- i.e., which
> headers should be placed where in the list, and what order to sort them
> in.
> 
> However, I think that statements about which header(s) provide the type
> under which standard need to be in the actual page text.  Programmers
> need this information.

My question (to Alex) above is related. (And to repeat, the thing
I most care about in the man pages is POSIX.1, rather than C.)

>>  .\"
>>  .\"		* Definition (no "Definition" header)
>>  .\"			Only struct/union types will have definition;
>> @@ -203,8 +204,8 @@ See also:
>>  .RS
>>  .br
>>  Include:
>> -.IR <stdio.h> ;
>> -or
>> +.IR <stdio.h> .
>> +Alternatively,
>>  .IR <wchar.h> .
>>  .PP
>>  An object type used for streams.
>> @@ -268,19 +269,14 @@ type in this page.
>>  .RS
>>  .br
>>  Include:
>> -.IR <sys/types.h> ;
>> -or
>> -.I <grp.h>
>> -or
>> -.I <pwd.h>
>> -or
>> -.I <signal.h>
>> -or
>> -.i <stropts.h>
>> -or
>> -.I <sys/ipc.h>
>> -or
>> -.I <sys/stat.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
> 
> How does the reader of the page know that "alternatively" here has a
> specific and different meaning from "or"?
> 
> Can we describe this somehow along the lines of:
> 
> The C standards specify this type in the following header:
> 
> 	<stddef.h>
> 
> In POSIX environments, it is sufficient instead to include any of the
> following headers, but the resulting program may not be portable to
> other C implementations unless <stddef.h> is also included:
> 
> 	[etc.]
> 
> 
> (I'm not sure this is 100% true, but it seems a safe recommendation.
> I'm also being lazy by writing "the C standards" and "POSIX
> environments" here -- it would be better to be specific.)

This feels too verbose to me. Again, I care more about POSIX
than C here. This is Linux; it quacks like a UNIX; so POSIX
is the most relevant thing. And I want to keep the discussion
of these types reasonably brief. In particular, I think that
people who care a lot about portability across C implementations
need to be looking somewhere else than the Linux manual pages.

Thanks,

Michael

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

Re: [RFC] system_data_types.7: wfix + ffix

[Alejandro Colomar]

Hi Dave,

On 2020-09-29 12:37, Dave Martin wrote:
> On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote:
>> The previous format/wording for the includes wasn't very clear.
>> Improve it a bit following Branden's proposal.
>>
>> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
>> ---
>>
>> Hi,
>>
>> What do you think about this?
>>
>> Would you change something?
> 
> Why should the user of a man page have to go look at the comments in the
> page source in order to find an explanation of what the notation in the
> page means?  That seems very strange.

I think I'll add a paragraph in the NOTES section at the bottom of the page.

> 
>>
>> Thanks,
>>
>> Alex
>>
>>
>>   man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
>>   1 file changed, 113 insertions(+), 172 deletions(-)
>>
>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
>> index 16930985e..dc4a3bae4 100644
>> --- a/man7/system_data_types.7
>> +++ b/man7/system_data_types.7
>> @@ -33,20 +33,21 @@ system_data_types \- overview of system data types
>>   .\"	Each entry will have the following parts:
>>   .\"		* Include
>>   .\"			The headers will be in the following order:
>> +.\"			"Include:"
>>   .\"			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
>> +.\"			   according to the C Standard.
>> +.\"			["or"]
>> +.\"			2) The main header that shall define the type
>> +.\"			   according to POSIX.
>> +.\"			[". Alternatively,"]
>> +.\"			3) 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.
>> +.\"			"."
> 
> It is fine to have notes about page maintenance here -- i.e., which
> headers should be placed where in the list, and what order to sort them
> in.
> 
> However, I think that statements about which header(s) provide the type
> under which standard need to be in the actual page text.  Programmers
> need this information.

I hope a paragraph in the NOTES section will be explicit enough, as said 
above.

> 
>>   .\"
>>   .\"		* Definition (no "Definition" header)
>>   .\"			Only struct/union types will have definition;
>> @@ -203,8 +204,8 @@ See also:
>>   .RS
>>   .br
>>   Include:
>> -.IR <stdio.h> ;
>> -or
>> +.IR <stdio.h> .
>> +Alternatively,
>>   .IR <wchar.h> .
>>   .PP
>>   An object type used for streams.
>> @@ -268,19 +269,14 @@ type in this page.
>>   .RS
>>   .br
>>   Include:
>> -.IR <sys/types.h> ;
>> -or
>> -.I <grp.h>
>> -or
>> -.I <pwd.h>
>> -or
>> -.I <signal.h>
>> -or
>> -.i <stropts.h>
>> -or
>> -.I <sys/ipc.h>
>> -or
>> -.I <sys/stat.h>
>> +.IR <sys/types.h> .
>> +Alternatively,
> 
> How does the reader of the page know that "alternatively" here has a
> specific and different meaning from "or"?

Well, it remarks a bit that those are something like 2nd class headers 
for that definition.  But that together with a paragraph in NOTES will 
be better.

> 
> Can we describe this somehow along the lines of:
> 
> The C standards specify this type in the following header:
> 
> 	<stddef.h>
> 
> In POSIX environments, it is sufficient instead to include any of the
> following headers, but the resulting program may not be portable to
> other C implementations unless <stddef.h> is also included:
> 
> 	[etc.]
> 
> 
> (I'm not sure this is 100% true, but it seems a safe recommendation.
> I'm also being lazy by writing "the C standards" and "POSIX
> environments" here -- it would be better to be specific.)
> 
> [...]

I wanted to avoid that because that would add a lot of noise lines.

Do you think the note in NOTES would be enough?

Thanks,

Alex

> 
> Cheers
> ---Dave
> 

Re: [RFC] system_data_types.7: wfix + ffix

[Alejandro Colomar]

Hi Michael & Dave,

On 2020-09-29 13:34, Michael Kerrisk (man-pages) wrote:
 > Hi Alex, Dave,
 >
 > [Alex, just to note: this patch doesn't apply against current master.]
 >
 > On 9/29/20 12:37 PM, Dave Martin wrote:
 >> On Mon, Sep 28, 2020 at 05:16:47PM +0200, Alejandro Colomar wrote:
 >>> The previous format/wording for the includes wasn't very clear.
 >>> Improve it a bit following Branden's proposal.
 >>>
 >>> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
 >>> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >>> ---
 >>>
 >>> Hi,
 >>>
 >>> What do you think about this?
 >>>
 >>> Would you change something?
 >>
 >> Why should the user of a man page have to go look at the comments in the
 >> page source in order to find an explanation of what the notation in the
 >> page means?  That seems very strange.
 >
 > I do agree that we need to add some help for the reader.
 >
 > Alex, how about we start as follows. At the end of the NOTES Section,
 > let's add a "Conventions used in this page" subsection (.SS).

I just sent an email I wrote an hour ago,
where I proposed to add a paragraph in NOTES.
Your proposal is a bit more specific :)

 >
 > Some things to mention there:
 >
 > * In "Conforming to" we only concern ourselves
 >    with POSIX.2001 and later and C99 and later.
 >    The type may be specified in earlier versions
 >    of one of these standards, but in the interests
 >    of simplicity we omit details from earlier standards.

Agree.

 >
 > * In "Include", we first note the "primary" header(s)
 >    that define the type according to either the C or POSIX.1
 >    standards. Under "Alternatively", we note additional headers
 >    that the standards specify shall define the type.

Agree.

 >
 > And then I have a question. Alex, did you so far find a case of
 > type where the C standard specified that a particular header
 > shall define the type, but PPOSIX.1 either did not have that
 > requirement or did not specify that header?

No.

I've found types where the "primary" header is different in C and POSIX.
But in all the cases I've checked, POSIX always adds headers to C,
and never removes them.
I hope it is always true, because I didn't check all of them one by one.

 > I've been kind of
 > expecting that the set of headers specified by POSIX be a proper
 > superset of the the set of headers specified by C, but maybe
 > you have found otherwise.

AFAICS, that holds true.

 >
 >>>   man7/system_data_types.7 | 285 
++++++++++++++++-----------------------
 >>>   1 file changed, 113 insertions(+), 172 deletions(-)
 >>>
 >>> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
 >>> index 16930985e..dc4a3bae4 100644
 >>> --- a/man7/system_data_types.7
 >>> +++ b/man7/system_data_types.7
 >>> @@ -33,20 +33,21 @@ system_data_types \- overview of system data types
 >>>   .\"	Each entry will have the following parts:
 >>>   .\"		* Include
 >>>   .\"			The headers will be in the following order:
 >>> +.\"			"Include:"
 >>>   .\"			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
 >>> +.\"			   according to the C Standard.
 >>> +.\"			["or"]
 >>> +.\"			2) The main header that shall define the type
 >>> +.\"			   according to POSIX.
 >>> +.\"			[". Alternatively,"]
 >>> +.\"			3) 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.
 >>> +.\"			"."
 >>
 >> It is fine to have notes about page maintenance here -- i.e., which
 >> headers should be placed where in the list, and what order to sort them
 >> in.
 >>
 >> However, I think that statements about which header(s) provide the type
 >> under which standard need to be in the actual page text.  Programmers
 >> need this information.
 >
 > My question (to Alex) above is related. (And to repeat, the thing
 > I most care about in the man pages is POSIX.1, rather than C.)

If/when the NOTES section documents that clearly,
I may remove that comment.

 >
 >>>   .\"
 >>>   .\"		* Definition (no "Definition" header)
 >>>   .\"			Only struct/union types will have definition;
 >>> @@ -203,8 +204,8 @@ See also:
 >>>   .RS
 >>>   .br
 >>>   Include:
 >>> -.IR <stdio.h> ;
 >>> -or
 >>> +.IR <stdio.h> .
 >>> +Alternatively,
 >>>   .IR <wchar.h> .
 >>>   .PP
 >>>   An object type used for streams.
 >>> @@ -268,19 +269,14 @@ type in this page.
 >>>   .RS
 >>>   .br
 >>>   Include:
 >>> -.IR <sys/types.h> ;
 >>> -or
 >>> -.I <grp.h>
 >>> -or
 >>> -.I <pwd.h>
 >>> -or
 >>> -.I <signal.h>
 >>> -or
 >>> -.i <stropts.h>
 >>> -or
 >>> -.I <sys/ipc.h>
 >>> -or
 >>> -.I <sys/stat.h>
 >>> +.IR <sys/types.h> .
 >>> +Alternatively,
 >>
 >> How does the reader of the page know that "alternatively" here has a
 >> specific and different meaning from "or"?
 >>
 >> Can we describe this somehow along the lines of:
 >>
 >> The C standards specify this type in the following header:
 >>
 >> 	<stddef.h>
 >>
 >> In POSIX environments, it is sufficient instead to include any of the
 >> following headers, but the resulting program may not be portable to
 >> other C implementations unless <stddef.h> is also included:
 >>
 >> 	[etc.]
 >>
 >>
 >> (I'm not sure this is 100% true, but it seems a safe recommendation.
 >> I'm also being lazy by writing "the C standards" and "POSIX
 >> environments" here -- it would be better to be specific.)
 >
 > This feels too verbose to me. Again, I care more about POSIX
 > than C here. This is Linux; it quacks like a UNIX; so POSIX
 > is the most relevant thing. And I want to keep the discussion
 > of these types reasonably brief. In particular, I think that
 > people who care a lot about portability across C implementations
 > need to be looking somewhere else than the Linux manual pages.

Agree,

 >
 > Thanks,
 >
 > Michael
 >

Thanks,

Alex

[PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Alejandro Colomar]

The previous format/wording for the includes wasn't very clear.
Improve it a bit following Branden's proposal.
It also helps reduce lines of code.

Add a subsection in NOTES explaining the conventions used.

Remove the comment for helping maintain the page,
as the NOTES section is now clear enough.

Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
Reported-by: Dave Martin <Dave.Martin@arm.com>
Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
---

Hi Michael,

After this patch, we're at a sync-point: no more pending patches from me.

Tomorrow I'll go to the mountain, so you can have a small break from me :p

Cheers,

Alex


 man7/system_data_types.7 | 302 +++++++++++++++------------------------
 1 file changed, 119 insertions(+), 183 deletions(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index af0c55c65..9cf67ee6f 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -31,22 +31,7 @@ system_data_types \- overview of system data types
 .\" 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.
+.\"		* Include (see NOTES)
 .\"
 .\"		* Definition (no "Definition" header)
 .\"			Only struct/union types will have definition;
@@ -55,9 +40,10 @@ system_data_types \- overview of system data types
 .\"		* Description (no "Description" header)
 .\"			A few lines describing the type.
 .\"
-.\"		* Conforming to
+.\"		* Bugs (if any)
+.\"
+.\"		* Conforming to (see NOTES)
 .\"			Format: CXY and later; POSIX.1-XXXX and later.
-.\"			Forget about pre-C99 C standards (i.e., C89/C90)
 .\"
 .\"		* Notes (optional)
 .\"
@@ -203,8 +189,8 @@ See also:
 .RS
 .br
 Include:
-.IR <stdio.h> ;
-or
+.IR <stdio.h> .
+Alternatively,
 .IR <wchar.h> .
 .PP
 An object type used for streams.
@@ -269,19 +255,14 @@ type in this page.
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <grp.h>
-or
-.I <pwd.h>
-or
-.I <signal.h>
-or
-.I <stropts.h>
-or
-.I <sys/ipc.h>
-or
-.I <sys/stat.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <grp.h> ,
+.IR <pwd.h> ,
+.IR <signal.h> ,
+.IR <stropts.h> ,
+.IR <sys/ipc.h> ,
+.IR <sys/stat.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -306,8 +287,8 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
+.IR <sys/types.h> .
+Alternatively,
 .IR <sys/resource.h> .
 .PP
 A type used to hold a general identifier.
@@ -586,29 +567,19 @@ See also:
 .RS
 .br
 Include
-.IR <sys/types.h> ;
-or
-.I <fcntl.h>
-or
-.I <sched.h>
-or
-.I <signal.h>
-or
-.I <spawn.h>
-or
-.I <sys/msg.h>
-or
-.I <sys/sem.h>
-or
-.I <sys/shm.h>
-or
-.I <sys/wait.h>
-or
-.I <termios.h>
-or
-.I <time.h>
-or
-.I <unistd.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <fcntl.h> ,
+.IR <sched.h> ,
+.IR <signal.h> ,
+.IR <spawn.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/wait.h> ,
+.IR <termios.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
 or
 .IR <utmpx.h> .
 .PP
@@ -738,11 +709,10 @@ types in this page.
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
-.I <aio.h>
-or
-.I <mqueue.h>
+.IR <signal.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <mqueue.h> ,
 or
 .IR <time.h> .
 .PP
@@ -787,8 +757,8 @@ structure in this page.
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
+.IR <signal.h> .
+Alternatively,
 .IR <sys/wait.h> .
 .PP
 .EX
@@ -823,9 +793,9 @@ See also:
 .RS
 .br
 Include:
-.IR <signal.h> ;
-or
-.I <spawn.h>
+.IR <signal.h> .
+Alternatively,
+.IR <spawn.h> ,
 or
 .IR <sys/select.h> .
 .PP
@@ -886,55 +856,32 @@ in this page.
 Include:
 .I <stddef.h>
 or
-.IR <sys/types.h> ;
-or
-.I <aio.h>
-or
-.I <glob.h>
-or
-.I <grp.h>
-or
-.I <iconv.h>
-or
-.I <monetary.h>
-or
-.I <mqueue.h>
-or
-.I <ndbm.h>
-or
-.I <pwd.h>
-or
-.I <regex.h>
-or
-.I <search.h>
-or
-.I <signal.h>
-or
-.I <stdio.h>
-or
-.I <stdlib.h>
-or
-.I <string.h>
-or
-.I <strings.h>
-or
-.I <sys/mman.h>
-or
-.I <sys/msg.h>
-or
-.I <sys/sem.h>
-or
-.I <sys/shm.h>
-or
-.I <sys/socket.h>
-or
-.I <sys/uio.h>
-or
-.I <time.h>
-or
-.I <unistd.h>
-or
-.I <wchar.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <glob.h> ,
+.IR <grp.h> ,
+.IR <iconv.h> ,
+.IR <monetary.h> ,
+.IR <mqueue.h> ,
+.IR <ndbm.h> ,
+.IR <pwd.h> ,
+.IR <regex.h> ,
+.IR <search.h> ,
+.IR <signal.h> ,
+.IR <stdio.h> ,
+.IR <stdlib.h> ,
+.IR <string.h> ,
+.IR <strings.h> ,
+.IR <sys/mman.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/socket.h> ,
+.IR <sys/uio.h> ,
+.IR <time.h> ,
+.IR <unistd.h> ,
+.IR <wchar.h> ,
 or
 .IR <wordexp.h> .
 .PP
@@ -1007,21 +954,15 @@ types in this page.
 .RS
 .br
 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>
+.IR <sys/types.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <monetary.h> ,
+.IR <mqueue.h> ,
+.IR <stdio.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/socket.h> ,
+.IR <sys/uio.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -1083,9 +1024,9 @@ types in this page.
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <sys/select.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <sys/select.h> ,
 or
 .IR <sys/time.h> .
 .PP
@@ -1110,23 +1051,17 @@ structure in this page.
 .RS
 .br
 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>
+.I <time.h>
 or
-.I <sys/time.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <sched.h> ,
+.IR <sys/msg.h> ,
+.IR <sys/select.h> ,
+.IR <sys/sem.h> ,
+.IR <sys/shm.h> ,
+.IR <sys/stat.h> ,
+.IR <sys/time.h> ,
 or
 .IR <utime.h> .
 .PP
@@ -1153,8 +1088,8 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
+.IR <sys/types.h> .
+Alternatively,
 .IR <time.h> .
 .PP
 Used for timer ID returned by
@@ -1176,17 +1111,13 @@ See also:
 .RS
 .br
 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>
+.IR <time.h> .
+Alternatively,
+.IR <aio.h> ,
+.IR <mqueue.h> ,
+.IR <sched.h> ,
+.IR <signal.h> ,
+.IR <sys/select.h> ,
 or
 .IR <sys/stat.h> .
 .PP
@@ -1214,11 +1145,10 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/time.h> ;
-or
-.I <sys/resource.h>
-or
-.I <sys/select.h>
+.IR <sys/time.h> .
+Alternatively,
+.IR <sys/resource.h> ,
+.IR <sys/select.h> ,
 or
 .IR <utmpx.h> .
 .PP
@@ -1247,17 +1177,13 @@ See also:
 .RS
 .br
 Include:
-.IR <sys/types.h> ;
-or
-.I <pwd.h>
-or
-.I <signal.h>
-or
-.I <stropts.h>
-or
-.I <sys/ipc.h>
-or
-.I <sys/stat.h>
+.IR <sys/types.h> .
+Alternatively,
+.IR <pwd.h> ,
+.IR <signal.h> ,
+.IR <stropts.h> ,
+.IR <sys/ipc.h> ,
+.IR <sys/stat.h> ,
 or
 .IR <unistd.h> .
 .PP
@@ -1418,9 +1344,9 @@ types in this page.
 .RS
 .br
 Include:
-.IR <stdarg> ;
-or
-.I <stdio.h>
+.IR <stdarg> .
+Alternatively,
+.IR <stdio.h> ,
 or
 .IR <wchar.h> .
 .PP
@@ -1473,6 +1399,16 @@ If the type has upper and lower limits,
 the user should check that the value is within those limits,
 before actually copying the value.
 The example below shows how these conversions should be done.
+.SS Conventions used in this page
+In "Conforming to" we only concern ourselves with
+C99 and later and POSIX.1-2001 and later.
+Some types may be specified in earlier versions of one of these standards,
+but in the interests of simplicity we omit details from earlier standards.
+.PP
+In "Include", we first note the "primary" header(s) that
+define the type according to either the C or POSIX.1 standards.
+Under "Alternatively", we note additional headers that
+the standards specify shall define the type.
 .SH EXAMPLES
 The program shown below scans from a string and prints a value stored in
 a variable of an integer type that doesn't have a length modifier.
-- 
2.28.0

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Dave Martin]

On Tue, Sep 29, 2020 at 04:22:19PM +0200, Alejandro Colomar wrote:
> The previous format/wording for the includes wasn't very clear.
> Improve it a bit following Branden's proposal.
> It also helps reduce lines of code.
> 
> Add a subsection in NOTES explaining the conventions used.
> 
> Remove the comment for helping maintain the page,
> as the NOTES section is now clear enough.
> 
> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> Reported-by: Dave Martin <Dave.Martin@arm.com>
> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> ---
> 
> Hi Michael,
> 
> After this patch, we're at a sync-point: no more pending patches from me.
> 
> Tomorrow I'll go to the mountain, so you can have a small break from me :p
> 
> Cheers,
> 
> Alex
> 
> 
>  man7/system_data_types.7 | 302 +++++++++++++++------------------------
>  1 file changed, 119 insertions(+), 183 deletions(-)
> 
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index af0c55c65..9cf67ee6f 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -31,22 +31,7 @@ system_data_types \- overview of system data types
>  .\" 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.
> +.\"		* Include (see NOTES)
>  .\"
>  .\"		* Definition (no "Definition" header)
>  .\"			Only struct/union types will have definition;
> @@ -55,9 +40,10 @@ system_data_types \- overview of system data types
>  .\"		* Description (no "Description" header)
>  .\"			A few lines describing the type.
>  .\"
> -.\"		* Conforming to
> +.\"		* Bugs (if any)
> +.\"
> +.\"		* Conforming to (see NOTES)
>  .\"			Format: CXY and later; POSIX.1-XXXX and later.
> -.\"			Forget about pre-C99 C standards (i.e., C89/C90)
>  .\"
>  .\"		* Notes (optional)
>  .\"
> @@ -203,8 +189,8 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <stdio.h> ;
> -or
> +.IR <stdio.h> .
> +Alternatively,
>  .IR <wchar.h> .
>  .PP
>  An object type used for streams.
> @@ -269,19 +255,14 @@ type in this page.
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> -.I <grp.h>
> -or
> -.I <pwd.h>
> -or
> -.I <signal.h>
> -or
> -.I <stropts.h>
> -or
> -.I <sys/ipc.h>
> -or
> -.I <sys/stat.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <grp.h> ,
> +.IR <pwd.h> ,
> +.IR <signal.h> ,
> +.IR <stropts.h> ,
> +.IR <sys/ipc.h> ,
> +.IR <sys/stat.h> ,
>  or
>  .IR <unistd.h> .
>  .PP
> @@ -306,8 +287,8 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> +.IR <sys/types.h> .
> +Alternatively,
>  .IR <sys/resource.h> .
>  .PP
>  A type used to hold a general identifier.
> @@ -586,29 +567,19 @@ See also:
>  .RS
>  .br
>  Include
> -.IR <sys/types.h> ;
> -or
> -.I <fcntl.h>
> -or
> -.I <sched.h>
> -or
> -.I <signal.h>
> -or
> -.I <spawn.h>
> -or
> -.I <sys/msg.h>
> -or
> -.I <sys/sem.h>
> -or
> -.I <sys/shm.h>
> -or
> -.I <sys/wait.h>
> -or
> -.I <termios.h>
> -or
> -.I <time.h>
> -or
> -.I <unistd.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <fcntl.h> ,
> +.IR <sched.h> ,
> +.IR <signal.h> ,
> +.IR <spawn.h> ,
> +.IR <sys/msg.h> ,
> +.IR <sys/sem.h> ,
> +.IR <sys/shm.h> ,
> +.IR <sys/wait.h> ,
> +.IR <termios.h> ,
> +.IR <time.h> ,
> +.IR <unistd.h> ,
>  or
>  .IR <utmpx.h> .
>  .PP
> @@ -738,11 +709,10 @@ types in this page.
>  .RS
>  .br
>  Include:
> -.IR <signal.h> ;
> -or
> -.I <aio.h>
> -or
> -.I <mqueue.h>
> +.IR <signal.h> .
> +Alternatively,
> +.IR <aio.h> ,
> +.IR <mqueue.h> ,
>  or
>  .IR <time.h> .
>  .PP
> @@ -787,8 +757,8 @@ structure in this page.
>  .RS
>  .br
>  Include:
> -.IR <signal.h> ;
> -or
> +.IR <signal.h> .
> +Alternatively,
>  .IR <sys/wait.h> .
>  .PP
>  .EX
> @@ -823,9 +793,9 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <signal.h> ;
> -or
> -.I <spawn.h>
> +.IR <signal.h> .
> +Alternatively,
> +.IR <spawn.h> ,
>  or
>  .IR <sys/select.h> .
>  .PP
> @@ -886,55 +856,32 @@ in this page.
>  Include:
>  .I <stddef.h>
>  or
> -.IR <sys/types.h> ;
> -or
> -.I <aio.h>
> -or
> -.I <glob.h>
> -or
> -.I <grp.h>
> -or
> -.I <iconv.h>
> -or
> -.I <monetary.h>
> -or
> -.I <mqueue.h>
> -or
> -.I <ndbm.h>
> -or
> -.I <pwd.h>
> -or
> -.I <regex.h>
> -or
> -.I <search.h>
> -or
> -.I <signal.h>
> -or
> -.I <stdio.h>
> -or
> -.I <stdlib.h>
> -or
> -.I <string.h>
> -or
> -.I <strings.h>
> -or
> -.I <sys/mman.h>
> -or
> -.I <sys/msg.h>
> -or
> -.I <sys/sem.h>
> -or
> -.I <sys/shm.h>
> -or
> -.I <sys/socket.h>
> -or
> -.I <sys/uio.h>
> -or
> -.I <time.h>
> -or
> -.I <unistd.h>
> -or
> -.I <wchar.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <aio.h> ,
> +.IR <glob.h> ,
> +.IR <grp.h> ,
> +.IR <iconv.h> ,
> +.IR <monetary.h> ,
> +.IR <mqueue.h> ,
> +.IR <ndbm.h> ,
> +.IR <pwd.h> ,
> +.IR <regex.h> ,
> +.IR <search.h> ,
> +.IR <signal.h> ,
> +.IR <stdio.h> ,
> +.IR <stdlib.h> ,
> +.IR <string.h> ,
> +.IR <strings.h> ,
> +.IR <sys/mman.h> ,
> +.IR <sys/msg.h> ,
> +.IR <sys/sem.h> ,
> +.IR <sys/shm.h> ,
> +.IR <sys/socket.h> ,
> +.IR <sys/uio.h> ,
> +.IR <time.h> ,
> +.IR <unistd.h> ,
> +.IR <wchar.h> ,
>  or
>  .IR <wordexp.h> .
>  .PP
> @@ -1007,21 +954,15 @@ types in this page.
>  .RS
>  .br
>  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>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <aio.h> ,
> +.IR <monetary.h> ,
> +.IR <mqueue.h> ,
> +.IR <stdio.h> ,
> +.IR <sys/msg.h> ,
> +.IR <sys/socket.h> ,
> +.IR <sys/uio.h> ,
>  or
>  .IR <unistd.h> .
>  .PP
> @@ -1083,9 +1024,9 @@ types in this page.
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> -.I <sys/select.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <sys/select.h> ,
>  or
>  .IR <sys/time.h> .
>  .PP
> @@ -1110,23 +1051,17 @@ structure in this page.
>  .RS
>  .br
>  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>
> +.I <time.h>
>  or
> -.I <sys/time.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <sched.h> ,
> +.IR <sys/msg.h> ,
> +.IR <sys/select.h> ,
> +.IR <sys/sem.h> ,
> +.IR <sys/shm.h> ,
> +.IR <sys/stat.h> ,
> +.IR <sys/time.h> ,
>  or
>  .IR <utime.h> .
>  .PP
> @@ -1153,8 +1088,8 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> +.IR <sys/types.h> .
> +Alternatively,
>  .IR <time.h> .
>  .PP
>  Used for timer ID returned by
> @@ -1176,17 +1111,13 @@ See also:
>  .RS
>  .br
>  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>
> +.IR <time.h> .
> +Alternatively,
> +.IR <aio.h> ,
> +.IR <mqueue.h> ,
> +.IR <sched.h> ,
> +.IR <signal.h> ,
> +.IR <sys/select.h> ,
>  or
>  .IR <sys/stat.h> .
>  .PP
> @@ -1214,11 +1145,10 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <sys/time.h> ;
> -or
> -.I <sys/resource.h>
> -or
> -.I <sys/select.h>
> +.IR <sys/time.h> .
> +Alternatively,
> +.IR <sys/resource.h> ,
> +.IR <sys/select.h> ,
>  or
>  .IR <utmpx.h> .
>  .PP
> @@ -1247,17 +1177,13 @@ See also:
>  .RS
>  .br
>  Include:
> -.IR <sys/types.h> ;
> -or
> -.I <pwd.h>
> -or
> -.I <signal.h>
> -or
> -.I <stropts.h>
> -or
> -.I <sys/ipc.h>
> -or
> -.I <sys/stat.h>
> +.IR <sys/types.h> .
> +Alternatively,
> +.IR <pwd.h> ,
> +.IR <signal.h> ,
> +.IR <stropts.h> ,
> +.IR <sys/ipc.h> ,
> +.IR <sys/stat.h> ,
>  or
>  .IR <unistd.h> .
>  .PP
> @@ -1418,9 +1344,9 @@ types in this page.
>  .RS
>  .br
>  Include:
> -.IR <stdarg> ;
> -or
> -.I <stdio.h>
> +.IR <stdarg> .
> +Alternatively,
> +.IR <stdio.h> ,
>  or
>  .IR <wchar.h> .
>  .PP
> @@ -1473,6 +1399,16 @@ If the type has upper and lower limits,
>  the user should check that the value is within those limits,
>  before actually copying the value.
>  The example below shows how these conversions should be done.
> +.SS Conventions used in this page
> +In "Conforming to" we only concern ourselves with
> +C99 and later and POSIX.1-2001 and later.
> +Some types may be specified in earlier versions of one of these standards,
> +but in the interests of simplicity we omit details from earlier standards.
> +.PP
> +In "Include", we first note the "primary" header(s) that
> +define the type according to either the C or POSIX.1 standards.
> +Under "Alternatively", we note additional headers that
> +the standards specify shall define the type.

While this is more informative, it still doesn't help the programmer
know which header(s) to use in a given situation.  I'd worry that people
may not read as far as the NOTES, or may not remember what's in there
when referring to the header lists.

Can we not just annotate each header listed with the originating
standard, say:

	<stddef.h>	(C)

	<sys/types.h>	(POSIX)
	...		(POSIX)
	...

while this is a bit more effort in the man page, it should make things
clear for the reader.

(the annotations can be terse, with a more complete citation of the
applicable standard in the NOTES or elsewhere).

I'm not trying to be awkard here -- actually having man pages defining
key types and the relevant headers to include is a really good idea.


Can we please alias all the actual type names to point to this page,
so that e.g., "man size_t" works?

(This might be considered overkill, so if others shoot the suggestion
down, fair enough -- in any case the alises could be added by a later
patch.)

Cheers
---Dave

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Alejandro Colomar]

Hi Dave,

On 2020-09-29 16:43, Dave Martin wrote:
 > On Tue, Sep 29, 2020 at 04:22:19PM +0200, Alejandro Colomar wrote:
 >> The previous format/wording for the includes wasn't very clear.
 >> Improve it a bit following Branden's proposal.
 >> It also helps reduce lines of code.
 >>
 >> Add a subsection in NOTES explaining the conventions used.
 >>
 >> Remove the comment for helping maintain the page,
 >> as the NOTES section is now clear enough.
 >>
 >> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
 >> Reported-by: Dave Martin <Dave.Martin@arm.com>
 >> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
 >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
 >> ---
 >>
 >> Hi Michael,
 >>
 >> After this patch, we're at a sync-point: no more pending patches 
from me.
 >>
 >> Tomorrow I'll go to the mountain, so you can have a small break from 
me :p
 >>
 >> Cheers,
 >>
 >> Alex
 >>
 >>
 >>   man7/system_data_types.7 | 302 +++++++++++++++------------------------
 >>   1 file changed, 119 insertions(+), 183 deletions(-)
 >>
 >> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
 >> index af0c55c65..9cf67ee6f 100644
 >> --- a/man7/system_data_types.7
 >> +++ b/man7/system_data_types.7
 >> @@ -31,22 +31,7 @@ system_data_types \- overview of system data types
 >>   .\" 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.
 >> +.\"		* Include (see NOTES)
 >>   .\"
 >>   .\"		* Definition (no "Definition" header)
 >>   .\"			Only struct/union types will have definition;
 >> @@ -55,9 +40,10 @@ system_data_types \- overview of system data types
 >>   .\"		* Description (no "Description" header)
 >>   .\"			A few lines describing the type.
 >>   .\"
 >> -.\"		* Conforming to
 >> +.\"		* Bugs (if any)
 >> +.\"
 >> +.\"		* Conforming to (see NOTES)
 >>   .\"			Format: CXY and later; POSIX.1-XXXX and later.
 >> -.\"			Forget about pre-C99 C standards (i.e., C89/C90)
 >>   .\"
 >>   .\"		* Notes (optional)
 >>   .\"
 >> @@ -203,8 +189,8 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <stdio.h> ;
 >> -or
 >> +.IR <stdio.h> .
 >> +Alternatively,
 >>   .IR <wchar.h> .
 >>   .PP
 >>   An object type used for streams.
 >> @@ -269,19 +255,14 @@ type in this page.
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/types.h> ;
 >> -or
 >> -.I <grp.h>
 >> -or
 >> -.I <pwd.h>
 >> -or
 >> -.I <signal.h>
 >> -or
 >> -.I <stropts.h>
 >> -or
 >> -.I <sys/ipc.h>
 >> -or
 >> -.I <sys/stat.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <grp.h> ,
 >> +.IR <pwd.h> ,
 >> +.IR <signal.h> ,
 >> +.IR <stropts.h> ,
 >> +.IR <sys/ipc.h> ,
 >> +.IR <sys/stat.h> ,
 >>   or
 >>   .IR <unistd.h> .
 >>   .PP
 >> @@ -306,8 +287,8 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/types.h> ;
 >> -or
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >>   .IR <sys/resource.h> .
 >>   .PP
 >>   A type used to hold a general identifier.
 >> @@ -586,29 +567,19 @@ See also:
 >>   .RS
 >>   .br
 >>   Include
 >> -.IR <sys/types.h> ;
 >> -or
 >> -.I <fcntl.h>
 >> -or
 >> -.I <sched.h>
 >> -or
 >> -.I <signal.h>
 >> -or
 >> -.I <spawn.h>
 >> -or
 >> -.I <sys/msg.h>
 >> -or
 >> -.I <sys/sem.h>
 >> -or
 >> -.I <sys/shm.h>
 >> -or
 >> -.I <sys/wait.h>
 >> -or
 >> -.I <termios.h>
 >> -or
 >> -.I <time.h>
 >> -or
 >> -.I <unistd.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <fcntl.h> ,
 >> +.IR <sched.h> ,
 >> +.IR <signal.h> ,
 >> +.IR <spawn.h> ,
 >> +.IR <sys/msg.h> ,
 >> +.IR <sys/sem.h> ,
 >> +.IR <sys/shm.h> ,
 >> +.IR <sys/wait.h> ,
 >> +.IR <termios.h> ,
 >> +.IR <time.h> ,
 >> +.IR <unistd.h> ,
 >>   or
 >>   .IR <utmpx.h> .
 >>   .PP
 >> @@ -738,11 +709,10 @@ types in this page.
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <signal.h> ;
 >> -or
 >> -.I <aio.h>
 >> -or
 >> -.I <mqueue.h>
 >> +.IR <signal.h> .
 >> +Alternatively,
 >> +.IR <aio.h> ,
 >> +.IR <mqueue.h> ,
 >>   or
 >>   .IR <time.h> .
 >>   .PP
 >> @@ -787,8 +757,8 @@ structure in this page.
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <signal.h> ;
 >> -or
 >> +.IR <signal.h> .
 >> +Alternatively,
 >>   .IR <sys/wait.h> .
 >>   .PP
 >>   .EX
 >> @@ -823,9 +793,9 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <signal.h> ;
 >> -or
 >> -.I <spawn.h>
 >> +.IR <signal.h> .
 >> +Alternatively,
 >> +.IR <spawn.h> ,
 >>   or
 >>   .IR <sys/select.h> .
 >>   .PP
 >> @@ -886,55 +856,32 @@ in this page.
 >>   Include:
 >>   .I <stddef.h>
 >>   or
 >> -.IR <sys/types.h> ;
 >> -or
 >> -.I <aio.h>
 >> -or
 >> -.I <glob.h>
 >> -or
 >> -.I <grp.h>
 >> -or
 >> -.I <iconv.h>
 >> -or
 >> -.I <monetary.h>
 >> -or
 >> -.I <mqueue.h>
 >> -or
 >> -.I <ndbm.h>
 >> -or
 >> -.I <pwd.h>
 >> -or
 >> -.I <regex.h>
 >> -or
 >> -.I <search.h>
 >> -or
 >> -.I <signal.h>
 >> -or
 >> -.I <stdio.h>
 >> -or
 >> -.I <stdlib.h>
 >> -or
 >> -.I <string.h>
 >> -or
 >> -.I <strings.h>
 >> -or
 >> -.I <sys/mman.h>
 >> -or
 >> -.I <sys/msg.h>
 >> -or
 >> -.I <sys/sem.h>
 >> -or
 >> -.I <sys/shm.h>
 >> -or
 >> -.I <sys/socket.h>
 >> -or
 >> -.I <sys/uio.h>
 >> -or
 >> -.I <time.h>
 >> -or
 >> -.I <unistd.h>
 >> -or
 >> -.I <wchar.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <aio.h> ,
 >> +.IR <glob.h> ,
 >> +.IR <grp.h> ,
 >> +.IR <iconv.h> ,
 >> +.IR <monetary.h> ,
 >> +.IR <mqueue.h> ,
 >> +.IR <ndbm.h> ,
 >> +.IR <pwd.h> ,
 >> +.IR <regex.h> ,
 >> +.IR <search.h> ,
 >> +.IR <signal.h> ,
 >> +.IR <stdio.h> ,
 >> +.IR <stdlib.h> ,
 >> +.IR <string.h> ,
 >> +.IR <strings.h> ,
 >> +.IR <sys/mman.h> ,
 >> +.IR <sys/msg.h> ,
 >> +.IR <sys/sem.h> ,
 >> +.IR <sys/shm.h> ,
 >> +.IR <sys/socket.h> ,
 >> +.IR <sys/uio.h> ,
 >> +.IR <time.h> ,
 >> +.IR <unistd.h> ,
 >> +.IR <wchar.h> ,
 >>   or
 >>   .IR <wordexp.h> .
 >>   .PP
 >> @@ -1007,21 +954,15 @@ types in this page.
 >>   .RS
 >>   .br
 >>   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>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <aio.h> ,
 >> +.IR <monetary.h> ,
 >> +.IR <mqueue.h> ,
 >> +.IR <stdio.h> ,
 >> +.IR <sys/msg.h> ,
 >> +.IR <sys/socket.h> ,
 >> +.IR <sys/uio.h> ,
 >>   or
 >>   .IR <unistd.h> .
 >>   .PP
 >> @@ -1083,9 +1024,9 @@ types in this page.
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/types.h> ;
 >> -or
 >> -.I <sys/select.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <sys/select.h> ,
 >>   or
 >>   .IR <sys/time.h> .
 >>   .PP
 >> @@ -1110,23 +1051,17 @@ structure in this page.
 >>   .RS
 >>   .br
 >>   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>
 >> +.I <time.h>
 >>   or
 >> -.I <sys/time.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <sched.h> ,
 >> +.IR <sys/msg.h> ,
 >> +.IR <sys/select.h> ,
 >> +.IR <sys/sem.h> ,
 >> +.IR <sys/shm.h> ,
 >> +.IR <sys/stat.h> ,
 >> +.IR <sys/time.h> ,
 >>   or
 >>   .IR <utime.h> .
 >>   .PP
 >> @@ -1153,8 +1088,8 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/types.h> ;
 >> -or
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >>   .IR <time.h> .
 >>   .PP
 >>   Used for timer ID returned by
 >> @@ -1176,17 +1111,13 @@ See also:
 >>   .RS
 >>   .br
 >>   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>
 >> +.IR <time.h> .
 >> +Alternatively,
 >> +.IR <aio.h> ,
 >> +.IR <mqueue.h> ,
 >> +.IR <sched.h> ,
 >> +.IR <signal.h> ,
 >> +.IR <sys/select.h> ,
 >>   or
 >>   .IR <sys/stat.h> .
 >>   .PP
 >> @@ -1214,11 +1145,10 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/time.h> ;
 >> -or
 >> -.I <sys/resource.h>
 >> -or
 >> -.I <sys/select.h>
 >> +.IR <sys/time.h> .
 >> +Alternatively,
 >> +.IR <sys/resource.h> ,
 >> +.IR <sys/select.h> ,
 >>   or
 >>   .IR <utmpx.h> .
 >>   .PP
 >> @@ -1247,17 +1177,13 @@ See also:
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <sys/types.h> ;
 >> -or
 >> -.I <pwd.h>
 >> -or
 >> -.I <signal.h>
 >> -or
 >> -.I <stropts.h>
 >> -or
 >> -.I <sys/ipc.h>
 >> -or
 >> -.I <sys/stat.h>
 >> +.IR <sys/types.h> .
 >> +Alternatively,
 >> +.IR <pwd.h> ,
 >> +.IR <signal.h> ,
 >> +.IR <stropts.h> ,
 >> +.IR <sys/ipc.h> ,
 >> +.IR <sys/stat.h> ,
 >>   or
 >>   .IR <unistd.h> .
 >>   .PP
 >> @@ -1418,9 +1344,9 @@ types in this page.
 >>   .RS
 >>   .br
 >>   Include:
 >> -.IR <stdarg> ;
 >> -or
 >> -.I <stdio.h>
 >> +.IR <stdarg> .
 >> +Alternatively,
 >> +.IR <stdio.h> ,
 >>   or
 >>   .IR <wchar.h> .
 >>   .PP
 >> @@ -1473,6 +1399,16 @@ If the type has upper and lower limits,
 >>   the user should check that the value is within those limits,
 >>   before actually copying the value.
 >>   The example below shows how these conversions should be done.
 >> +.SS Conventions used in this page
 >> +In "Conforming to" we only concern ourselves with
 >> +C99 and later and POSIX.1-2001 and later.
 >> +Some types may be specified in earlier versions of one of these 
standards,
 >> +but in the interests of simplicity we omit details from earlier 
standards.
 >> +.PP
 >> +In "Include", we first note the "primary" header(s) that
 >> +define the type according to either the C or POSIX.1 standards.
 >> +Under "Alternatively", we note additional headers that
 >> +the standards specify shall define the type.
 >
 > While this is more informative, it still doesn't help the programmer
 > know which header(s) to use in a given situation.  I'd worry that people
 > may not read as far as the NOTES, or may not remember what's in there
 > when referring to the header lists.

I hope they do :)
And if not, I hope that people will take the first one they see
(and not go through some obscure alternative headers).

 >
 > Can we not just annotate each header listed with the originating
 > standard, say:
 >
 > 	<stddef.h>	(C)
 >
 > 	<sys/types.h>	(POSIX)
 > 	...		(POSIX)
 > 	...

That may be a good idea; I've thought about doing that in the past;
but also thought that it's still too much noise.
Let's see what others think about it.

The downside is that it adds a lot of lines,
being harder to read for types with too many headers (e.g., size_t).

It could also be done in the same line, but maybe it adds too much noise
for the eyes to actually parse the headers.


 >
 > while this is a bit more effort in the man page, it should make things
 > clear for the reader.
 >
 > (the annotations can be terse, with a more complete citation of the
 > applicable standard in the NOTES or elsewhere).
 >
 > I'm not trying to be awkard here -- actually having man pages defining
 > key types and the relevant headers to include is a really good idea.

No problem.  I've already thought about this many times:
how to be as informative as possible,
without distracting from the main information.

 >
 >
 > Can we please alias all the actual type names to point to this page,
 > so that e.g., "man size_t" works?

We already have that :)

 >
 > (This might be considered overkill, so if others shoot the suggestion
 > down, fair enough -- in any case the alises could be added by a later
 > patch.)
 >
 > Cheers
 > ---Dave
 >

Cheers,

Alex

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Michael Kerrisk (man-pages)]

>  > Can we not just annotate each header listed with the originating
>  > standard, say:
>  >
>  > 	<stddef.h>	(C)
>  >
>  > 	<sys/types.h>	(POSIX)
>  > 	...		(POSIX)
>  > 	...
> 
> That may be a good idea; I've thought about doing that in the past;
> but also thought that it's still too much noise.
> Let's see what others think about it.

My thought is that maybe we can add this kind of info later,
providing we find a concise way to do it. But, for now, already
the info in the page is useful as is, and I don't want to stop
the momentum of Alex's work. So, for now, I think let's carry
on the current style.

> The downside is that it adds a lot of lines,
> being harder to read for types with too many headers (e.g., size_t).

That is also my concern.

Thanks,

Michael

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

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Dave Martin]

On Tue, Sep 29, 2020 at 04:52:18PM +0200, Alejandro Colomar wrote:
> Hi Dave,
> 
> On 2020-09-29 16:43, Dave Martin wrote:
> > On Tue, Sep 29, 2020 at 04:22:19PM +0200, Alejandro Colomar wrote:
> >> The previous format/wording for the includes wasn't very clear.
> >> Improve it a bit following Branden's proposal.
> >> It also helps reduce lines of code.
> >>
> >> Add a subsection in NOTES explaining the conventions used.
> >>
> >> Remove the comment for helping maintain the page,
> >> as the NOTES section is now clear enough.
> >>
> >> Reported-by: G. Branden Robinson <g.branden.robinson@gmail.com>
> >> Reported-by: Dave Martin <Dave.Martin@arm.com>
> >> Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> >> Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
> >> ---
> >>
> >> Hi Michael,
> >>
> >> After this patch, we're at a sync-point: no more pending patches from me.
> >>
> >> Tomorrow I'll go to the mountain, so you can have a small break from me
> :p
> >>
> >> Cheers,
> >>
> >> Alex
> >>
> >>
> >>   man7/system_data_types.7 | 302 +++++++++++++++------------------------
> >>   1 file changed, 119 insertions(+), 183 deletions(-)
> >>
> >> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> >> index af0c55c65..9cf67ee6f 100644
> >> --- a/man7/system_data_types.7
> >> +++ b/man7/system_data_types.7
> >> @@ -31,22 +31,7 @@ system_data_types \- overview of system data types
> >>   .\" 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.
> >> +.\"		* Include (see NOTES)
> >>   .\"
> >>   .\"		* Definition (no "Definition" header)
> >>   .\"			Only struct/union types will have definition;
> >> @@ -55,9 +40,10 @@ system_data_types \- overview of system data types
> >>   .\"		* Description (no "Description" header)
> >>   .\"			A few lines describing the type.
> >>   .\"
> >> -.\"		* Conforming to
> >> +.\"		* Bugs (if any)
> >> +.\"
> >> +.\"		* Conforming to (see NOTES)
> >>   .\"			Format: CXY and later; POSIX.1-XXXX and later.
> >> -.\"			Forget about pre-C99 C standards (i.e., C89/C90)
> >>   .\"
> >>   .\"		* Notes (optional)
> >>   .\"
> >> @@ -203,8 +189,8 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <stdio.h> ;
> >> -or
> >> +.IR <stdio.h> .
> >> +Alternatively,
> >>   .IR <wchar.h> .
> >>   .PP
> >>   An object type used for streams.
> >> @@ -269,19 +255,14 @@ type in this page.
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/types.h> ;
> >> -or
> >> -.I <grp.h>
> >> -or
> >> -.I <pwd.h>
> >> -or
> >> -.I <signal.h>
> >> -or
> >> -.I <stropts.h>
> >> -or
> >> -.I <sys/ipc.h>
> >> -or
> >> -.I <sys/stat.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <grp.h> ,
> >> +.IR <pwd.h> ,
> >> +.IR <signal.h> ,
> >> +.IR <stropts.h> ,
> >> +.IR <sys/ipc.h> ,
> >> +.IR <sys/stat.h> ,
> >>   or
> >>   .IR <unistd.h> .
> >>   .PP
> >> @@ -306,8 +287,8 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/types.h> ;
> >> -or
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >>   .IR <sys/resource.h> .
> >>   .PP
> >>   A type used to hold a general identifier.
> >> @@ -586,29 +567,19 @@ See also:
> >>   .RS
> >>   .br
> >>   Include
> >> -.IR <sys/types.h> ;
> >> -or
> >> -.I <fcntl.h>
> >> -or
> >> -.I <sched.h>
> >> -or
> >> -.I <signal.h>
> >> -or
> >> -.I <spawn.h>
> >> -or
> >> -.I <sys/msg.h>
> >> -or
> >> -.I <sys/sem.h>
> >> -or
> >> -.I <sys/shm.h>
> >> -or
> >> -.I <sys/wait.h>
> >> -or
> >> -.I <termios.h>
> >> -or
> >> -.I <time.h>
> >> -or
> >> -.I <unistd.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <fcntl.h> ,
> >> +.IR <sched.h> ,
> >> +.IR <signal.h> ,
> >> +.IR <spawn.h> ,
> >> +.IR <sys/msg.h> ,
> >> +.IR <sys/sem.h> ,
> >> +.IR <sys/shm.h> ,
> >> +.IR <sys/wait.h> ,
> >> +.IR <termios.h> ,
> >> +.IR <time.h> ,
> >> +.IR <unistd.h> ,
> >>   or
> >>   .IR <utmpx.h> .
> >>   .PP
> >> @@ -738,11 +709,10 @@ types in this page.
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <signal.h> ;
> >> -or
> >> -.I <aio.h>
> >> -or
> >> -.I <mqueue.h>
> >> +.IR <signal.h> .
> >> +Alternatively,
> >> +.IR <aio.h> ,
> >> +.IR <mqueue.h> ,
> >>   or
> >>   .IR <time.h> .
> >>   .PP
> >> @@ -787,8 +757,8 @@ structure in this page.
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <signal.h> ;
> >> -or
> >> +.IR <signal.h> .
> >> +Alternatively,
> >>   .IR <sys/wait.h> .
> >>   .PP
> >>   .EX
> >> @@ -823,9 +793,9 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <signal.h> ;
> >> -or
> >> -.I <spawn.h>
> >> +.IR <signal.h> .
> >> +Alternatively,
> >> +.IR <spawn.h> ,
> >>   or
> >>   .IR <sys/select.h> .
> >>   .PP
> >> @@ -886,55 +856,32 @@ in this page.
> >>   Include:
> >>   .I <stddef.h>
> >>   or
> >> -.IR <sys/types.h> ;
> >> -or
> >> -.I <aio.h>
> >> -or
> >> -.I <glob.h>
> >> -or
> >> -.I <grp.h>
> >> -or
> >> -.I <iconv.h>
> >> -or
> >> -.I <monetary.h>
> >> -or
> >> -.I <mqueue.h>
> >> -or
> >> -.I <ndbm.h>
> >> -or
> >> -.I <pwd.h>
> >> -or
> >> -.I <regex.h>
> >> -or
> >> -.I <search.h>
> >> -or
> >> -.I <signal.h>
> >> -or
> >> -.I <stdio.h>
> >> -or
> >> -.I <stdlib.h>
> >> -or
> >> -.I <string.h>
> >> -or
> >> -.I <strings.h>
> >> -or
> >> -.I <sys/mman.h>
> >> -or
> >> -.I <sys/msg.h>
> >> -or
> >> -.I <sys/sem.h>
> >> -or
> >> -.I <sys/shm.h>
> >> -or
> >> -.I <sys/socket.h>
> >> -or
> >> -.I <sys/uio.h>
> >> -or
> >> -.I <time.h>
> >> -or
> >> -.I <unistd.h>
> >> -or
> >> -.I <wchar.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <aio.h> ,
> >> +.IR <glob.h> ,
> >> +.IR <grp.h> ,
> >> +.IR <iconv.h> ,
> >> +.IR <monetary.h> ,
> >> +.IR <mqueue.h> ,
> >> +.IR <ndbm.h> ,
> >> +.IR <pwd.h> ,
> >> +.IR <regex.h> ,
> >> +.IR <search.h> ,
> >> +.IR <signal.h> ,
> >> +.IR <stdio.h> ,
> >> +.IR <stdlib.h> ,
> >> +.IR <string.h> ,
> >> +.IR <strings.h> ,
> >> +.IR <sys/mman.h> ,
> >> +.IR <sys/msg.h> ,
> >> +.IR <sys/sem.h> ,
> >> +.IR <sys/shm.h> ,
> >> +.IR <sys/socket.h> ,
> >> +.IR <sys/uio.h> ,
> >> +.IR <time.h> ,
> >> +.IR <unistd.h> ,
> >> +.IR <wchar.h> ,
> >>   or
> >>   .IR <wordexp.h> .
> >>   .PP
> >> @@ -1007,21 +954,15 @@ types in this page.
> >>   .RS
> >>   .br
> >>   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>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <aio.h> ,
> >> +.IR <monetary.h> ,
> >> +.IR <mqueue.h> ,
> >> +.IR <stdio.h> ,
> >> +.IR <sys/msg.h> ,
> >> +.IR <sys/socket.h> ,
> >> +.IR <sys/uio.h> ,
> >>   or
> >>   .IR <unistd.h> .
> >>   .PP
> >> @@ -1083,9 +1024,9 @@ types in this page.
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/types.h> ;
> >> -or
> >> -.I <sys/select.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <sys/select.h> ,
> >>   or
> >>   .IR <sys/time.h> .
> >>   .PP
> >> @@ -1110,23 +1051,17 @@ structure in this page.
> >>   .RS
> >>   .br
> >>   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>
> >> +.I <time.h>
> >>   or
> >> -.I <sys/time.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <sched.h> ,
> >> +.IR <sys/msg.h> ,
> >> +.IR <sys/select.h> ,
> >> +.IR <sys/sem.h> ,
> >> +.IR <sys/shm.h> ,
> >> +.IR <sys/stat.h> ,
> >> +.IR <sys/time.h> ,
> >>   or
> >>   .IR <utime.h> .
> >>   .PP
> >> @@ -1153,8 +1088,8 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/types.h> ;
> >> -or
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >>   .IR <time.h> .
> >>   .PP
> >>   Used for timer ID returned by
> >> @@ -1176,17 +1111,13 @@ See also:
> >>   .RS
> >>   .br
> >>   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>
> >> +.IR <time.h> .
> >> +Alternatively,
> >> +.IR <aio.h> ,
> >> +.IR <mqueue.h> ,
> >> +.IR <sched.h> ,
> >> +.IR <signal.h> ,
> >> +.IR <sys/select.h> ,
> >>   or
> >>   .IR <sys/stat.h> .
> >>   .PP
> >> @@ -1214,11 +1145,10 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/time.h> ;
> >> -or
> >> -.I <sys/resource.h>
> >> -or
> >> -.I <sys/select.h>
> >> +.IR <sys/time.h> .
> >> +Alternatively,
> >> +.IR <sys/resource.h> ,
> >> +.IR <sys/select.h> ,
> >>   or
> >>   .IR <utmpx.h> .
> >>   .PP
> >> @@ -1247,17 +1177,13 @@ See also:
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <sys/types.h> ;
> >> -or
> >> -.I <pwd.h>
> >> -or
> >> -.I <signal.h>
> >> -or
> >> -.I <stropts.h>
> >> -or
> >> -.I <sys/ipc.h>
> >> -or
> >> -.I <sys/stat.h>
> >> +.IR <sys/types.h> .
> >> +Alternatively,
> >> +.IR <pwd.h> ,
> >> +.IR <signal.h> ,
> >> +.IR <stropts.h> ,
> >> +.IR <sys/ipc.h> ,
> >> +.IR <sys/stat.h> ,
> >>   or
> >>   .IR <unistd.h> .
> >>   .PP
> >> @@ -1418,9 +1344,9 @@ types in this page.
> >>   .RS
> >>   .br
> >>   Include:
> >> -.IR <stdarg> ;
> >> -or
> >> -.I <stdio.h>
> >> +.IR <stdarg> .
> >> +Alternatively,
> >> +.IR <stdio.h> ,
> >>   or
> >>   .IR <wchar.h> .
> >>   .PP
> >> @@ -1473,6 +1399,16 @@ If the type has upper and lower limits,
> >>   the user should check that the value is within those limits,
> >>   before actually copying the value.
> >>   The example below shows how these conversions should be done.
> >> +.SS Conventions used in this page
> >> +In "Conforming to" we only concern ourselves with
> >> +C99 and later and POSIX.1-2001 and later.
> >> +Some types may be specified in earlier versions of one of these
> standards,
> >> +but in the interests of simplicity we omit details from earlier
> standards.
> >> +.PP
> >> +In "Include", we first note the "primary" header(s) that
> >> +define the type according to either the C or POSIX.1 standards.
> >> +Under "Alternatively", we note additional headers that
> >> +the standards specify shall define the type.
> >
> > While this is more informative, it still doesn't help the programmer
> > know which header(s) to use in a given situation.  I'd worry that people
> > may not read as far as the NOTES, or may not remember what's in there
> > when referring to the header lists.
> 
> I hope they do :)
> And if not, I hope that people will take the first one they see
> (and not go through some obscure alternative headers).
> 
> >
> > Can we not just annotate each header listed with the originating
> > standard, say:
> >
> > 	<stddef.h>	(C)
> >
> > 	<sys/types.h>	(POSIX)
> > 	...		(POSIX)
> > 	...
> 
> That may be a good idea; I've thought about doing that in the past;
> but also thought that it's still too much noise.
> Let's see what others think about it.
> 
> The downside is that it adds a lot of lines,
> being harder to read for types with too many headers (e.g., size_t).
> 
> It could also be done in the same line, but maybe it adds too much noise
> for the eyes to actually parse the headers.
> 
> 
> >
> > while this is a bit more effort in the man page, it should make things
> > clear for the reader.
> >
> > (the annotations can be terse, with a more complete citation of the
> > applicable standard in the NOTES or elsewhere).
> >
> > I'm not trying to be awkard here -- actually having man pages defining
> > key types and the relevant headers to include is a really good idea.
> 
> No problem.  I've already thought about this many times:
> how to be as informative as possible,
> without distracting from the main information.

OK

> > Can we please alias all the actual type names to point to this page,
> > so that e.g., "man size_t" works?
> 
> We already have that :)

Great :)

[...]

Cheers
---Dave

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Dave Martin]

On Tue, Sep 29, 2020 at 05:06:27PM +0200, Michael Kerrisk (man-pages) wrote:
> 
> >  > Can we not just annotate each header listed with the originating
> >  > standard, say:
> >  >
> >  > 	<stddef.h>	(C)
> >  >
> >  > 	<sys/types.h>	(POSIX)
> >  > 	...		(POSIX)
> >  > 	...
> > 
> > That may be a good idea; I've thought about doing that in the past;
> > but also thought that it's still too much noise.
> > Let's see what others think about it.
> 
> My thought is that maybe we can add this kind of info later,
> providing we find a concise way to do it. But, for now, already
> the info in the page is useful as is, and I don't want to stop
> the momentum of Alex's work. So, for now, I think let's carry
> on the current style.
> 
> > The downside is that it adds a lot of lines,
> > being harder to read for types with too many headers (e.g., size_t).
> 
> That is also my concern.

OK, that's fair -- I agree that the page makes a valuable contribution
already, so it makes sense to merge it in its current form and think
about improvements (if any are warranted) afterward.

Apologies for the noise!

Cheers
---Dave

Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES

[Alejandro Colomar]

On 2020-09-29 17:13, Dave Martin wrote:
> On Tue, Sep 29, 2020 at 05:06:27PM +0200, Michael Kerrisk (man-pages) wrote:
>>
>>>   > Can we not just annotate each header listed with the originating
>>>   > standard, say:
>>>   >
>>>   > 	<stddef.h>	(C)
>>>   >
>>>   > 	<sys/types.h>	(POSIX)
>>>   > 	...		(POSIX)
>>>   > 	...
>>>
>>> That may be a good idea; I've thought about doing that in the past;
>>> but also thought that it's still too much noise.
>>> Let's see what others think about it.
>>
>> My thought is that maybe we can add this kind of info later,
>> providing we find a concise way to do it. But, for now, already
>> the info in the page is useful as is, and I don't want to stop
>> the momentum of Alex's work. So, for now, I think let's carry
>> on the current style.
>>
>>> The downside is that it adds a lot of lines,
>>> being harder to read for types with too many headers (e.g., size_t).
>>
>> That is also my concern.
> 
> OK, that's fair -- I agree that the page makes a valuable contribution
> already, so it makes sense to merge it in its current form and think
> about improvements (if any are warranted) afterward.
> 
> Apologies for the noise!
> 
> Cheers
> ---Dave
> 


Hi Dave,

No problem, suggestions are welcome!
Actually, I want suggestions for that page.

Actually, I should apologize for the noise...
I don't know, but I may have sent a few hundred emails to this list in 
the past 4 weeks :p

Cheers,

Alex

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Joseph Myers]

On Fri, 18 Sep 2020, Paul Eggert wrote:

> On 9/18/20 7:34 AM, Florian Weimer via Libc-alpha wrote:
> > the length modifier for printf and scanf is z, commently used as
> > %zu or %zx (%zd is for ssize_t).
> 
> While %zd works for ssize_t in glibc, POSIX doesn't guarantee that it'll work,
> as ssize_t might not have the same width as size_t. (If memory serves this
> goes back to the bad old days when size_t was 64 bits and ssize_t 32 bits on
> some platforms.) So if we document %zd we should say it's a GNU extension to
> POSIX, or something like that.

%zd is for the signed type corresponding to size_t; that's in ISO C.  The 
GNU extension would be a guarantee that ssize_t is the signed type 
corresponding to size_t (if we do guarantee that).

-- 
Joseph S. Myers
joseph@codesourcery.com

Re: [PATCH 1/2] system_data_types.7: Document size_t

[Joseph Myers]

On Mon, 28 Sep 2020, Alejandro Colomar via Libc-alpha wrote:

> > To clarify, does POSIX _guarantee_ that all of those headers define this
> > type?  (I admit I'm too lazy to search through the POSIX standard for an
> > answer to this).
> 
> Yes, POSIX does guarantee that all those headers define the type.

For a lot of cases where a header contains a function using a type in its 
prototype, current POSIX requires that type to be defined in the header, 
but older POSIX permitted it (by virtue of the *_t reservation) but did 
not require it unless XSI extensions were enabled.

The preferred glibc practice in such cases where older POSIX permitted the 
definition and included functions using the type is not to make the 
definition of the type in the header conditional on the POSIX version / 
XSI extensions, but to enable the definition for all standards that 
include the relevant function.  (This simplifies the headers, and also 
simplifies the conform/ tests because they then don't need to handle 
testing for a declaration of a function without being able to write its 
type in the most straightforward way.)

The headers still need to include feature test macro conditionals and 
special handling where a header is required by some standard to declare a 
function without defining the corresponding type name.  (For example, ISO 
C does not permit <stdio.h> to define va_list, so the header has to use an 
implementation-namespace name for that type when declaring vprintf.)

-- 
Joseph S. Myers
joseph@codesourcery.com