[PATCH] pthread_kill.3: Update to match POSIX.

[enh <enh@google.com>]

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

POSIX removed ESRCH years ago.

In resolving http://austingroupbugs.net/view.php?id=1214 it was made
clear that callers can't rely on using signal 0 to test for the
continued existence of a thread. Update the man page to make it clearer
that this doesn't generally work (even if it sometimes seems to).

See also the long explanation of why this is the case (and how to fix
your code) here:

https://android.googlesource.com/platform/bionic/+/master/docs/status.md#invalid-handling-targetsdkversion-o
---
 man3/pthread_kill.3 | 25 +++++++++----------------
 1 file changed, 9 insertions(+), 16 deletions(-)

diff --git a/man3/pthread_kill.3 b/man3/pthread_kill.3
index e70e2669e..fb27afd24 100644
--- a/man3/pthread_kill.3
+++ b/man3/pthread_kill.3
@@ -56,10 +56,6 @@ to
 a thread in the same process as the caller.
 The signal is asynchronously directed to
 .IR thread .
-.PP
-If
-.I sig
-is 0, then no signal is sent, but error checking is still performed.
 .SH RETURN VALUE
 On success,
 .BR pthread_kill ()
@@ -93,26 +89,23 @@ this action will affect the whole process.
 .PP
 The glibc implementation of
 .BR pthread_kill ()
-gives an error
-.RB ( EINVAL )
+gives the error
+.B EINVAL
 on attempts to send either of the real-time signals
 used internally by the NPTL threading implementation.
 See
 .BR nptl (7)
 for details.
 .PP
-POSIX.1-2008 recommends that if an implementation detects the use
-of a thread ID after the end of its lifetime,
+The glibc implementation of
 .BR pthread_kill ()
-should return the error
-.BR ESRCH .
-The glibc implementation returns this error in the cases where
-an invalid thread ID can be detected.
-But note also that POSIX says that an attempt to use a thread ID whose
-lifetime has ended produces undefined behavior,
-and an attempt to use an invalid thread ID in a call to
+tries to give the error
+.B ESRCH
+on attempts to use an invalid thread ID, but this isn't always possible.
+An attempt to use an invalid thread ID in a call to
 .BR pthread_kill ()
-can, for example, cause a segmentation fault.
+can, for example, cause a segmentation fault. Android is stricter, and will
+always abort when a pthread function is given an invalid thread ID.
 .SH SEE ALSO
 .BR kill (2),
 .BR sigaction (2),
-- 
2.24.0.rc1.363.gb1bccd3e3d-goog

[-- Attachment #2: 0001-pthread_kill.3-Update-to-match-POSIX.patch --]
[-- Type: text/x-patch, Size: 2484 bytes --]

From 656249792d1782e2d8ca581663ee88b19181b084 Mon Sep 17 00:00:00 2001
From: Elliott Hughes <enh@google.com>
Date: Tue, 12 Nov 2019 12:19:52 -0800
Subject: [PATCH] pthread_kill.3: Update to match POSIX.

POSIX removed ESRCH years ago.

In resolving http://austingroupbugs.net/view.php?id=1214 it was made
clear that callers can't rely on using signal 0 to test for the
continued existence of a thread. Update the man page to make it clearer
that this doesn't generally work (even if it sometimes seems to).

See also the long explanation of why this is the case (and how to fix
your code) here:

https://android.googlesource.com/platform/bionic/+/master/docs/status.md#invalid-handling-targetsdkversion-o
---
 man3/pthread_kill.3 | 25 +++++++++----------------
 1 file changed, 9 insertions(+), 16 deletions(-)

diff --git a/man3/pthread_kill.3 b/man3/pthread_kill.3
index e70e2669e..fb27afd24 100644
--- a/man3/pthread_kill.3
+++ b/man3/pthread_kill.3
@@ -56,10 +56,6 @@ to
 a thread in the same process as the caller.
 The signal is asynchronously directed to
 .IR thread .
-.PP
-If
-.I sig
-is 0, then no signal is sent, but error checking is still performed.
 .SH RETURN VALUE
 On success,
 .BR pthread_kill ()
@@ -93,26 +89,23 @@ this action will affect the whole process.
 .PP
 The glibc implementation of
 .BR pthread_kill ()
-gives an error
-.RB ( EINVAL )
+gives the error
+.B EINVAL
 on attempts to send either of the real-time signals
 used internally by the NPTL threading implementation.
 See
 .BR nptl (7)
 for details.
 .PP
-POSIX.1-2008 recommends that if an implementation detects the use
-of a thread ID after the end of its lifetime,
+The glibc implementation of
 .BR pthread_kill ()
-should return the error
-.BR ESRCH .
-The glibc implementation returns this error in the cases where
-an invalid thread ID can be detected.
-But note also that POSIX says that an attempt to use a thread ID whose
-lifetime has ended produces undefined behavior,
-and an attempt to use an invalid thread ID in a call to
+tries to give the error
+.B ESRCH
+on attempts to use an invalid thread ID, but this isn't always possible.
+An attempt to use an invalid thread ID in a call to
 .BR pthread_kill ()
-can, for example, cause a segmentation fault.
+can, for example, cause a segmentation fault. Android is stricter, and will
+always abort when a pthread function is given an invalid thread ID.
 .SH SEE ALSO
 .BR kill (2),
 .BR sigaction (2),
-- 
2.24.0.rc1.363.gb1bccd3e3d-goog