3p page wording

3p page wording

[enh]

is it a requirement that the 3p pages only contain text that's
explicitly in POSIX? the siginfo_t::si_addr description on
system_data_types.7 (which is what people see if they `man siginfo_t`)
says "Address of faulting instruction", which isn't true for all
signals, and caused enough confusion for the ART maintainers that they
came to me as Android's libc maintainer for an adjudication. meanwhile
the sigaction.2 page says "Memory location which caused fault" which
seems much more helpful.

i _was_ going to send you a patch, but then i checked
https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
which has the same unfortunate "Address of faulting instruction"
wording. at which point i assume you want me to file an Austin Group
bug (which i'll do anyway:
https://www.austingroupbugs.net/view.php?id=1775), and presumably wait
for POSIX's wording to improve before changing system_data_types.7?

Re: 3p page wording

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1485 bytes --]

Hi enh,

On 2023-09-13 21:58, enh wrote:
> is it a requirement that the 3p pages only contain text that's
> explicitly in POSIX?

Yes, I guess.

> the siginfo_t::si_addr description on
> system_data_types.7 (which is what people see if they `man siginfo_t`)
> says "Address of faulting instruction", which isn't true for all
> signals, and caused enough confusion for the ART maintainers that they
> came to me as Android's libc maintainer for an adjudication. meanwhile
> the sigaction.2 page says "Memory location which caused fault" which
> seems much more helpful.

siginfo_t(3type), aka system_data_types(7), isn't a POSIX page, so
we can patch it if you want.

I'd also move the types to their own pages and have system_data_types(7)
be a link to intro(3) (until we have an intro(3type)).

> 
> i _was_ going to send you a patch, but then i checked
> https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html
> which has the same unfortunate "Address of faulting instruction"
> wording. at which point i assume you want me to file an Austin Group
> bug (which i'll do anyway:
> https://www.austingroupbugs.net/view.php?id=1775),

Thanks.

> and presumably wait
> for POSIX's wording to improve before changing system_data_types.7?

Nah, we can improve siginfo_t(3type) already.  Feel free to send a patch.

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

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

Re: 3p page wording

[Alejandro Colomar]

[-- Attachment #1.1: Type: text/plain, Size: 1164 bytes --]

On 2023-09-13 23:50, Alejandro Colomar wrote:
> Hi enh,
> 
> On 2023-09-13 21:58, enh wrote:
>> is it a requirement that the 3p pages only contain text that's
>> explicitly in POSIX?
> 
> Yes, I guess.
> 
>> the siginfo_t::si_addr description on
>> system_data_types.7 (which is what people see if they `man siginfo_t`)
>> says "Address of faulting instruction", which isn't true for all
>> signals, and caused enough confusion for the ART maintainers that they
>> came to me as Android's libc maintainer for an adjudication. meanwhile
>> the sigaction.2 page says "Memory location which caused fault" which
>> seems much more helpful.
> 
> siginfo_t(3type), aka system_data_types(7), isn't a POSIX page, so
> we can patch it if you want.
> 
> I'd also move the types to their own pages and have system_data_types(7)
> be a link to intro(3) (until we have an intro(3type)).

I've done this.  Please check if you approve these patches:

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=contrib>

Cheers,
Alex

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5


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

Re: 3p page wording

[enh]

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

(sorry, didn't get chance to get back to this until now. as penance,
i've caught up with a couple of other outstanding man7 patches too!)

thanks for doing the major cleanup. attached is my trivial change on
top of that.


On Wed, Sep 13, 2023 at 4:33 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> On 2023-09-13 23:50, Alejandro Colomar wrote:
> > Hi enh,
> >
> > On 2023-09-13 21:58, enh wrote:
> >> is it a requirement that the 3p pages only contain text that's
> >> explicitly in POSIX?
> >
> > Yes, I guess.
> >
> >> the siginfo_t::si_addr description on
> >> system_data_types.7 (which is what people see if they `man siginfo_t`)
> >> says "Address of faulting instruction", which isn't true for all
> >> signals, and caused enough confusion for the ART maintainers that they
> >> came to me as Android's libc maintainer for an adjudication. meanwhile
> >> the sigaction.2 page says "Memory location which caused fault" which
> >> seems much more helpful.
> >
> > siginfo_t(3type), aka system_data_types(7), isn't a POSIX page, so
> > we can patch it if you want.
> >
> > I'd also move the types to their own pages and have system_data_types(7)
> > be a link to intro(3) (until we have an intro(3type)).
>
> I've done this.  Please check if you approve these patches:
>
> <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=contrib>
>
> Cheers,
> Alex
>
> --
> <http://www.alejandro-colomar.es/>
> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
>

[-- Attachment #2: 0001-system_data_types.7-clarify-si_addr-field.patch --]
[-- Type: application/octet-stream, Size: 1158 bytes --]

From 2371b944d4c1d9b6751e595529537b19a6fa5f56 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 19 Sep 2023 14:16:54 -0700
Subject: [PATCH] system_data_types.7: clarify si_addr field.

This patch reuses the clearer text from sigaction.2 instead.

I've also filed https://www.austingroupbugs.net/view.php?id=1775
to improve POSIX's wording here to not be SIGILL-specific.

Signed-off-by: Elliott Hughes <enh@google.com>
---
 man7/system_data_types.7 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
index 1840a40fa..d4538ce5b 100644
--- a/man7/system_data_types.7
+++ b/man7/system_data_types.7
@@ -124,7 +124,7 @@ typedef struct {
     int      si_code;   /* Signal code */
     pid_t    si_pid;    /* Sending process ID */
     uid_t    si_uid;    /* Real user ID of sending process */
-    void    *si_addr;   /* Address of faulting instruction */
+    void    *si_addr;   /* Memory location which caused fault */
     int      si_status; /* Exit value or signal */
     union sigval si_value;  /* Signal value */
 } siginfo_t;
-- 
2.42.0.459.ge4e396fd5e-goog

Re: 3p page wording

[Alejandro Colomar]

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

Hi Elliott,

On Tue, Sep 19, 2023 at 02:21:04PM -0700, enh wrote:
> (sorry, didn't get chance to get back to this until now. as penance,
> i've caught up with a couple of other outstanding man7 patches too!)
> 
> thanks for doing the major cleanup. attached is my trivial change on
> top of that.

Thanks for reviewing!  Patch applied.

Cheers,
Alex

> 
> 
> On Wed, Sep 13, 2023 at 4:33 PM Alejandro Colomar <alx@kernel.org> wrote:
> >
> > On 2023-09-13 23:50, Alejandro Colomar wrote:
> > > Hi enh,
> > >
> > > On 2023-09-13 21:58, enh wrote:
> > >> is it a requirement that the 3p pages only contain text that's
> > >> explicitly in POSIX?
> > >
> > > Yes, I guess.
> > >
> > >> the siginfo_t::si_addr description on
> > >> system_data_types.7 (which is what people see if they `man siginfo_t`)
> > >> says "Address of faulting instruction", which isn't true for all
> > >> signals, and caused enough confusion for the ART maintainers that they
> > >> came to me as Android's libc maintainer for an adjudication. meanwhile
> > >> the sigaction.2 page says "Memory location which caused fault" which
> > >> seems much more helpful.
> > >
> > > siginfo_t(3type), aka system_data_types(7), isn't a POSIX page, so
> > > we can patch it if you want.
> > >
> > > I'd also move the types to their own pages and have system_data_types(7)
> > > be a link to intro(3) (until we have an intro(3type)).
> >
> > I've done this.  Please check if you approve these patches:
> >
> > <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/?h=contrib>
> >
> > Cheers,
> > Alex
> >
> > --
> > <http://www.alejandro-colomar.es/>
> > GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
> >



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

Re: 3p page wording

[Florian Weimer]

> is it a requirement that the 3p pages only contain text that's
> explicitly in POSIX?

The current 3p terms do not allow modification.

<https://git.kernel.org/pub/scm/docs/man-pages/man-pages-posix.git/tree/man-pages-posix-2017/POSIX-COPYRIGHT>

Thanks,
Florian