Document various changes to kq:

    - new EV_SET macro,
    - NOTE_LOWAT option for low water marks on read/write filters,
    - NOTE_REVOKE for filesystem unmounting (and revoke() calls)
    - improved API for EVFILT_AIO

1 files changed, 44 insertions, 10 deletions

diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2
index 1787a6e..b05833d 100644
--- a/lib/libc/sys/kqueue.2
+++ b/lib/libc/sys/kqueue.2
@@ -41,6 +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
 .Sh DESCRIPTION
 .Fn kqueue
 provides a generic method of notifying the user when an event
@@ -114,6 +115,10 @@ structure.  The same array may be used for the
 and 
 .Fa eventlist .
 .Pp
+.Fn EV_SET
+is a macro which is provided for ease of initializing a
+kevent structure.
+.Pp
 The
 .Va kevent
 structure is defined as:
@@ -199,6 +204,7 @@ Takes a descriptor as the identifier, and returns whenever
 there is data available to read.
 The behavior of the filter is slightly different depending
 on the descriptor type.
+.Pp
 .Bl -tag -width 2n
 .It Sockets
 Sockets which have previously been passed to
@@ -208,13 +214,25 @@ return when there is an incoming connection pending.
 contains the size of the listen backlog.
 .Pp
 Other socket descriptors return when there is data to be read,
-subject to the SO_RCVLOWAT value of the socket buffer.
+subject to the
+.Dv SO_RCVLOWAT
+value of the socket buffer.
+This may be overridden with a per-filter low water mark at the
+time the filter is added by setting the 
+NOTE_LOWAT 
+flag in 
+.Va fflags ,
+and specifying the new low water mark in
+.Va data .
+On return,
 .Va data
 contains the number of bytes in the socket buffer.
 .Pp
 If the read direction of the socket has shutdown, then the filter
 also sets EV_EOF in
-.Va flags .
+.Va flags ,
+and returns the socket error (if any) in 
+.Va fflags .
 It is possible for EOF to be returned (indicating the connection is gone)
 while there is still data pending in the socket buffer.
 .It Vnodes
@@ -242,21 +260,33 @@ will contain the amount of space remaining in the write buffer.
 The filter will set EV_EOF when the reader disconnects, and for
 the fifo case, this may be cleared by use of EV_CLEAR.
 Note that this filter is not supported for vnodes.
+.Pp
+For sockets, the low water mark and socket error handling is 
+identical to the EVFILT_READ case.
 .It EVFILT_AIO
-A kevent structure is initialized, with
-.Va ident
-containing the descriptor of the kqueue that the event should be
-attached to.  The address of the kevent structure is then placed in the
-.Va aio_lio_opcode
-field of the AIO request, and the aio_* function is then called.
-The event will be registered with the specified kqueue, and the
+The sigevent portion of the AIO request is filled in, with
+.Va sigev_notify_kqueue 
+containing the descriptor of the kqueue that the event should
+be attached to,
+.Va sigev_value
+containing the udata value, and 
+.Va sigev_notify
+set to SIGEV_EVENT.
+When the aio_* function is called, the event will be registered
+with the specified kqueue, and the
 .Va ident
 argument set to the
 .Fa struct aiocb
 returned by the aio_* function.
 The filter returns under the same conditions as aio_error.
 .Pp
-NOTE: this interface is unstable and subject to change.
+Alternatively, a kevent structure may be initialized, with 
+.Va ident
+containing the descriptor of the the kqueue, and the
+address of the kevent structure placed in the
+.Va aio_lio_opcode
+field of the AIO request.  However, this approach will not work on
+architectures with 64-bit pointers, and should be considered depreciated.
 .It EVFILT_VNODE
 Takes a file descriptor as the identifier and the events to watch for in 
 .Va fflags ,
@@ -276,6 +306,10 @@ The file referenced by the descriptor had its attributes changed.
 The link count on the file changed.
 .It NOTE_RENAME
 The file referenced by the descriptor was renamed.
+.It NOTE_REVOKE
+Access to the file was revoked via 
+.Xr revoke 2
+or the underlying fileystem was unmounted.
 .El
 .Pp
 On return,