From e35ba8684be9951fa2129503477ccd5ed6e4e5fc Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@kth.se>
Date: Mon, 11 Dec 2017 23:13:37 +0100
Subject: Simplify, do not install examples or info manual, and change license
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@kth.se>
---
 bus_poll.3 | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 bus_poll.3

(limited to 'bus_poll.3')

diff --git a/bus_poll.3 b/bus_poll.3
new file mode 100644
index 0000000..f916237
--- /dev/null
+++ b/bus_poll.3
@@ -0,0 +1,79 @@
+.TH BUS_POLL 3 BUS
+.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 be 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)
-- 
cgit v1.2.3-70-g09d2