[PATCH] pthread_atfork.3: wfix.

[PATCH] pthread_atfork.3: wfix.

[enh]

Clarify that the pthread_atfork() callback list is a global, not
per-thread.

The use of "this thread" implied to some readers that pthread_atfork()
maintained per-thread lists of callbacks. Given that the next sentence
already explains that the callbacks are run in the context of the thread
that calls fork(), I actually think it would be fine not to mention
threads at all in the earlier sentence, but for now I've gone with what
I think was intended to be written.
---
 man3/pthread_atfork.3 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
index b727cb48e..3e61e797f 100644
--- a/man3/pthread_atfork.3
+++ b/man3/pthread_atfork.3
@@ -39,7 +39,7 @@ The
 .BR pthread_atfork ()
 function registers fork handlers that are to be executed when
 .BR fork (2)
-is called by this thread.
+is called by any thread in a process.
 The handlers are executed in the context of the thread that calls
 .BR fork (2).
 .PP
-- 
2.34.0.rc0.344.g81b53c2807-goog

Re: [PATCH] pthread_atfork.3: wfix.

[Florian Weimer]

> diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
> index b727cb48e..3e61e797f 100644
> --- a/man3/pthread_atfork.3
> +++ b/man3/pthread_atfork.3
> @@ -39,7 +39,7 @@ The
>  .BR pthread_atfork ()
>  function registers fork handlers that are to be executed when
>  .BR fork (2)
> -is called by this thread.
> +is called by any thread in a process.
>  The handlers are executed in the context of the thread that calls
>  .BR fork (2).
>  .PP

There's another confusing “thread” reference further below:
“pthread_atfork() may be called multiple times by a thread, to register
multiple handlers for each phase.”  I think that should be replaced by
“process” for clarity.

Thanks,
Florian

Re: [PATCH] pthread_atfork.3: wfix.

[Alejandro Colomar (man-pages)]

Hi,

On 11/9/21 23:27, enh wrote:
 > Clarify that the pthread_atfork() callback list is a global, not
 > per-thread.
 >
 > The use of "this thread" implied to some readers that pthread_atfork()
 > maintained per-thread lists of callbacks. Given that the next sentence
 > already explains that the callbacks are run in the context of the thread
 > that calls fork(), I actually think it would be fine not to mention
 > threads at all in the earlier sentence, but for now I've gone with what
 > I think was intended to be written.
 > ---
 >   man3/pthread_atfork.3 | 2 +-
 >   1 file changed, 1 insertion(+), 1 deletion(-)

Could you please sign your patch?

<https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>

On 11/10/21 09:11, Florian Weimer wrote:
>> diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
>> index b727cb48e..3e61e797f 100644
>> --- a/man3/pthread_atfork.3
>> +++ b/man3/pthread_atfork.3
>> @@ -39,7 +39,7 @@ The
>>   .BR pthread_atfork ()
>>   function registers fork handlers that are to be executed when
>>   .BR fork (2)
>> -is called by this thread.
>> +is called by any thread in a process.
>>   The handlers are executed in the context of the thread that calls
>>   .BR fork (2).
>>   .PP
> 
> There's another confusing “thread” reference further below:
> “pthread_atfork() may be called multiple times by a thread, to register
> multiple handlers for each phase.”  I think that should be replaced by
> “process” for clarity.

Also, if you could also fix that line reported by Florian in the same 
patch, it would be great.

Thanks!

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] pthread_atfork.3: wfix.

[enh]

done; sorry, i didn't realize Signed-off-by was for the original author too!

Florian's comment made me read through the *whole* page now, so i've
fixed a few more places that seemed a bit confusing too. v2 inlined
here...

From 92f3e61c8d61045448e6e94b9fb59817a5e07748 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 9 Nov 2021 14:20:32 -0800
Subject: [PATCH] pthread_atfork.3: wfix.

Clarify that the pthread_atfork() callback list is a global, not
per-thread.

The use of "this thread" implied to some readers that pthread_atfork()
maintained per-thread lists of callbacks. Given that the next sentence
already explains that the callbacks are run in the context of the thread
that calls fork(), I actually think it would be fine not to mention
threads at all in the earlier sentence, but for now I've gone with what
I think was intended to be written.

This patch also attempts to clarify other references to "thread",
and fixes a trivial typo "form" instead of "fork".

Signed-off-by: Elliott Hughes <enh@google.com>
---
 man3/pthread_atfork.3 | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
index b727cb48e..12a1492b6 100644
--- a/man3/pthread_atfork.3
+++ b/man3/pthread_atfork.3
@@ -39,14 +39,14 @@ The
 .BR pthread_atfork ()
 function registers fork handlers that are to be executed when
 .BR fork (2)
-is called by this thread.
+is called by any thread in a process.
 The handlers are executed in the context of the thread that calls
 .BR fork (2).
 .PP
 Three kinds of handler can be registered:
 .IP * 3
 .IR prepare
-specifies a handler that is executed before
+specifies a handler that is executed in the parent process before
 .BR fork (2)
 processing starts.
 .IP *
@@ -70,8 +70,8 @@ On success,
 returns zero.
 On error, it returns an error number.
 .BR pthread_atfork ()
-may be called multiple times by a thread,
-to register multiple handlers for each phase.
+may be called multiple times by a process
+to register additional handlers.
 The handlers for each phase are called in a specified order: the
 .I prepare
 handlers are called in reverse order of registration; the
@@ -82,7 +82,7 @@ handlers are called in the order of registration.
 .SH ERRORS
 .TP
 .B ENOMEM
-Could not allocate memory to record the form handler entry.
+Could not allocate memory to record the fork handler list entry.
 .SH CONFORMING TO
 POSIX.1-2001, POSIX.1-2008.
 .SH NOTES
@@ -92,7 +92,7 @@ is called in a multithreaded process,
 only the calling thread is duplicated in the child process.
 The original intention of
 .BR pthread_atfork ()
-was to allow the calling thread to be returned to a consistent state.
+was to allow the child process to be returned to a consistent state.
 For example, at the time of the call to
 .BR fork (2),
 other threads may have locked mutexes that are visible in the
-- 
2.34.0.rc1.387.gb447b232ab-goog



On Thu, Nov 11, 2021 at 1:49 PM Alejandro Colomar (man-pages)
<alx.manpages@gmail.com> wrote:
>
> Hi,
>
> On 11/9/21 23:27, enh wrote:
>  > Clarify that the pthread_atfork() callback list is a global, not
>  > per-thread.
>  >
>  > The use of "this thread" implied to some readers that pthread_atfork()
>  > maintained per-thread lists of callbacks. Given that the next sentence
>  > already explains that the callbacks are run in the context of the thread
>  > that calls fork(), I actually think it would be fine not to mention
>  > threads at all in the earlier sentence, but for now I've gone with what
>  > I think was intended to be written.
>  > ---
>  >   man3/pthread_atfork.3 | 2 +-
>  >   1 file changed, 1 insertion(+), 1 deletion(-)
>
> Could you please sign your patch?
>
> <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#developer-s-certificate-of-origin-1-1>
>
> On 11/10/21 09:11, Florian Weimer wrote:
> >> diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
> >> index b727cb48e..3e61e797f 100644
> >> --- a/man3/pthread_atfork.3
> >> +++ b/man3/pthread_atfork.3
> >> @@ -39,7 +39,7 @@ The
> >>   .BR pthread_atfork ()
> >>   function registers fork handlers that are to be executed when
> >>   .BR fork (2)
> >> -is called by this thread.
> >> +is called by any thread in a process.
> >>   The handlers are executed in the context of the thread that calls
> >>   .BR fork (2).
> >>   .PP
> >
> > There's another confusing “thread” reference further below:
> > “pthread_atfork() may be called multiple times by a thread, to register
> > multiple handlers for each phase.”  I think that should be replaced by
> > “process” for clarity.
>
> Also, if you could also fix that line reported by Florian in the same
> patch, it would be great.
>
> Thanks!
>
> Alex
>
> --
> Alejandro Colomar
> Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
> http://www.alejandro-colomar.es/

Re: [PATCH] pthread_atfork.3: wfix.

[Alejandro Colomar (man-pages)]

Hi Elliot,

On 11/11/21 23:42, enh wrote:
> done; sorry, i didn't realize Signed-off-by was for the original author too!
> 
> Florian's comment made me read through the *whole* page now, so i've
> fixed a few more places that seemed a bit confusing too. v2 inlined
> here...
> 
>  From 92f3e61c8d61045448e6e94b9fb59817a5e07748 Mon Sep 17 00:00:00 2001
> From: Elliott Hughes <enh@google.com>
> Date: Tue, 9 Nov 2021 14:20:32 -0800
> Subject: [PATCH] pthread_atfork.3: wfix.
> 
> Clarify that the pthread_atfork() callback list is a global, not
> per-thread.
> 
> The use of "this thread" implied to some readers that pthread_atfork()
> maintained per-thread lists of callbacks. Given that the next sentence
> already explains that the callbacks are run in the context of the thread
> that calls fork(), I actually think it would be fine not to mention
> threads at all in the earlier sentence, but for now I've gone with what
> I think was intended to be written.
> 
> This patch also attempts to clarify other references to "thread",
> and fixes a trivial typo "form" instead of "fork".
> 
> Signed-off-by: Elliott Hughes <enh@google.com>

Patch applied!

Thanks,
Alex

> ---
>   man3/pthread_atfork.3 | 12 ++++++------
>   1 file changed, 6 insertions(+), 6 deletions(-)
> 
> diff --git a/man3/pthread_atfork.3 b/man3/pthread_atfork.3
> index b727cb48e..12a1492b6 100644
> --- a/man3/pthread_atfork.3
> +++ b/man3/pthread_atfork.3
> @@ -39,14 +39,14 @@ The
>   .BR pthread_atfork ()
>   function registers fork handlers that are to be executed when
>   .BR fork (2)
> -is called by this thread.
> +is called by any thread in a process.
>   The handlers are executed in the context of the thread that calls
>   .BR fork (2).
>   .PP
>   Three kinds of handler can be registered:
>   .IP * 3
>   .IR prepare
> -specifies a handler that is executed before
> +specifies a handler that is executed in the parent process before
>   .BR fork (2)
>   processing starts.
>   .IP *
> @@ -70,8 +70,8 @@ On success,
>   returns zero.
>   On error, it returns an error number.
>   .BR pthread_atfork ()
> -may be called multiple times by a thread,
> -to register multiple handlers for each phase.
> +may be called multiple times by a process
> +to register additional handlers.
>   The handlers for each phase are called in a specified order: the
>   .I prepare
>   handlers are called in reverse order of registration; the
> @@ -82,7 +82,7 @@ handlers are called in the order of registration.
>   .SH ERRORS
>   .TP
>   .B ENOMEM
> -Could not allocate memory to record the form handler entry.
> +Could not allocate memory to record the fork handler list entry.
>   .SH CONFORMING TO
>   POSIX.1-2001, POSIX.1-2008.
>   .SH NOTES
> @@ -92,7 +92,7 @@ is called in a multithreaded process,
>   only the calling thread is duplicated in the child process.
>   The original intention of
>   .BR pthread_atfork ()
> -was to allow the calling thread to be returned to a consistent state.
> +was to allow the child process to be returned to a consistent state.
>   For example, at the time of the call to
>   .BR fork (2),
>   other threads may have locked mutexes that are visible in the
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

Re: [PATCH] pthread_atfork.3: wfix.

[Alejandro Colomar]

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

Hi enh,

On 7/25/22 23:00, enh wrote:
> interestingly, i see that commit in the log: 
> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/man3/pthread_atfork.3 <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/man3/pthread_atfork.3>
> 
> but it doesn't seem to have made it to the web? 
> https://man7.org/linux/man-pages/man3/pthread_atfork.3.html 
> <https://man7.org/linux/man-pages/man3/pthread_atfork.3.html>
> 
> is there a known issue with man7.org <http://man7.org> being out of date?

man7.org shows the latest release.  Since we haven't released since 
man-pages 5.13, there are many changes in the git repo that aren't found 
in that website.

Cheers,

Alex


-- 
Alejandro Colomar
<http://www.alejandro-colomar.es/>

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

Re: [PATCH] pthread_atfork.3: wfix.

[enh]

On Tue, Jul 26, 2022 at 4:06 AM Alejandro Colomar
<alx.manpages@gmail.com> wrote:
>
> Hi enh,
>
> On 7/25/22 23:00, enh wrote:
> > interestingly, i see that commit in the log:
> > https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/man3/pthread_atfork.3 <https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/log/man3/pthread_atfork.3>
> >
> > but it doesn't seem to have made it to the web?
> > https://man7.org/linux/man-pages/man3/pthread_atfork.3.html
> > <https://man7.org/linux/man-pages/man3/pthread_atfork.3.html>
> >
> > is there a known issue with man7.org <http://man7.org> being out of date?
>
> man7.org shows the latest release.  Since we haven't released since
> man-pages 5.13, there are many changes in the git repo that aren't found
> in that website.

oh, i didn't know that (in part because i have a local git clone and
set $MANPATH!), but that would explain a lot! is there anything i can
read on the background to this? in particular: is the problem
technical or political or financial? (hopefully it's not health, given
that 5.13 would be "early covid times"?)

> Cheers,
>
> Alex
>
>
> --
> Alejandro Colomar
> <http://www.alejandro-colomar.es/>