1 files changed, 71 insertions, 0 deletions
diff --git a/bus_read.3 b/bus_read.3
new file mode 100644
index 0000000..36fd4c9
--- /dev/null
+++ b/bus_read.3
@@ -0,0 +1,71 @@
+.TH BUS_READ 3 BUS
+.SH NAME
+bus_read, bus_read_timed - Listen for new messages a bus
+.SH SYNOPSIS
+.LP
+.nf
+#include <bus.h>
+.P
+int bus_read(const bus_t *\fIbus\fP, int (*\fIcallback\fP)(const char *\fImessage\fP, void *\fIuser_data\fP),
+             void *\fIuser_data\fP);
+int bus_read_timed(const bus_t *\fIbus\fP, int (*\fIcallback\fP)(const char *\fImessage\fP, void *\fIuser_data\fP),
+                   void *\fIuser_data\fP, const struct timespec *\fItimeout\fP, clockid_t \fIclockid\fP);
+.fi
+.SH DESCRIPTION
+The
+.BR bus_read ()
+function waits for new message to be sent on the bus specified in
+\fIbus\fP, as provieded by a previous call to the
+.BR bus_open ()
+function.  Once a message is received, the \fIcallback\fP function is
+invoked.  The \fImessage\fP argument to the callback is the received
+message, and \fIuser_data\fP for \fIcallback\fP should be
+\fIuser_data\fP from
+.BR bus_read ().
+However, once
+.BR bus_read ()
+has ensured that it will receive any message sent on the bus, it shall
+invoke the \fIcallback\fP function with \fImessage\fP set to \fINULL\fP,
+to notify the process that it can perform any action that requires that
+it is listening on the bus.
+.PP
+After \fIcallback\fP returns, \fImessage\fP may be override.  Therefore
+\fIcallback\fP should copy \fImessage\fP and start a new thread that
+uses the copy of \fImessage\fP.  \fIcallback\fP shall return -1 on
+failure, 0 if
+.BR bus_read ()
+should stop listening or 1 if
+.BR bus_read ()
+should continue listening.
+.PP
+The
+.BR bus_read_timed ()
+function behaves like
+.BR bus_read (),
+except it will automatically fail and set \fIerrno\fP to \fBEAGAIN\fP
+when the specified time has passed. 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, these functions returns 0.  Otherwise the
+function returns -1 and sets \fIerrno\fP to indicate the error.
+.SH ERRORS
+The
+.BR bus_read (3)
+function may fail and set \fIerrno\fP to any of the errors specified for
+.BR semop (3).
+The
+.BR bus_read_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_poll (3),
+.BR semop (3),
+.BR clock_gettime (3)