kevent behavior

[Konstantin Belousov]

On Sun, Mar 29, 2015 at 07:22:07PM +0200, Jilles Tjoelker wrote:
> Given that the special case for fcntl() is mentioned in
> pthread_testcancel(3) (only a cancellation point if cmd is F_SETLKW),
> the same should be done for kevent().
> 
> Looks good to me otherwise.

Below is the update.  I will commit after some tests finish.

diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2
index 93223f1..c5e8caf 100644
--- a/lib/libc/sys/kqueue.2
+++ b/lib/libc/sys/kqueue.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 18, 2014
+.Dd March 29, 2015
 .Dt KQUEUE 2
 .Os
 .Sh NAME
@@ -41,7 +41,7 @@
 .Fn kqueue "void"
 .Ft int
 .Fn kevent "int kq" "const struct kevent *changelist" "int nchanges" "struct kevent *eventlist" "int nevents" "const struct timespec *timeout"
-.Fn EV_SET "&kev" ident filter flags fflags data udata
+.Fn EV_SET "kev" ident filter flags fflags data udata
 .Sh DESCRIPTION
 The
 .Fn kqueue
@@ -550,6 +550,16 @@ On return,
 .Va fflags
 contains the users defined flags in the lower 24 bits.
 .El
+.Sh CANCELLATION BEHAVIOUR
+If
+.Fa nevents
+is non-zero, i.e. the function is potentially blocking, the call
+is a cancellation point.
+Otherwise, i.e. if
+.Fa nevents
+is zero, the call is not cancellable.
+Cancellation can only occur before any changes are made to the kqueue,
+or when the call was blocked and no changes to the queue were requested.
 .Sh RETURN VALUES
 The
 .Fn kqueue
@@ -620,6 +630,8 @@ The specified descriptor is invalid.
 .It Bq Er EINTR
 A signal was delivered before the timeout expired and before any
 events were placed on the kqueue for return.
+.It Bq Er EINTR
+A cancellation request was delivered to the thread, but not yet handled.
 .It Bq Er EINVAL
 The specified time limit or filter is invalid.
 .It Bq Er ENOENT
@@ -634,6 +646,14 @@ sysctl.
 .It Bq Er ESRCH
 The specified process to attach to does not exist.
 .El
+.Pp
+When
+.Fn kevent
+call fails with
+.Er EINTR
+error, all changes in the
+.Fa changelist
+have been applied.
 .Sh SEE ALSO
 .Xr aio_error 2 ,
 .Xr aio_read 2 ,
@@ -643,6 +663,7 @@ The specified process to attach to does not exist.
 .Xr select 2 ,
 .Xr sigaction 2 ,
 .Xr write 2 ,
+.Xr pthread_setcancelstate 3 ,
 .Xr signal 3
 .Sh HISTORY
 The
diff --git a/share/man/man3/pthread_testcancel.3 b/share/man/man3/pthread_testcancel.3
index ef6a1c1..a6b27f6 100644
--- a/share/man/man3/pthread_testcancel.3
+++ b/share/man/man3/pthread_testcancel.3
@@ -1,5 +1,5 @@
 .\" $FreeBSD$
-.Dd June 11, 2013
+.Dd March 29, 2015
 .Dt PTHREAD_TESTCANCEL 3
 .Os
 .Sh NAME
@@ -107,6 +107,7 @@ functions:
 .Fn close ,
 .Fn creat ,
 .Fn fsync ,
+.Fn kevent ,
 .Fn mq_receive ,
 .Fn mq_send ,
 .Fn mq_timedreceive ,
@@ -147,12 +148,20 @@ functions:
 .Fn waitpid ,
 .Fn write ,
 .Fn writev .
+.Pp
 The
 .Fn fcntl
 function is a cancellation point if
 .Fa cmd
 is
 .Dv F_SETLKW .
+.Pp
+The
+.Fn kevent
+function is a cancellation point if it is potentially blocking,
+i.e. when the
+.Fa nevents
+argument  is non-zero.
 .Sh RETURN VALUES
 If successful, the
 .Fn pthread_setcancelstate