Skip to contentSkip to conversation

Document size_t

PATCH Superseded Alejandro Colomar 7 participants 34 messages Sep 18, 2020 – Sep 30, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

cover Document size_t

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
Signature · 1 line
2.28.0
#1 lore raw

PATCH 1/2 system_data_types.7: Document size_t

---
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)
man7/system_data_types.7 +99 -4
index 84fea85b9..041e7e243 100644
@@ -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
Signature · 1 line
2.28.0
#2 lore raw

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

* Alejandro Colomar via Libc-alpha:

man7/system_data_types.7 See also: · line 158

Quoted 7 lines
man7/system_data_types.7 +7 -0
+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

Signature · 3 lines
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
#3 lore raw

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

Hello Florian,

Quoted 11 lines · Florian Weimer

* Alejandro Colomar via Libc-alpha:

man7/system_data_types.7 See also: · line 158

Quoted 7 lines
man7/system_data_types.7 +7 -0
+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.

:-)

Quoted 1 line

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.

Quoted 10 lines · Michael Kerrisk (man-pages)
Quoted 10 lines
Quoted 4 lines
Quoted 1 line

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.

Quoted 6 lines
Quoted 1 line
         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.

Quoted 2 lines · Florian Weimer

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?.

Quoted 3 lines

Florian

Thanks,

Alex

#4 lore raw

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

* Alejandro Colomar:

Quoted 6 lines

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.

Quoted 7 lines · Florian Weimer
Quoted 2 lines

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

Signature · 3 lines
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
#5 lore raw

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

In reply to Florian Weimer
Quoted 2 lines · Florian Weimer via Libc-alpha

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.

#6 lore raw

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

* Paul Eggert:

Quoted 9 lines · Florian Weimer via Libc-alpha
Quoted 2 lines

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

Signature · 3 lines
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
#7 lore raw

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

In reply to Paul Eggert
Quoted 9 lines · Paul Eggert
Quoted 2 lines · Florian Weimer via Libc-alpha

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).

Signature · 2 lines
Joseph S. Myers
[email protected]
#8 lore raw

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

In reply to Alejandro Colomar
Quoted 1 line · Alejandro Colomar

Merged.

Thanks,

Michael

Quoted 126 lines
---
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)
man7/system_data_types.7 +99 -4
index 84fea85b9..041e7e243 100644
@@ -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
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#9 lore raw

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

In reply to Alejandro Colomar

man7/system_data_types.7

Quoted 9 lines · Alejandro Colomar
---
 man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 99 insertions(+), 4 deletions(-)
man7/system_data_types.7 +0 -0
index 84fea85b9..041e7e243 100644

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

man7/system_data_types.7 See also: · line 99

Quoted 9 lines
man7/system_data_types.7 +5 -0
@@ -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.

man7/system_data_types.7 See also: · line 112

Quoted 13 lines
man7/system_data_types.7 +13 -0
+.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

#10 lore raw

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

Hi Dave,

Quoted 20 lines · Dave Martin

man7/system_data_types.7

Quoted 9 lines · Alejandro Colomar
---
  man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++--
  1 file changed, 99 insertions(+), 4 deletions(-)
man7/system_data_types.7 +0 -0
index 84fea85b9..041e7e243 100644

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

Quoted 11 lines

man7/system_data_types.7 See also: · line 99

Quoted 9 lines
man7/system_data_types.7 +5 -0
@@ -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

Quoted 24 lines

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

man7/system_data_types.7 See also: · line 112

Quoted 13 lines
man7/system_data_types.7 +13 -0
+.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

#11 lore raw

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

Hi, Alex!

Quoted 9 lines · Alejandro Colomar
Quoted 1 line

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

#12 lore raw

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

Quoted 12 lines · G. Branden Robinson

Hi, Alex!

Quoted 9 lines · Alejandro Colomar
Quoted 1 line

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.

Quoted 4 lines

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

#13 lore raw

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

Hi Dave!

Quoted 11 lines · Dave Martin
Quoted 10 lines · G. Branden Robinson

Hi, Alex!

Quoted 7 lines · Alejandro Colomar
Quoted 1 line

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.

Quoted 6 lines
Quoted 2 lines
Quoted 2 lines

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.

Quoted 5 lines

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

Quoted 7 lines
Quoted 4 lines

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?

Quoted 4 lines

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

Quoted 11 lines

(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

#14 lore raw

RFC 1/1 system_data_types.7: wfix + ffix

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

---

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(-)
man7/system_data_types.7 +113 -172
index 16930985e..dc4a3bae4 100644
@@ -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
Signature · 1 line
2.28.0
#15 lore raw

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

Quoted 5 lines · Alejandro Colomar

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

Quoted 7 lines

---

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.

Quoted 29 lines

Thanks,

Alex

 man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 172 deletions(-)
man7/system_data_types.7 +4 -7
index 16930985e..dc4a3bae4 100644
@@ -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

man7/system_data_types.7 system_data_types \- overview of system data types · line 50

Quoted 10 lines
man7/system_data_types.7 +4 -0
+.\"			   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.

Quoted 23 lines
man7/system_data_types.7 +2 -7
 .\"
 .\"		* 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>

man7/system_data_types.7 type in this page. · line 273

Quoted 10 lines
man7/system_data_types.7 +2 -8
-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

#16 lore raw

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

Hi Dave,

Quoted 10 lines · Dave Martin
Quoted 9 lines · Alejandro Colomar

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

---

Hi,

Quoted 7 lines
Quoted 3 lines

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.

Quoted 45 lines
Quoted 30 lines

Thanks,

Alex

  man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
  1 file changed, 113 insertions(+), 172 deletions(-)
man7/system_data_types.7 +4 -7
index 16930985e..dc4a3bae4 100644
@@ -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

man7/system_data_types.7 system_data_types \- overview of system data types · line 50

Quoted 10 lines
man7/system_data_types.7 +4 -0
+.\"			   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.

Quoted 3 lines

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.

Quoted 29 lines
Quoted 29 lines
man7/system_data_types.7 +2 -12
  .\"
  .\"		* 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
Quoted 8 lines

man7/system_data_types.7 type in this page. · line 273

Quoted 5 lines
man7/system_data_types.7 +2 -3
-.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.

Quoted 11 lines

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:

Quoted 8 lines
	[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

Quoted 4 lines

Cheers
---Dave

#17 lore raw

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

In reply to Dave Martin

Hi Alex, Dave,

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

Quoted 10 lines · Dave Martin
Quoted 9 lines · Alejandro Colomar

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

---

Hi,

Quoted 7 lines
Quoted 3 lines

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.

Quoted 38 lines
Quoted 23 lines
 man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 172 deletions(-)
man7/system_data_types.7 +4 -7
index 16930985e..dc4a3bae4 100644
@@ -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

man7/system_data_types.7 system_data_types \- overview of system data types · line 50

Quoted 10 lines
man7/system_data_types.7 +4 -0
+.\"			   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.

Quoted 3 lines

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.)

Quoted 47 lines
Quoted 23 lines
man7/system_data_types.7 +2 -7
 .\"
 .\"		* 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>

man7/system_data_types.7 type in this page. · line 273

Quoted 10 lines
man7/system_data_types.7 +2 -8
-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:

Quoted 6 lines
	[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

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#18 lore raw

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

Hi Michael & Dave,

Quoted 19 lines · Michael Kerrisk (man-pages)

Hi Alex, Dave,

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

Quoted 14 lines · Dave Martin
Quoted 12 lines · Alejandro Colomar

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

---

Hi,

What do you think about this?

Would you change something?

Quoted 8 lines
Quoted 3 lines

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 :)

Quoted 8 lines

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.

Quoted 5 lines

* 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.

Quoted 5 lines

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.

Quoted 4 lines

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.

Quoted 39 lines
Quoted 39 lines
Quoted 24 lines
  man7/system_data_types.7 | 285 ++++++++++++++++-----------------------
  1 file changed, 113 insertions(+), 172 deletions(-)
man7/system_data_types.7 +4 -7
index 16930985e..dc4a3bae4 100644
@@ -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

man7/system_data_types.7 system_data_types \- overview of system data types · line 50

Quoted 10 lines
man7/system_data_types.7 +4 -0
+.\"			   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.

Quoted 6 lines
Quoted 3 lines

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.

Quoted 55 lines
Quoted 48 lines
Quoted 24 lines
man7/system_data_types.7 +2 -7
  .\"
  .\"		* 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>

man7/system_data_types.7 type in this page. · line 273

Quoted 10 lines
man7/system_data_types.7 +2 -8
-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:

Quoted 6 lines
	[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.)

Quoted 6 lines

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,

Quoted 5 lines

Thanks,

Michael

Thanks,

Alex

#19 lore raw

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

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.

---

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(-)
man7/system_data_types.7 +119 -183
index af0c55c65..9cf67ee6f 100644
@@ -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.
Signature · 1 line
2.28.0
#20 lore raw

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

Quoted 457 lines · 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.

---

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(-)
man7/system_data_types.7 +109 -183
index af0c55c65..9cf67ee6f 100644
@@ -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.

man7/system_data_types.7 If the type has upper and lower limits, · line 1411

Quoted 10 lines
man7/system_data_types.7 +10 -0
+.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

#21 lore raw

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

Hi Dave,

Quoted 465 lines · Dave Martin
Quoted 464 lines · 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.

---

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(-)
man7/system_data_types.7 +116 -183
index af0c55c65..9cf67ee6f 100644
@@ -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
Quoted 8 lines

man7/system_data_types.7 If the type has upper and lower limits, · line 1411

Quoted 3 lines
man7/system_data_types.7 +3 -0
+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).

Quoted 9 lines

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.

Quoted 9 lines

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.

Quoted 4 lines

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 :)

Quoted 8 lines

(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

#22 lore raw

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

Quoted 6 lines
Quoted 6 lines

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

	<stddef.h>	(C)
Quoted 7 lines
Quoted 3 lines
	<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.

Quoted 2 lines

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

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#23 lore raw

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

Quoted 20 lines · Michael Kerrisk (man-pages)
Quoted 6 lines
Quoted 6 lines

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

	<stddef.h>	(C)
Quoted 7 lines
Quoted 3 lines
	<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.

Quoted 4 lines
Quoted 2 lines

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

#24 lore raw

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

Quoted 26 lines · Dave Martin
Quoted 20 lines · Michael Kerrisk (man-pages)
Quoted 6 lines
Quoted 6 lines

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

	<stddef.h>	(C)
Quoted 7 lines
Quoted 3 lines
	<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.

Quoted 4 lines
Quoted 2 lines

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.

Quoted 9 lines

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

#25 lore raw

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

In reply to Alejandro Colomar
Quoted 512 lines · Alejandro Colomar

Hi Dave,

Quoted 16 lines · Dave Martin
Quoted 15 lines · 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.

---

Quoted 5 lines
Quoted 5 lines

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

Quoted 433 lines
Quoted 433 lines

Cheers,

Alex

  man7/system_data_types.7 | 302 +++++++++++++++------------------------
  1 file changed, 119 insertions(+), 183 deletions(-)
man7/system_data_types.7 +109 -183
index af0c55c65..9cf67ee6f 100644
@@ -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
Quoted 8 lines

man7/system_data_types.7 If the type has upper and lower limits, · line 1405

Quoted 8 lines
man7/system_data_types.7 +4 -0
@@ -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,

Quoted 1 line

man7/system_data_types.7 If the type has upper and lower limits, · line 1406

Quoted 1 line
man7/system_data_types.7 +1 -0
+but in the interests of simplicity we omit details from earlier

standards.

Quoted 10 lines

man7/system_data_types.7 If the type has upper and lower limits, · line 1411

Quoted 5 lines
man7/system_data_types.7 +5 -0
+.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).

Quoted 9 lines

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.

Quoted 7 lines

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).

Quoted 6 lines
Quoted 2 lines

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

Quoted 4 lines
Quoted 2 lines

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

#26 lore raw

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

In reply to Alejandro Colomar
Quoted 5 lines · Alejandro Colomar via Libc-alpha
Quoted 3 lines

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.)

Signature · 2 lines
Joseph S. Myers
[email protected]
#27 lore raw

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

In reply to Dave Martin

Hi Dave,

Quoted 15 lines · Dave Martin
Quoted 12 lines · G. Branden Robinson

Hi, Alex!

Quoted 9 lines · Alejandro Colomar
Quoted 1 line

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.

Quoted 6 lines

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.

Quoted 7 lines
Quoted 4 lines

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.

Quoted 2 lines

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

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#28 lore raw

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

In reply to G. Branden Robinson

Hi Branden,

Quoted 18 lines · G. Branden Robinson

Hi, Alex!

Quoted 9 lines · Alejandro Colomar
Quoted 1 line

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.

Quoted 8 lines

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

#30 lore raw

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

Quoted 1 line · Alejandro Colomar

Merged.

Thanks,

Michael

Quoted 13 lines
---
 man3/size_t.3 | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 man3/size_t.3
man3/size_t.3 new file +1 -0
new file mode 100644
index 000000000..db50c0f09
@@ -0,0 +1 @@
+.so man7/system_data_types.7
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#31 lore raw
In reply to Alejandro Colomar
Quoted 7 lines · 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...

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.

Quoted 2 lines

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

Quoted 9 lines

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
Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#32 lore raw
Quoted 4 lines · Michael Kerrisk (man-pages)

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.

Quoted 6 lines
Quoted 4 lines

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

#33 lore raw

* Alejandro Colomar:

Quoted 6 lines
Quoted 3 lines
Quoted 2 lines

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

Signature · 3 lines
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