document race condition caused by queueing of multiple events

io/io_wait.3

@@ -23,5 +23,17 @@ io_wait is not interrupted by the delivery of a signal. Programs that
 expect interruption are unreliable: they will block if the same signal
 is delivered a moment before io_wait. The correct way to handle signals
 is with the self-pipe trick.
+
+.SH NOTE
+Depending on the underlying operating system primitive, there is a
+potential race condition to be aware of. Some event notification
+mechanisms (for example, kqueue on BSD and epoll on Linux) will return
+multiple events. If your application operates on pairs of file
+descriptors (a proxy server maybe), and an error on one descriptor
+can lead to closing the other descriptor, then an outstanding event on
+the other descriptor can still be queued for delivery to you. Be
+prepared to receive events for a descriptor that has already been
+closed.
+
 .SH "SEE ALSO"
 io_waituntil(3), io_check(3), io_wantread(3), io_wantwrite(3), io_fd(3)

io/io_waituntil.3

@@ -7,5 +7,17 @@ io_waituntil \- wait for events
 void \fBio_waituntil\fP(tai6464 t);
 .SH DESCRIPTION
 io_waituntil(t) is like io_wait() but does not wait (noticeably) past time \fIt\fR.
+
+.SH NOTE
+Depending on the underlying operating system primitive, there is a
+potential race condition to be aware of. Some event notification
+mechanisms (for example, kqueue on BSD and epoll on Linux) will return
+multiple events. If your application operates on pairs of file
+descriptors (a proxy server maybe), and an error on one descriptor
+can lead to closing the other descriptor, then an outstanding event on
+the other descriptor can still be queued for delivery to you. Be
+prepared to receive events for a descriptor that has already been
+closed.
+
 .SH "SEE ALSO"
 io_wait(3), io_check(3), io_wantread(3), io_wantwrite(3), io_fd(3)