1 files changed, 64 insertions, 0 deletions
diff --git a/doc/bus_poll.3 b/doc/bus_poll.3
new file mode 100644
index 0000000..857ea20
--- /dev/null
+++ b/doc/bus_poll.3
@@ -0,0 +1,64 @@
+.TH BUS_POLL 3 BUS-%VERSION%
+.SH NAME
+bus_poll - Wait a message to be broadcasted
+.SH SYNOPSIS
+.LP
+.nf
+#include <bus.h>
+.P
+int bus_poll_start(bus_t *bus);
+int bus_poll_stop(const bus_t *bus);
+const char * bus_poll(bus_t *bus, int flags);
+.fi
+.SH DESCRIPTION
+The
+.BR bus_poll(3)
+function waits for a message to broadcasted on the \fIbus\fP, and return
+the message it receives. The function fails if there is not already a
+message waiting on the bus when the function is called and (\fIflags\fP
+&BUS_NOWAIT). Received messages shall be copied and parsed, and acted
+upon, in a separate thread, and
+.BR bus_poll(3)
+or
+.BR bus_poll_stop(3)
+called again as soon as possible.
+.PP
+The
+.BR bus_poll_start(3)
+funcion must be called before
+.BR bus_poll(3)
+is called for the first time. When the process is done listening on the
+bus it must call the
+.BR bus_poll_stop(3)
+function.
+.SH RETURN VALUES
+Upon successful completion, the functions
+.BR bus_poll_start(3)
+and
+.BR bus_poll_stop(3)
+returns 0.  Otherwise the functions returns -1 and sets \fIerrno\fP to
+indicate the error.
+.PP
+Upon successful completion, the function
+.BR bus_poll(3)
+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).
+.SH SEE ALSO
+bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3),
+bus_read(3), semop(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