1 files changed, 87 insertions, 0 deletions
diff --git a/doc/man/bus_poll.3 b/doc/man/bus_poll.3
new file mode 100644
index 0000000..b22115c
--- /dev/null
+++ b/doc/man/bus_poll.3
@@ -0,0 +1,87 @@
+.TH BUS_POLL 3 BUS-%VERSION%
+.SH NAME
+bus_poll_start, bus_poll_stop, bus_poll, bus_poll_timed - Wait a message to be broadcasted
+.SH SYNOPSIS
+.LP
+.nf
+#include <bus.h>
+.P
+int bus_poll_start(bus_t *\fIbus\fP);
+int bus_poll_stop(const bus_t *\fIbus\fP);
+const char *bus_poll(bus_t *\fIbus\fP, int \fIflags\fP);
+const char *bus_poll_timed(bus_t *\fIbus\fP, const struct timespec *\fItimeout\fP, clockid_t \fIclockid\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR bus_poll ()
+function waits for a message to broadcasted on the \fIbus\fP, and return
+the message it receives.  The function fails if (\fIflags\fP &BUS_NOWAIT)
+and there is not already a message waiting on the bus.  Received messages
+shall be copied and parsed, and acted upon, in a separate thread, and
+.BR bus_poll ()
+or
+.BR bus_poll_stop ()
+called again as soon as possible.
+.PP
+The
+.BR bus_poll_start ()
+funcion must be called before
+.BR bus_poll ()
+is called for the first time.  When the process is done listening on the
+bus it must call the
+.BR bus_poll_stop ()
+function.
+.PP
+The
+.BR bus_poll_timed ()
+function behaves like
+.BR bus_poll (),
+except if it is not able to read a message within the specified time,
+it will fail and set \fIerrno\fP to \fBEAGAIN\fP.  The time is specified
+as an absolute time using the parameter \fItimeout\fP.  The behaviour is
+unspecified if \fItimeout\fP is \fINULL\fP. \fItimeout\fP is measured
+with the clock whose ID is specified by the \fIclockid\fP parameter.  This
+clock must be a predicitable clock.
+.SH RETURN VALUES
+Upon successful completion, the functions
+.BR bus_poll_start ()
+and
+.BR bus_poll_stop ()
+returns 0.  Otherwise the functions returns -1 and sets \fIerrno\fP to
+indicate the error.
+.PP
+Upon successful completion, the functions
+.BR bus_poll ()
+and
+.BR bus_poll_timed ()
+returns the received message.  Otherwise the function returns \fINULL\fP
+and sets \fIerrno\fP to indicate the error.
+.SH ERRORS
+The
+.BR bus_poll (3),
+.BR bus_poll_start (3)
+and
+.BR bus_poll_stop (3)
+functions may fail and set \fIerrno\fP to any of the errors specified for
+.BR semop (3).
+The
+.BR bus_poll_timed (3)
+function may also set \fIerrno\fP to any of the errors specified for
+.BR clock_gettime (3).
+.SH SEE ALSO
+.BR bus-create (1),
+.BR bus (5),
+.BR libbus (7),
+.BR bus_open (3),
+.BR bus_write (3),
+.BR bus_read (3),
+.BR semop (3),
+.BR clock_gettime (3)
+.SH AUTHORS
+Principal author, Mattias Andrée.  See the LICENSE file for the full
+list of authors.
+.SH LICENSE
+MIT/X Consortium License.
+.SH BUGS
+Please report bugs to https://github.com/maandree/bus/issues or to
+maandree@member.fsf.org