From f997f10b0e07376f15a6e3dfd9f9e9e355b091b7 Mon Sep 17 00:00:00 2001
From: Alexandre Ratchov <alex@caoua.org>
Date: Thu, 20 Sep 2012 11:00:31 +0200
Subject: [PATCH] fix interface to poll(2)

---
 libsndio/mio_open.3 | 89 ++++++++++++++++++++++++++-------------------
 1 file changed, 51 insertions(+), 38 deletions(-)

diff --git a/libsndio/mio_open.3 b/libsndio/mio_open.3
index 30bf5d6..f4d117b 100644
--- a/libsndio/mio_open.3
+++ b/libsndio/mio_open.3
@@ -117,7 +117,7 @@ It will store at most
 .Ar nbytes
 bytes at the
 .Ar addr
-location and return the number of bytes stored.
+location.
 Unless the
 .Ar nbio_flag
 flag is set, it will block until data becomes available and
@@ -149,34 +149,34 @@ system call can be used to check if data can be
 read from or written to the stream.
 The
 .Fn mio_pollfd
-function fills the array
+function prepares the array
 .Ar pfd
 of
 .Va pollfd
-structures, used by
-.Xr poll 2 ,
-with
-.Ar events ;
-the latter is a bit-mask of
+structures for use with
+.Xr poll 2 .
+The optimal size of the
+.Ar pfd
+array, which the caller must pre-allocate, is provided by the
+.Fn mio_nfds
+function.
+.Pp
+.Xr poll 2
+will sleep until any of the
+.Ar events
+requested with
+.Fn mio_pollfd
+have occurred.
+Events are represented as a bit-mask of
 .Va POLLIN
 and
 .Va POLLOUT
-constants; refer to
+constants.
+The events which woke up
 .Xr poll 2
-for more details.
-.Fn mio_pollfd
-returns the number of
-.Va pollfd
-structures filled.
-The
+can be obtained with the
 .Fn mio_revents
-function returns the bit-mask set by
-.Xr poll 2
-in the
-.Va pfd
-array of
-.Va pollfd
-structures.
+function.
 If
 .Va POLLIN
 is set,
@@ -188,17 +188,8 @@ is set,
 .Fn mio_write
 can be called without blocking.
 POLLHUP may be set if an error occurs, even if
-it is not selected with
+it is not requested with
 .Fn mio_pollfd .
-.Pp
-The
-.Fn mio_nfds
-function returns the number of
-.Va pollfd
-structures the caller must preallocate in order to be sure
-that
-.Fn mio_pollfd
-will never overrun.
 .Ss Error handling
 Errors related to the MIDI subsystem
 (like hardware errors or dropped connections) and
@@ -212,25 +203,46 @@ argument, except
 and
 .Fn mio_eof ,
 stop working (i.e. always return 0).
-.Pp
-The
-.Fn mio_eof
-function can be used at any stage;
-it returns 0 if there's no pending error, and a non-zero
-value if there's an error.
 .Sh RETURN VALUES
 The
 .Fn mio_open
 function returns the newly created handle on success or NULL
 on failure.
+.Pp
 The
 .Fn mio_pollfd
-function returns 1 on success and 0 on failure.
+function returns the number of
+.Va pollfd
+structures filled.
+The
+.Fn mio_nfds
+function returns the number of
+.Va pollfd
+structures the caller must preallocate in order to be sure
+that
+.Fn mio_pollfd
+will never overrun.
+.Pp
+The
+.Fn mio_revents
+function returns the bit-mask set by
+.Xr poll 2
+in the
+.Va pfd
+array of
+.Va pollfd
+structures.
+.Pp
 The
 .Fn mio_read
 and
 .Fn mio_write
 functions return the number of bytes transferred.
+.Pp
+The
+.Fn mio_eof
+function returns 0 if there's no pending error, and a non-zero
+value if there's an error.
 .Sh ENVIRONMENT
 .Bl -tag -width "SNDIO_DEBUGXXX" -compact
 .It Ev SNDIO_DEBUG
@@ -249,5 +261,6 @@ devices.
 .El
 .Sh SEE ALSO
 .Xr sndiod 1 ,
+.Xr poll 2 ,
 .Xr midi 4 ,
 .Xr sndio 7