man3: fix wrong/non-existent section references
cover man3: fix wrong/non-existent section references
Commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in many wrong section references.
Mostly, this is about references to no-longer-existent section NOTES, but there are some other issues as well, such as references to a wrong section, or a discussion which is now split in between two sections, etc.
This patch series tries to fix some of these issues in man3 section only (I haven't checked other section numbers).
Found accidentally when reading exec(3).
Kir Kolyshkin (11):
exec.3: fix section reference
posix_fallocate.3: fix section references
floor.3: fix section reference
ceil.3,rint.3,round.3: rm NOTES section
getdtablesize.3: fix section reference
readdir.3: fix section references
setjmp.3: fix section references
sigpause.3: fix section reference
stailq.3: fix section reference
strtok.3: fix section reference
strtod.3: fix wrong section reference
man/man3/ceil.3 | 4 ++-- man/man3/exec.3 | 2 +- man/man3/floor.3 | 2 +- man/man3/getdtablesize.3 | 2 +- man/man3/posix_fallocate.3 | 4 ++-- man/man3/readdir.3 | 8 ++++---- man/man3/rint.3 | 4 ++-- man/man3/round.3 | 4 ++-- man/man3/setjmp.3 | 6 +++--- man/man3/sigpause.3 | 2 +- man/man3/stailq.3 | 2 +- man/man3/strtod.3 | 2 +- man/man3/strtok.3 | 2 +- 13 files changed, 22 insertions(+), 22 deletions(-)
Signature · 1 line
2.45.2
PATCH 1/11 exec.3: fix section reference
There is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/exec.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/exec.3 +1 -1
@@ -120,7 +120,7 @@ .SS p - execlp(), execvp(), execvpe() .I confstr(_CS_PATH) (which typically returns the value "/bin:/usr/bin") and possibly also the current working directory; -see NOTES for further details. +see VERSIONS for further details. .P .BR execvpe () searches for the program using the value of
Signature · 1 line
2.45.2
PATCH 2/11 posix_fallocate.3: fix section references
In reply to Kir KolyshkinThere are references to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/posix_fallocate.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
man/man3/posix_fallocate.3 +2 -2
@@ -86,7 +86,7 @@ .SH ERRORS .I fd does not support this operation. This error code can be returned by C libraries that don't perform the -emulation shown in NOTES, such as musl libc. +emulation shown in CAVEATS, such as musl libc. .TP .B ESPIPE .I fd
@@ -106,7 +106,7 @@ .SH ATTRIBUTES T} Thread safety T{ .na .nh -MT-Safe (but see NOTES) +MT-Safe (but see CAVEATS) T} .TE .SH STANDARDS
Signature · 1 line
2.45.2
PATCH 3/11 floor.3: fix section reference
In reply to Kir KolyshkinThere is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/floor.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/floor.3 +1 -1
@@ -52,7 +52,7 @@ .SH RETURN VALUE itself is returned. .SH ERRORS No errors occur. -POSIX.1-2001 documents a range error for overflows, but see NOTES. +POSIX.1-2001 documents a range error for overflows, but see HISTORY. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
Signature · 1 line
2.45.2
Alejandro Colomar
maintainerRe: [PATCH 03/11] floor.3: fix section reference
Hi Kir,
Quoted 6 lines · Kir Kolyshkin
There is a reference to NOTES section, which no longer exists since the commit
4131356cd("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").Fixes 4131356cdSigned-off-by Kir Kolyshkin <[email protected]>
Thanks for the patch. In this page, I've noticed that we can remove the reference, since POSIX.1-2008 doesn't have that problem any more. I've applied an alternative patch instead:
<https://www.alejandro-colomar.es/src/alx/linux/man-pages/man-pages.git/commit/?h=contrib&id=c3049eef0ad06131609bb16a94475778f737b8c8>
Have a lovely day!
Alex
Quoted 20 lines
--- man/man3/floor.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)man/man3/floor.3 +1
-1@@ -52,7 +52,7 @@ .SH RETURN VALUE itself is returned. .SH ERRORS No errors occur. -POSIX.1-2001 documents a range error for overflows, but see NOTES. +POSIX.1-2001 documents a range error for overflows, but see HISTORY. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).Signature · 1 line
2.45.2
Signature · 1 line
<https://www.alejandro-colomar.es/>
PATCH 4/11 ceil.3,rint.3,round.3: rm NOTES section
In reply to Kir KolyshkinCommit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") removed the NOTES section from floor(3), moving the explanation of overflow errors to HISTORY.
The very same explanation is also there in ceil(3), rint(3), and round(3). Let's move it to HISTORY as well, for uniformity.
--- man/man3/ceil.3 | 4 ++-- man/man3/rint.3 | 4 ++-- man/man3/round.3 | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-)
man/man3/ceil.3 +2 -2
@@ -53,7 +53,7 @@ .SH RETURN VALUE itself is returned. .SH ERRORS No errors occur. -POSIX.1-2001 documents a range error for overflows, but see NOTES. +POSIX.1-2001 documents a range error for overflows, but see HISTORY. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
@@ -79,7 +79,7 @@ .SH HISTORY .I double also conforms to SVr4, 4.3BSD, C89. -.SH NOTES +.P SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno to
man/man3/rint.3 +2 -2
@@ -91,7 +91,7 @@ .SH RETURN VALUE itself is returned. .SH ERRORS No errors occur. -POSIX.1-2001 documents a range error for overflows, but see NOTES. +POSIX.1-2001 documents a range error for overflows, but see HISTORY. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
@@ -115,7 +115,7 @@ .SH STANDARDS C11, POSIX.1-2008. .SH HISTORY C99, POSIX.1-2001. -.SH NOTES +.P SUSv2 and POSIX.1-2001 contain text about overflow (which might set .I errno to
man/man3/round.3 +2 -2
@@ -56,7 +56,7 @@ .SH RETURN VALUE itself is returned. .SH ERRORS No errors occur. -POSIX.1-2001 documents a range error for overflows, but see NOTES. +POSIX.1-2001 documents a range error for overflows, but see HISTORY. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
@@ -78,7 +78,7 @@ .SH STANDARDS .SH HISTORY glibc 2.1. C99, POSIX.1-2001. -.SH NOTES +.P POSIX.1-2001 contains text about overflow (which might set .I errno to
Signature · 1 line
2.45.2
PATCH 5/11 getdtablesize.3: fix section reference
In reply to Kir KolyshkinThere is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/getdtablesize.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/getdtablesize.3 +1 -1
@@ -44,7 +44,7 @@ .SH ERRORS .BR getdtablesize () can return any of the errors described for .BR getrlimit (2); -see NOTES below. +see VERSIONS below. .SH ATTRIBUTES For an explanation of the terms used in this section, see .BR attributes (7).
Signature · 1 line
2.45.2
PATCH 6/11 readdir.3: fix section references
In reply to Kir KolyshkinThere are references to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
While at it, unify the "see XXX" style.
--- man/man3/readdir.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
man/man3/readdir.3 +4 -4
@@ -59,7 +59,7 @@ .SH DESCRIPTION and .IR d_ino . The other fields are unstandardized, and not present on all systems; -see NOTES below for some further details. +see VERSIONS. .P The fields of the .I dirent
@@ -85,7 +85,7 @@ .SH DESCRIPTION .I d_reclen This is the size (in bytes) of the returned record. This may not match the size of the structure definition shown above; -see NOTES. +see VERSIONS. .TP .I d_type This field contains a value indicating the file type,
@@ -137,8 +137,8 @@ .SH DESCRIPTION .BR DT_UNKNOWN . .TP .I d_name -This field contains the null terminated filename. -.IR "See NOTES" . +This field contains the null terminated filename; +see VERSIONS. .P The data returned by .BR readdir ()
Signature · 1 line
2.45.2
Alejandro Colomar
maintainerRe: [PATCH 06/11] readdir.3: fix section references
Hi Kir,
Quoted 3 lines · Kir Kolyshkin
There are references to NOTES section, which no longer exists since the commit
4131356cd("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
Hmmm, in this case, there's still a NOTES section. It's smaller, but still exists. This text will need to be different.
Have a lovely day!
Alex
Quoted 45 lines
While at it, unify the "see XXX" style.
Fixes 4131356cdSigned-off-by Kir Kolyshkin <[email protected]>--- man/man3/readdir.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)man/man3/readdir.3 +4
-4@@ -59,7 +59,7 @@ .SH DESCRIPTION and .IR d_ino . The other fields are unstandardized, and not present on all systems; -see NOTES below for some further details. +see VERSIONS. .P The fields of the .I dirent@@ -85,7 +85,7 @@ .SH DESCRIPTION .I d_reclen This is the size (in bytes) of the returned record. This may not match the size of the structure definition shown above; -see NOTES. +see VERSIONS. .TP .I d_type This field contains a value indicating the file type,@@ -137,8 +137,8 @@ .SH DESCRIPTION .BR DT_UNKNOWN . .TP .I d_name -This field contains the null terminated filename. -.IR "See NOTES" . +This field contains the null terminated filename; +see VERSIONS. .P The data returned by .BR readdir ()Signature · 1 line
2.45.2
Signature · 1 line
<https://www.alejandro-colomar.es/>
PATCH v2 6/11 readdir.3: fix wrong section references
There are references to NOTES section, but since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY: Reorganize sections") the relevant information is in VERSIONS.
While at it, unify the "see XXX" style.
--- man/man3/readdir.3 | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
man/man3/readdir.3 +4 -4
@@ -59,7 +59,7 @@ .SH DESCRIPTION and .IR d_ino . The other fields are unstandardized, and not present on all systems; -see NOTES below for some further details. +see VERSIONS. .P The fields of the .I dirent
@@ -85,7 +85,7 @@ .SH DESCRIPTION .I d_reclen This is the size (in bytes) of the returned record. This may not match the size of the structure definition shown above; -see NOTES. +see VERSIONS. .TP .I d_type This field contains a value indicating the file type,
@@ -137,8 +137,8 @@ .SH DESCRIPTION .BR DT_UNKNOWN . .TP .I d_name -This field contains the null terminated filename. -.IR "See NOTES" . +This field contains the null terminated filename; +see VERSIONS. .P The data returned by .BR readdir ()
Signature · 1 line
2.45.2
PATCH 7/11 setjmp.3: fix section references
In reply to Kir KolyshkinCommit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in a few problems with setjmp(3):
1. "Feature Test Macro Requirements for glibc" refers to NOTES, while those macros are now described in HISTORY.
2. The discussion about saving signal mask is now split between HISTORY and NOTES.
To fix all this, let's remove NOTES and fix references to point to HISTORY.
--- man/man3/setjmp.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
man/man3/setjmp.3 +3 -3
@@ -26,7 +26,7 @@ .SH SYNOPSIS .RE .P .BR setjmp (): -see NOTES. +see HISTORY. .P .BR sigsetjmp (): .nf
@@ -65,7 +65,7 @@ .SH DESCRIPTION was called and to restore ("rewind") the stack to its state at the time of the .BR setjmp () call. -In addition, and depending on the implementation (see NOTES), +In addition, and depending on the implementation (see HISTORY), the values of some other registers and the process signal mask may be restored to their state at the time of the .BR setjmp ()
@@ -201,7 +201,7 @@ .SH HISTORY with a nonzero .I savesigs argument. -.SH NOTES +.P .BR setjmp () and .BR longjmp ()
Signature · 1 line
2.45.2
Alejandro Colomar
maintainerRe: [PATCH 07/11] setjmp.3: fix section references
Hi Kir,
Quoted 41 lines · Kir Kolyshkin
Commit
4131356cd("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in a few problems with setjmp(3):1. "Feature Test Macro Requirements for glibc" refers to NOTES, while those macros are now described in HISTORY.
2. The discussion about saving signal mask is now split between HISTORY and NOTES.
To fix all this, let's remove NOTES and fix references to point to HISTORY.
Fixes 4131356cdSigned-off-by Kir Kolyshkin <[email protected]>--- man/man3/setjmp.3 | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)man/man3/setjmp.3 +2
-2@@ -26,7 +26,7 @@ .SH SYNOPSIS .RE .P .BR setjmp (): -see NOTES. +see HISTORY. .P .BR sigsetjmp (): .nf@@ -65,7 +65,7 @@ .SH DESCRIPTION was called and to restore ("rewind") the stack to its state at the time of the .BR setjmp () call. -In addition, and depending on the implementation (see NOTES), +In addition, and depending on the implementation (see HISTORY), the values of some other registers and the process signal mask may be restored to their state at the time of the .BR setjmp ()
man/man3/setjmp.3 .SH HISTORY · line 204
Quoted 5 lines
man/man3/setjmp.3 +1
-1@@ -201,7 +201,7 @@ .SH HISTORY with a nonzero .I savesigs argument. -.SH NOTES +.P
But the paragraph below is not about HISTORY. It's current stuff (which is why I kept it). How about saying "see NOTES and HISTORY"?
Cheers,
Alex
Quoted 6 lines
man/man3/setjmp.3 +0
-0.BR setjmp () and .BR longjmp ()Signature · 1 line
2.45.2
Signature · 1 line
<https://www.alejandro-colomar.es/>
PATCH v2 7/11 setjmp.3: fix section references
Commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in a few problems with setjmp(3):
1. "Feature Test Macro Requirements for glibc" refers to NOTES, while those macros are now described in HISTORY.
2. The discussion about saving signal mask is now split between HISTORY and NOTES.
Fix the references accordingly.
--- man/man3/setjmp.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
man/man3/setjmp.3 +2 -2
@@ -26,7 +26,7 @@ .SH SYNOPSIS .RE .P .BR setjmp (): -see NOTES. +see HISTORY. .P .BR sigsetjmp (): .nf
@@ -65,7 +65,7 @@ .SH DESCRIPTION was called and to restore ("rewind") the stack to its state at the time of the .BR setjmp () call. -In addition, and depending on the implementation (see NOTES), +In addition, and depending on the implementation (see NOTES and HISTORY), the values of some other registers and the process signal mask may be restored to their state at the time of the .BR setjmp ()
Signature · 1 line
2.45.2
Re: [PATCH v2 07/11] setjmp.3: fix section references
Hi Kir,
Quoted 6 lines · Kir Kolyshkin
Commit
4131356cd("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in a few problems with setjmp(3):1. "Feature Test Macro Requirements for glibc" refers to NOTES, while those macros are now described in HISTORY.
Quoted 7 lines
2. The discussion about saving signal mask is now split between HISTORY and NOTES.
Fix the references accordingly.
Fixes 4131356cdSigned-off-by Kir Kolyshkin <[email protected]>
I've applied both v2 06 and 07. Thanks for the revised patches.
Have a lovely night!
Alex
Quoted 29 lines
--- man/man3/setjmp.3 | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)man/man3/setjmp.3 +2
-2@@ -26,7 +26,7 @@ .SH SYNOPSIS .RE .P .BR setjmp (): -see NOTES. +see HISTORY. .P .BR sigsetjmp (): .nf@@ -65,7 +65,7 @@ .SH DESCRIPTION was called and to restore ("rewind") the stack to its state at the time of the .BR setjmp () call. -In addition, and depending on the implementation (see NOTES), +In addition, and depending on the implementation (see NOTES and HISTORY), the values of some other registers and the process signal mask may be restored to their state at the time of the .BR setjmp ()Signature · 1 line
2.45.2
Signature · 1 line
<https://www.alejandro-colomar.es/>
PATCH 8/11 sigpause.3: fix section reference
In reply to Kir KolyshkinThere is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
Currently, the relevant information is kind of split between VERSIONS and HISTORY, so it's not very clear to which section refer to. My guess is VERSIONS is somewhat more relevant.
--- man/man3/sigpause.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/sigpause.3 +1 -1
@@ -13,7 +13,7 @@ .SH SYNOPSIS .nf .B #include <signal.h> .P -.BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see NOTES) */" +.BI "[[deprecated]] int sigpause(int " sigmask "); /* BSD (but see VERSIONS) */" .P .BI "[[deprecated]] int sigpause(int " sig "); /* POSIX.1 / SysV / UNIX 95 */" .fi
Signature · 1 line
2.45.2
PATCH 9/11 stailq.3: fix section reference
In reply to Kir KolyshkinThere is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/stailq.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/stailq.3 +1 -1
@@ -96,7 +96,7 @@ .SH SYNOPSIS .\" .BI " STAILQ_ENTRY " NAME ); .fi .IR Note : -Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see NOTES. +Identical macros prefixed with SIMPLEQ instead of STAILQ exist; see VERSIONS. .SH DESCRIPTION These macros define and operate on singly linked tail queues. .P
Signature · 1 line
2.45.2
PATCH 10/11 strtok.3: fix section reference
In reply to Kir KolyshkinThere is a reference to NOTES section, which no longer exists since the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections").
--- man/man3/strtok.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/strtok.3 +1 -1
@@ -131,7 +131,7 @@ .SH DESCRIPTION .I str should point to the string to be parsed, and the value of .I *saveptr -is ignored (but see NOTES). +is ignored (but see VERSIONS). In subsequent calls, .I str should be NULL, and
Signature · 1 line
2.45.2
PATCH 11/11 strtod.3: fix wrong section reference
In reply to Kir KolyshkinSince the commit 4131356cd ("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections"), the discussion about n-char-sequence refers to NOTES, while the relevant information is now in VERSIONS.
--- man/man3/strtod.3 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
man/man3/strtod.3 +1 -1
@@ -94,7 +94,7 @@ .SH DESCRIPTION where .I n-char-sequence specifies in an implementation-dependent -way the type of NAN (see NOTES). +way the type of NAN (see VERSIONS). .SH RETURN VALUE These functions return the converted value, if any. .P
Signature · 1 line
2.45.2
Alejandro Colomar
maintainerHi Kir,
Quoted 8 lines · Kir Kolyshkin
Commit
4131356cd("man*/, man-pages.7: VERSIONS, STANDARDS, HISTORY:
Reorganize sections") results in many wrong section references.Mostly, this is about references to no-longer-existent section NOTES, but there are some other issues as well, such as references to a wrong section, or a discussion which is now split in between two sections, etc.
Quoted 4 lines
This patch series tries to fix some of these issues in man3 section only (I haven't checked other section numbers).
Found accidentally when reading exec(3).
Thanks for the patches!
Quoted 4 lines
Kir Kolyshkin (11):
exec.3: fix section reference
posix_fallocate.3: fix section references
floor.3: fix section reference
Quoted 8 lines
ceil.3,rint.3,round.3: rm NOTES section
getdtablesize.3: fix section reference
readdir.3: fix section references
setjmp.3: fix section references
sigpause.3: fix section reference
stailq.3: fix section reference
strtok.3: fix section reference
strtod.3: fix wrong section reference
I've applied the following patches:
01, 02, 04, 05, 08, 09, 10, 11
I've applied an alternative patch to 03, so it's no longer needed.
Patches 06 and 07 need some more work, and I've provided comments on each of them.
Have a lovely day!
Alex
Quoted 20 lines
man/man3/ceil.3 | 4 ++-- man/man3/exec.3 | 2 +- man/man3/floor.3 | 2 +- man/man3/getdtablesize.3 | 2 +- man/man3/posix_fallocate.3 | 4 ++-- man/man3/readdir.3 | 8 ++++---- man/man3/rint.3 | 4 ++-- man/man3/round.3 | 4 ++-- man/man3/setjmp.3 | 6 +++--- man/man3/sigpause.3 | 2 +- man/man3/stailq.3 | 2 +- man/man3/strtod.3 | 2 +- man/man3/strtok.3 | 2 +- 13 files changed, 22 insertions(+), 22 deletions(-)Signature · 1 line
2.45.2
Signature · 1 line
<https://www.alejandro-colomar.es/>