Re: [PATCH] pthread_atfork.3: wfix.

enh
2021-11-11T22:43:10Z

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/