From 8aacddbe8e827f13306460ff211aae25e4db68a8 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Fri, 1 May 2015 14:42:43 +0200 Subject: m + add bus_poll.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 6 +++++- doc/bus_chmod.3 | 8 ++++---- doc/bus_chown.3 | 4 ++-- doc/bus_open.3 | 3 ++- doc/bus_poll.3 | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/bus_read.3 | 3 ++- doc/bus_write.3 | 2 +- doc/libbus.7 | 3 ++- 8 files changed, 82 insertions(+), 11 deletions(-) create mode 100644 doc/bus_poll.3 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 +.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. -- cgit v1.2.3-70-g09d2