[PATCH] Fix pthread_cancel manual page

[Scott Lamb <slamb at slamb dot org>]

The pthread_cancel manual page says that LinuxThreads is not integrated 
enough to implement cancellation points in the system library. I believe 
that hasn't been true for some time. This patch updates the bugs section 
to read "None." (None known, anyway.)

I moved the workaround suggestion to a "HISTORY" section. I also noted 
that it was not a reliable workaround - it contained a race condition.

And I added a "NOTES" section noting that cancellation is not very 
portable currently. (I just filed three bugs against OS X. Their 
cancellation support is completely worthless. I believe a lot of other 
systems are little better.)

Sorry if it's stylistically off; this is my first manual page patch.

I'm assuming updates to the LinuxThreads manual pages are still 
desirable. Is that true, now that NPTL is around? It seems NPTL has none 
of its own manual pages, and hopefully the LinuxThreads stuff applies in 
general to NPTL.

Also, would this be the appropriate page to talk about the C++ 
cancellation behavior? I don't see it mentioned anywhere in the manual. 
I especially wonder because it differs between LinuxThreads and NPTL.

Thanks,
Scott Lamb

Index: linuxthreads/man/pthread_cancel.man
===================================================================
RCS file: /cvs/glibc/libc/linuxthreads/man/pthread_cancel.man,v
retrieving revision 1.1
diff -u -r1.1 pthread_cancel.man
--- linuxthreads/man/pthread_cancel.man	11 Mar 1998 12:42:23 -0000	1.1
+++ linuxthreads/man/pthread_cancel.man	24 Dec 2003 06:16:45 -0000
@@ -128,19 +128,19 @@
 
 .SH BUGS
 
+None.
+
+.SH HISTORY
+
 POSIX specifies that a number of system calls (basically, all
 system calls that may block, such as !read!(2), !write!(2), !wait!(2),
 etc.) and library functions that may call these system calls (e.g.
-!fprintf!(3)) are cancellation points.  LinuxThreads is not yet
-integrated enough with the C library to implement this, and thus none
-of the C library functions is a cancellation point.
-
-For system calls at least, there is a workaround. Cancellation
-requests are transmitted to the target thread by sending it a
-signal. That signal will interrupt all blocking system calls, causing
-them to return immediately with the !EINTR! error. So, checking for
-cancellation during a !read! system call, for instance, can be
-achieved as follows:
+!fprintf!(3)) are cancellation points.  Historically, LinuxThreads was
+not integrated enough with the C library to implement this, and thus none
+of the C library functions were cancellation points.
+
+There is no reliable workaround. Formerly, this manual page advocated code
+like this:
 
 .RS
 .ft 3
@@ -153,3 +153,18 @@
 .LP
 .RE
 .fi
+
+Which mostly worked, because cancellation requests are transmitted to the
+target by sending it a signal. That signal will interrupt all blocking
+system calls, causing them to return immediately with the !EINTR! error.
+However, it contains a race condition. If the signal is delivered after the
+!pthread_testcancel!(3) and before the !read!(2) enters kernel space, the
+cancellation will be delayed until !read!(2) returns for other reasons.
+
+Fortunately, modern systems do not suffer from this problem.
+
+.SH NOTES
+
+Support for thread cancellation varies widely from system to system,
+despite standardization. Portable programs should use this feature with
+caution.