m + add bus_poll.3

Signed-off-by: Mattias Andrée <maandree@operamail.com>

8 files changed, 82 insertions, 11 deletions

diff --git a/Makefile b/Makefile
index 6171ee6..6cf36de 100644
--- a/Makefile
+++ b/Makefile
@@ -17,7 +17,7 @@ PKGNAME = bus
 
 
 MAN1 = bus bus-broadcast bus-create bus-listen bus-remove bus-wait
-MAN3 = bus_create bus_unlink bus_open bus_close bus_read bus_write
+MAN3 = bus_create bus_unlink bus_open bus_close bus_read bus_write bus_poll bus_chmod bus_chown
 MAN5 = bus
 MAN7 = libbus
 
@@ -135,6 +135,8 @@ install-man3: $(foreach M,${MAN3},bin/${M}.3)
 	@echo INSTALL $(foreach M,${MAN3},${M}.3)
 	@install -dm755 -- "${DESTDIR}${MANDIR}/man3"
 	@install -m644 $^ -- "${DESTDIR}${MANDIR}/man3"
+	@ln -sf -- "bus_poll.3" "${DESTDIR}${MANDIR}/man3/bus_poll_start.3"
+	@ln -sf -- "bus_poll.3" "${DESTDIR}${MANDIR}/man3/bus_poll_stop.3"
 
 install-man5: $(foreach M,${MAN5},bin/${M}.5)
 	@echo INSTALL $(foreach M,${MAN5},${M}.5)
@@ -157,6 +159,8 @@ uninstall:
 	-rmdir -- "${DESTDIR}${LICENSEDIR}/${PKGNAME}"
 	-rm -- $(foreach M,${MAN1},"${DESTDIR}${MANDIR}/man1/${M}.1")
 	-rm -- $(foreach M,${MAN3},"${DESTDIR}${MANDIR}/man3/${M}.3")
+	-rm -- "${DESTDIR}${MANDIR}/man3/bus_poll_start.3"
+	-rm -- "${DESTDIR}${MANDIR}/man3/bus_poll_stop.3"
 	-rm -- $(foreach M,${MAN5},"${DESTDIR}${MANDIR}/man5/${M}.5")
 	-rm -- $(foreach M,${MAN7},"${DESTDIR}${MANDIR}/man7/${M}.7")
 
diff --git a/doc/bus_chmod.3 b/doc/bus_chmod.3
index c61fcd3..f7d431d 100644
--- a/doc/bus_chmod.3
+++ b/doc/bus_chmod.3
@@ -6,12 +6,12 @@ bus_chmod - Change bus mode bits
 
 int bus_chmod(const char *file, mode_t mode);
 .SH DESCRIPTION
-The \fIbus_chmod()\fP function shall give access to the bus associated
-with \fIfile\fP according to the following rules:
+The \fIbus_chmod()\fP function gives access to the bus associated with
+\fIfile\fP according to the following rules:
 .TP
 *
-If (\fImode\fP &S_IRWXU) the owner should be given full access to
-the bus. Otherwise the owner should have no access.
+If (\fImode\fP &S_IRWXU) the owner should be given full access to the
+bus. Otherwise the owner should have no access.
 .TP
 *
 If (\fImode\fP &S_IRWXG) the group should be given read and write
diff --git a/doc/bus_chown.3 b/doc/bus_chown.3
index 7bfe60a..86e9481 100644
--- a/doc/bus_chown.3
+++ b/doc/bus_chown.3
@@ -6,8 +6,8 @@ bus_chown - Change bus owner and group
 
 int bus_chown(const char *file, uid_t owner, gid_t group);
 .SH DESCRIPTION
-The \fIbus_chown()\fP function shall change the owner and the group of
-the bus associated with \fIfile\fP to the \fIowner\fP and \fIgroup\fP,
+The \fIbus_chown()\fP function change the owner and the group of the bus
+associated with \fIfile\fP to the \fIowner\fP and \fIgroup\fP,
 respectively.
 .SH RETURN VALUES
 Upon successful completion, the function returns 0.  Otherwise the
diff --git a/doc/bus_open.3 b/doc/bus_open.3
index 34ffb5f..f40f444 100644
--- a/doc/bus_open.3
+++ b/doc/bus_open.3
@@ -45,7 +45,8 @@ function may also fail and set \fIerrno\fP to any of the errors
 specified for the routine
 .BR open(2).
 .SH SEE ALSO
-bus-create(1), bus(5), libbus(7), bus_open(3), bus_unlink(3), open(2)
+bus-create(1), bus(5), libbus(7), bus_close(3), bus_unlink(3),
+bus_write(3), bus_read(3), bus_poll(3), open(2)
 .SH AUTHORS
 Principal author, Mattias Andrée.  See the LICENSE file for the full
 list of authors.
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
diff --git a/doc/bus_read.3 b/doc/bus_read.3
index 7ad0189..b8b927e 100644
--- a/doc/bus_read.3
+++ b/doc/bus_read.3
@@ -34,7 +34,8 @@ The
 function 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), semop(3)
+bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3),
+bus_poll(3), semop(3)
 .SH AUTHORS
 Principal author, Mattias Andrée.  See the LICENSE file for the full
 list of authors.
diff --git a/doc/bus_write.3 b/doc/bus_write.3
index 8fbecbf..55ca7df 100644
--- a/doc/bus_write.3
+++ b/doc/bus_write.3
@@ -25,7 +25,7 @@ errors specified for
 .BR semop(3).
 .SH SEE ALSO
 bus-create(1), bus(5), libbus(7), bus_open(3), bus_read(3),
-bus_chown(3), bus_chmod(3)
+bus_poll(3), bus_chown(3), bus_chmod(3)
 .SH AUTHORS
 Principal author, Mattias Andrée.  See the LICENSE file for the full
 list of authors.
diff --git a/doc/libbus.7 b/doc/libbus.7
index 73c289e..256e672 100644
--- a/doc/libbus.7
+++ b/doc/libbus.7
@@ -14,7 +14,8 @@ Private and abstract buses might be interesting.  Timed out read and
 writes might be too.
 .SH SEE ALSO
 bus(1), bus(5), bus_create(3), bus_unlink(3), bus_open(3), bus_close(3),
-bus_read(3), bus_write(3), bus_chown(3), bus_chmod(3)
+bus_write(3), bus_read(3), bus_poll_start(3), bus_poll_stop(3),
+bus_poll(3), bus_chown(3), bus_chmod(3)
 .SH AUTHORS
 Principal author, Mattias Andrée.  See the LICENSE file for the full
 list of authors.