aboutsummaryrefslogtreecommitdiffstats
path: root/bus_poll.3
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2017-12-11 23:13:37 +0100
committerMattias Andrée <maandree@kth.se>2017-12-11 23:13:37 +0100
commite35ba8684be9951fa2129503477ccd5ed6e4e5fc (patch)
tree756292d5a18ad6011a9311fdea8159f474385b65 /bus_poll.3
parenttypo (diff)
downloadbus-e35ba8684be9951fa2129503477ccd5ed6e4e5fc.tar.gz
bus-e35ba8684be9951fa2129503477ccd5ed6e4e5fc.tar.bz2
bus-e35ba8684be9951fa2129503477ccd5ed6e4e5fc.tar.xz
Simplify, do not install examples or info manual, and change license3.1.7
Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat (limited to 'bus_poll.3')
-rw-r--r--bus_poll.379
1 files changed, 79 insertions, 0 deletions
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)