svn commit: r360406 - in stable: 11/lib/libc/sys 12/lib/libc/sys

[Kyle Evans]

Author: kevans
Date: Mon Apr 27 22:43:24 2020
New Revision: 360406
URL: https://svnweb.freebsd.org/changeset/base/360406

Log:
  MFC r360182-r360183: kqueue(2): add note about EV_RECEIPT
  
  r360182:
  kqueue(2): add a note about EV_RECEIPT
  
  In the below-referenced PR, a case is attached of a simple reproducer that
  exhibits suboptimal behavior: EVFILT_READ and EVFILT_WRITE being set in the
  same kevent(2) call will only honor the first one. This is, in-fact, how
  it's supposed to work.
  
  A read of the manpage leads me to believe we could be more clear about this;
  right now there's a logical leap to make in the relevant statement: "When
  passed as input, it forces EV_ERROR to always be returned." -- the logical
  leap being that this indicates the caller should have allocated space for
  the change to be returned with EV_ERROR indicated in the events, or
  subsequent filters will get dropped on the floor.
  
  Another possible workaround that accomplishes similar effect without needing
  space for all events is just setting EV_RECEIPT on the final change being
  passed in; if any errored before it, the kqueue would not be drained. If we
  made it to the final change with EV_RECEIPT set, then we would return that
  one with EV_ERROR and still not drain the kqueue. This would seem to not be
  all that advisable.
  
  r360183:
  kqueue(2): de-vandalize the random sentence in the middle
  
  A last minute change appears to have inadvertently vandalized unrelated
  parts of the manpage with the date. =-(
  
  PR:		229741

Modified:
  stable/12/lib/libc/sys/kqueue.2
Directory Properties:
  stable/12/   (props changed)

Changes in other areas also in this revision:
Modified:
  stable/11/lib/libc/sys/kqueue.2
Directory Properties:
  stable/11/   (props changed)

Modified: stable/12/lib/libc/sys/kqueue.2
==============================================================================
--- stable/12/lib/libc/sys/kqueue.2	Mon Apr 27 22:34:45 2020	(r360405)
+++ stable/12/lib/libc/sys/kqueue.2	Mon Apr 27 22:43:24 2020	(r360406)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 27, 2018
+.Dd April 21, 2020
 .Dt KQUEUE 2
 .Os
 .Sh NAME
@@ -233,6 +233,11 @@ to always be returned.
 When a filter is successfully added the
 .Va data
 field will be zero.
+Note that if this flag is encountered and there is no remaining space in
+.Fa eventlist
+to hold the
+.Dv EV_ERROR
+event, then subsequent changes will not get processed.
 .It Dv EV_ONESHOT
 Causes the event to return only the first occurrence of the filter
 being triggered.