Document size_t
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
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
@@ -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
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
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
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
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Florian WeimerQuoted 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.
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_tin glibc, POSIX doesn't guarantee that it'll work, asssize_tmight not have the same width assize_t. (If memory serves this goes back to the bad old days whensize_twas 64 bits andssize_t32 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
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Paul EggertQuoted 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_tin glibc, POSIX doesn't guarantee that it'll work, asssize_tmight not have the same width assize_t. (If memory serves this goes back to the bad old days whensize_twas 64 bits andssize_t32 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]
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Alejandro ColomarQuoted 1 line · Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
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@@ -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/
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Alejandro Colomarman7/system_data_types.7
Quoted 9 lines · Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>--- man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 4 deletions(-)man7/system_data_types.7 +0
-0
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
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
Signed-off-by Alejandro Colomar <[email protected]>--- man7/system_data_types.7 | 103 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 4 deletions(-)man7/system_data_types.7 +0
-0The distinction might not be worth highlighting here, but types like
size_tare 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> +orWhere 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
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
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
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
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
@@ -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
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.
Reported-by G. Branden Robinson <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>
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@@ -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
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.
Reported-by G. Branden Robinson <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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 typeman7/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
Re: [RFC] system_data_types.7: wfix + ffix
In reply to Dave MartinHi 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.
Reported-by G. Branden Robinson <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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 typeman7/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/
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.
Reported-by G. Branden Robinson <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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 typeman7/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
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
@@ -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
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.Reported-by G. Branden Robinson <[email protected]>Reported-by Dave Martin <[email protected]>Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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
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.Reported-by G. Branden Robinson <[email protected]>Reported-by Dave Martin <[email protected]>Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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
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/
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
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
Re: [PATCH v2] system_data_types.7: Improve "Include" wording and format, and explain it in NOTES
In reply to Alejandro ColomarQuoted 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.Reported-by G. Branden Robinson <[email protected]>Reported-by Dave Martin <[email protected]>Reported-by Michael Kerrisk <[email protected]>Signed-off-by Alejandro Colomar <[email protected]>---
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@@ -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> . .PPQuoted 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 thesestandards,
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 earlierstandards.
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
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Alejandro ColomarQuoted 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]
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to Dave MartinHi 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/
Re: [PATCH 1/2] system_data_types.7: Document size_t
In reply to G. Branden RobinsonHi 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_tInclude: <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
PATCH 2/2 size_t.3: New link to new documented type in system_data_types(7)
In reply to Alejandro Colomar--- 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
@@ -0,0 +1 @@ +.so man7/system_data_types.7
Signature · 1 line
2.28.0
Re: [PATCH 2/2] size_t.3: New link to new documented type in system_data_types(7)
Quoted 1 line · Alejandro Colomar
Signed-off-by Alejandro Colomar <[email protected]>
Merged.
Thanks,
Michael
Quoted 13 lines
--- man3/size_t.3 | 1 + 1 file changed, 1 insertion(+) create mode 100644 man3/size_t.3man3/size_t.3 new file +1
-0@@ -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/
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_tIt'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: Documentsize_t
size_t.3: New link to new documented type insystem_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/
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
* 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