From 14fc48b64b190c94e94ffdc2b8c77f49633c9d73 Mon Sep 17 00:00:00 2001
From: asomers <asomers@ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f>
Date: Mon, 31 Jul 2017 22:36:03 +0000
Subject: [PATCH] Clarify usage of aio(4) with kqueue(2)

Reviewed by:	jhb
MFC after:	3 weeks
Differential Revision:	https://reviews.freebsd.org/D11299


git-svn-id: svn://svn.freebsd.org/base/stable/10@321829 ccf9f872-aa2e-dd11-9fc8-001c23d0bc1f
---
 lib/libc/sys/kqueue.2 | 37 +++++++++++--------------------------
 share/man/man4/aio.4  | 20 ++++++++++++++++++--
 2 files changed, 29 insertions(+), 28 deletions(-)

diff --git a/lib/libc/sys/kqueue.2 b/lib/libc/sys/kqueue.2
index 2bff471c7..1044c3f61 100644
--- a/lib/libc/sys/kqueue.2
+++ b/lib/libc/sys/kqueue.2
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 3, 2016
+.Dd June 22, 2017
 .Dt KQUEUE 2
 .Os
 .Sh NAME
@@ -327,33 +327,18 @@ identical to the
 .Dv EVFILT_READ
 case.
 .It Dv EVFILT_AIO
-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_notify_kevent_flags
-containing the kevent flags which should be
-.Dv EV_ONESHOT ,
-.Dv EV_CLEAR
-or
-.Dv EV_DISPATCH ,
-.Va sigev_value
-containing the udata value, and
-.Va sigev_notify
-set to
-.Dv SIGEV_KEVENT .
-When the
-.Fn aio_*
-system call is made, the event will be registered
-with the specified kqueue, and the
-.Va ident
-argument set to the
-.Fa struct aiocb
-returned by the
-.Fn aio_*
-system call.
+Events for this filter are not registered with
+.Fn kevent
+directly but are registered via the
+.Va aio_sigevent
+member of an asychronous I/O request when it is scheduled via an asychronous I/O
+system call such as
+.Fn aio_read .
 The filter returns under the same conditions as
 .Fn aio_error .
+For more details on this filter see
+.Xr sigevent 3 and
+.Xr aio 4 .
 .It Dv EVFILT_VNODE
 Takes a file descriptor as the identifier and the events to watch for in
 .Va fflags ,
diff --git a/share/man/man4/aio.4 b/share/man/man4/aio.4
index eb9bfffe8..f2db1031e 100644
--- a/share/man/man4/aio.4
+++ b/share/man/man4/aio.4
@@ -27,7 +27,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd July 15, 2016
+.Dd June 22, 2017
 .Dt AIO 4
 .Os
 .Sh NAME
@@ -59,11 +59,27 @@ field which can be used to request notification when an operation completes.
 For
 .Dv SIGEV_KEVENT
 notifications,
-the posted kevent will contain:
+the
+.Va sigevent
+.Ap
+s
+.Va sigev_notify_kqueue
+field should contain the descriptor of the kqueue that the event should be attached
+to, its
+.Va sigev_notify_kevent_flags
+field may contain
+.Dv EV_ONESHOT ,
+.Dv EV_CLEAR , and/or
+.Dv EV_DISPATCH , and its
+.Va sigev_notify
+field should be set to
+.Dv SIGEV_KEVENT .
+The posted kevent will contain:
 .Bl -column ".Va filter"
 .It Sy Member Ta Sy Value
 .It Va ident Ta asynchronous I/O control buffer pointer
 .It Va filter Ta Dv EVFILT_AIO
+.It Va flags Ta Dv EV_EOF
 .It Va udata Ta
 value stored in
 .Va aio_sigevent.sigev_value
-- 
2.42.0