diff options
Diffstat (limited to 'doc/bus_read.3')
-rw-r--r-- | doc/bus_read.3 | 76 |
1 files changed, 0 insertions, 76 deletions
diff --git a/doc/bus_read.3 b/doc/bus_read.3 deleted file mode 100644 index 0bea94a..0000000 --- a/doc/bus_read.3 +++ /dev/null @@ -1,76 +0,0 @@ -.TH BUS_READ 3 BUS-%VERSION% -.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 \fIbus_read\fP. However, once \fIbus_read\fP 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 time specified 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) -.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 |