diff options
| -rw-r--r-- | Makefile | 7 | ||||
| -rw-r--r-- | doc/bus-broadcast.1 | 2 | ||||
| -rw-r--r-- | doc/bus-chgrp.1 | 5 | ||||
| -rw-r--r-- | doc/bus-chmod.1 | 19 | ||||
| -rw-r--r-- | doc/bus-chown.1 | 11 | ||||
| -rw-r--r-- | doc/bus-create.1 | 7 | ||||
| -rw-r--r-- | doc/bus-listen.1 | 2 | ||||
| -rw-r--r-- | doc/bus-remove.1 | 2 | ||||
| -rw-r--r-- | doc/bus-wait.1 | 2 | ||||
| -rw-r--r-- | doc/bus.1 | 13 | ||||
| -rw-r--r-- | doc/bus.5 | 13 | ||||
| -rw-r--r-- | doc/bus_chmod.3 | 39 | ||||
| -rw-r--r-- | doc/bus_chown.3 | 34 | ||||
| -rw-r--r-- | doc/bus_close.3 | 15 | ||||
| -rw-r--r-- | doc/bus_create.3 | 27 | ||||
| -rw-r--r-- | doc/bus_open.3 | 26 | ||||
| -rw-r--r-- | doc/bus_poll.3 | 75 | ||||
| -rw-r--r-- | doc/bus_read.3 | 58 | ||||
| -rw-r--r-- | doc/bus_unlink.3 | 30 | ||||
| -rw-r--r-- | doc/bus_write.3 | 62 | ||||
| -rw-r--r-- | doc/libbus.7 | 26 | ||||
| -rw-r--r-- | src/bus.c | 154 | ||||
| -rw-r--r-- | src/bus.h | 107 |
23 files changed, 543 insertions, 193 deletions
@@ -68,12 +68,12 @@ bin/libbus.a: obj/bus-fpic.o bin/bus: obj/cmdline-nofpic.o obj/bus-nofpic.o @echo CC -o $@ @mkdir -p bin - @${CC} ${FLAGS} -o $@ $^ ${LDFLAGS} + @${CC} ${FLAGS} -lrt -o $@ $^ ${LDFLAGS} bin/libbus.so.${LIB_VERSION}: obj/bus-fpic.o @echo CC -o $@ @mkdir -p bin - @${CC} ${FLAGS} -shared -Wl,-soname,libbus.so.${LIB_MAJOR} -o $@ $^ ${LDFLAGS} + @${CC} ${FLAGS} -lrt -shared -Wl,-soname,libbus.so.${LIB_MAJOR} -o $@ $^ ${LDFLAGS} bin/libbus.so.${LIB_MAJOR}: @echo LN -s $@ @@ -161,6 +161,9 @@ uninstall: -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 -- "${DESTDIR}${MANDIR}/man3/bus_poll_timed.3" + -rm -- "${DESTDIR}${MANDIR}/man3/bus_read_timed.3" + -rm -- "${DESTDIR}${MANDIR}/man3/bus_write_timed.3" -rm -- $(foreach M,${MAN5},"${DESTDIR}${MANDIR}/man5/${M}.5") -rm -- $(foreach M,${MAN7},"${DESTDIR}${MANDIR}/man7/${M}.7") diff --git a/doc/bus-broadcast.1 b/doc/bus-broadcast.1 index 5a4a7a3..e6094be 100644 --- a/doc/bus-broadcast.1 +++ b/doc/bus-broadcast.1 @@ -24,7 +24,7 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus(5) +.BR bus (5) .SH AUTHORS See the LICENSE file for the authors. .SH LICENSE diff --git a/doc/bus-chgrp.1 b/doc/bus-chgrp.1 index 49f5642..2ae0307 100644 --- a/doc/bus-chgrp.1 +++ b/doc/bus-chgrp.1 @@ -8,7 +8,7 @@ bus chgrp - Change group ownership of a bus .IR pathname .SH DESCRIPTION Change the group, that owns a bus with an associated \fIpathname\fP, -to the specified \fIgroup\fP. The \fIgroup\fP can be specified either +to the specified \fIgroup\fP. The \fIgroup\fP can be specified either with a GID or with a group name. .SH EXIT STATUS .TP @@ -21,7 +21,8 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus-chown(1), bus-chmod(1) +.BR bus-chown (1), +.BR bus-chmod (1) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus-chmod.1 b/doc/bus-chmod.1 index 24cdac9..fd88072 100644 --- a/doc/bus-chmod.1 +++ b/doc/bus-chmod.1 @@ -10,17 +10,17 @@ bus chmod - Change permissions on a bus Change whom as access to a bus with an associated \fIpathname\fP. In the \fIpermissions\fP, the owner, the group, and others (not in group) are represented by the symbols \fBu\fP, \fBg\fP, and -\fBo\fP, respectively. The \fIpermissions\fP string is imagined -to have always be prefixed with an \fB=\fP. This symbols means +\fBo\fP, respectively. The \fIpermissions\fP string is imagined +to have always be prefixed with an \fB=\fP. This symbols means that all user classes list after it, and only those classes, as -permission to use the bus. Similarly the symbols \fB+\fP and +permission to use the bus. Similarly the symbols \fB+\fP and \fB\-\fP can be used to grant and revoke access, respectively. The symbols \fB=\fP, \fB+\fP, and \fB\-\fP can be maked, and are -interpreted from left to right. -Alternatively the \fIpermissions\fP string can be a octal number, -where the owner is represented by any bit in 700 (100, 200, or 400, -or any combination thereof), the group is represented by any bit in 70, -and others (not in the group) is represented by any bit in 7. +interpreted from left to right. Alternatively the \fIpermissions\fP +string can be a octal number, where the owner is represented by any +bit in 700 (100, 200, or 400, or any combination thereof), the +group is represented by any bit in 70, and others (not in the group) +is represented by any bit in 7. .SH EXIT STATUS .TP 0 @@ -32,7 +32,8 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus-chown(1), bus-chgrp(1) +.BR bus-chown (1), +.BR bus-chgrp (1) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus-chown.1 b/doc/bus-chown.1 index a9c09ff..2436558 100644 --- a/doc/bus-chown.1 +++ b/doc/bus-chown.1 @@ -9,10 +9,10 @@ bus chown - Change ownership of a bus .SH DESCRIPTION Change the owner, that owns a bus with an associated \fIpathname\fP, to the specified \fIowner\fP. The \fIowner\fP can be specified either -with a UID or with a user name. -If a \fIgroup\fP is specified, the bus's owner-group will be set to -that \fIgroup\fP, otherwise the group will remain unchanged. The -\fIgroup\fP can be specified either with a GID or with a group name. +with a UID or with a user name. If a \fIgroup\fP is specified, the +bus's owner-group will be set to that \fIgroup\fP, otherwise the group +will remain unchanged. The \fIgroup\fP can be specified either with +a GID or with a group name. .SH EXIT STATUS .TP 0 @@ -24,7 +24,8 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus-chgrp(1), bus-chmod(1) +.BR bus-chgrp (1), +.BR bus-chmod (1) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus-create.1 b/doc/bus-create.1 index f50ad97..d0cc27d 100644 --- a/doc/bus-create.1 +++ b/doc/bus-create.1 @@ -7,8 +7,8 @@ bus create - Create a bus [--] .IR [pathname] .SH DESCRIPTION -Create a bus with an associated \fIpathname\fP. If \fIpathname\fP, a -random pathname in \fI$XDG_RUNTIME_DIR/bus\fP will be created and +Create a bus with an associated \fIpathname\fP. If \fIpathname\fP, +a random pathname in \fI$XDG_RUNTIME_DIR/bus\fP will be created and printed to stdout. .SH OPTIONS .TP @@ -25,7 +25,8 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus(5) +.BR bus (5), +.BR bus-remove (1) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus-listen.1 b/doc/bus-listen.1 index 0f56398..4977ce5 100644 --- a/doc/bus-listen.1 +++ b/doc/bus-listen.1 @@ -21,7 +21,7 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus(5) +.BR bus (5) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus-remove.1 b/doc/bus-remove.1 index 1b14d50..8bebce6 100644 --- a/doc/bus-remove.1 +++ b/doc/bus-remove.1 @@ -17,6 +17,8 @@ The command failed. .TP 2 The command is not recognised. +.SH SEE ALSO +.BR bus (5) .SH AUTHORS See the LICENSE file for the authors. .SH LICENSE diff --git a/doc/bus-wait.1 b/doc/bus-wait.1 index c9add51..4231cd0 100644 --- a/doc/bus-wait.1 +++ b/doc/bus-wait.1 @@ -22,7 +22,7 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus(5) +.BR bus (5) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. @@ -57,9 +57,16 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus-create(1), bus-remove(1), bus-listen(1), bus-wait(1), -bus-broadcast(1), bus-chmod(1), bus-chown(1) bus-chgrp(1), -bus(5), libbus(7) +.BR bus-create (1), +.BR bus-remove (1), +.BR bus-listen (1), +.BR bus-wait (1), +.BR bus-broadcast (1), +.BR bus-chmod (1), +.BR bus-chown (1), +.BR bus-chgrp (1), +.BR bus (5), +.BR libbus (7) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. @@ -7,9 +7,9 @@ messages to other processes on the same machine. \fBbus\fP does not use any daemon. Instead, all communication and synchronisation is managed using System V (XSI) semaphores and System V (XSI) shared memory. .PP -The command \fBbus create\fP can be used to create new buses. By +The command \fBbus create\fP can be used to create new buses. By convention, buses should be stored in \fI$XDG_RUNTIME_DIR/bus\fP, this is -what \fBbus create\fP does if no pathname is given. The pathname of the +what \fBbus create\fP does if no pathname is given. The pathname of the bus should be tracked using \fIBUS_X\fP, where \fIX\fP is replaced with either: .TP @@ -30,13 +30,16 @@ For the bus used in with the input subsystem is involved. For the bus used in with the storage subsystem is involved. .PP Messages broadcasted on a bus cannot be longer than 2047 bytes, -excluding NUL termination. Message should be encoded in UTF-8, and most -not contain the NUL character. +excluding NULL termination. Message should be encoded in UTF-8, +and most not contain the NULL character. .PP Broadcasted message should start with the process ID whence the message originated, followed by a single regular space. .SH SEE ALSO -bus(1), libbus(7), semop(2), shmop(2) +.BR bus (1), +.BR libbus (7), +.BR semop (2), +.BR shmop (2) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_chmod.3 b/doc/bus_chmod.3 index f7d431d..330a9d9 100644 --- a/doc/bus_chmod.3 +++ b/doc/bus_chmod.3 @@ -2,44 +2,53 @@ .SH NAME bus_chmod - Change bus mode bits .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_chmod(const char *file, mode_t mode); +.P +int bus_chmod(const char *\fIfile\fP, mode_t \fImode\fP); +.fi .SH DESCRIPTION -The \fIbus_chmod()\fP function gives access to the bus associated with -\fIfile\fP according to the following rules: +The +.BR bus_chmod () +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. +bus. Otherwise the owner should have no access. .TP * If (\fImode\fP &S_IRWXG) the group should be given read and write -access to the bus. Otherwise the group should have no access. +access to the bus. Otherwise the group should have no access. .TP * If (\fImode\fP &S_IRWXO) others (except the group) should be given -read and write access to the bus. Otherwise others should have no +read and write access to the bus. Otherwise others should have no access. .SH RETURN VALUES Upon successful completion, the function returns 0. Otherwise the function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS The -.BR bus_chown(3) +.BR bus_chown (3) function may fail and set \fIerrno\fP to any of the errors specified for -.BR bus_open(3), -.BR chmod(3), -.BR semget(3), -.BR shmget(3) +.BR bus_open (3), +.BR chmod (3), +.BR semget (3), +.BR shmget (3) and -.BR shmctl(3) +.BR shmctl (3) as well as any errors specified for the \fIIPC_STAT\fP and \fIIPC_SET\fP commands for -.BR semctl(3). +.BR semctl (3). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_open(3), bus_read(3) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_read (3) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_chown.3 b/doc/bus_chown.3 index 86e9481..186e937 100644 --- a/doc/bus_chown.3 +++ b/doc/bus_chown.3 @@ -2,32 +2,40 @@ .SH NAME bus_chown - Change bus owner and group .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_chown(const char *file, uid_t owner, gid_t group); +.P +int bus_chown(const char *\fIfile\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi .SH DESCRIPTION -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. +The +.BR bus_chown () +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 function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS The -.BR bus_chown(3) +.BR bus_chown (3) function may fail and set \fIerrno\fP to any of the errors specified for -.BR bus_open(3), -.BR chown(3), -.BR semget(3), -.BR shmget(3) +.BR bus_open (3), +.BR chown (3), +.BR semget (3), +.BR shmget (3) and -.BR shmctl(3) +.BR shmctl (3) as well as any errors specified for the \fIIPC_STAT\fP and \fIIPC_SET\fP commands for -.BR semctl(3). +.BR semctl (3). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_open(3), bus_read(3) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_read (3) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_close.3 b/doc/bus_close.3 index 41e2a97..734f18d 100644 --- a/doc/bus_close.3 +++ b/doc/bus_close.3 @@ -2,12 +2,15 @@ .SH NAME bus_close - Close a bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_close(bus_t *bus); +.P +int bus_close(bus_t *\fIbus\fP); +.fi .SH DESCRIPTION The -.BR bus_close(3) +.BR bus_close (3) function disposes of resources allocated to the process, as referenced in the \fIbus\fP argument. .SH RETURN VALUES @@ -18,7 +21,11 @@ function returns -1 and sets \fIerrno\fP to indicate the error. .B EINVAL The bus does not exist. .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_open(3), bus_unlink(3) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_unlink (3) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_create.3 b/doc/bus_create.3 index d18f3c0..158c755 100644 --- a/doc/bus_create.3 +++ b/doc/bus_create.3 @@ -2,12 +2,15 @@ .SH NAME bus_create - Create a new bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_create(const char * \fIfile\fP, int \fIflags\fP, char ** \fIout_file\fP); +.P +int bus_create(const char *\fIfile\fP, int \fIflags\fP, char **\fIout_file\fP); +.fi .SH DESCRIPTION The -.BR bus_create(3) +.BR bus_create () function creates a bus with the asscoiated pathname specifed by the value of the parameter \fIfile\fP. If \fIfile\fP is \fINULL\fP a random pathname is selected. This pathname adheres to the convention set forth @@ -15,10 +18,10 @@ by .BR bus(5). .PP If \fIfile\fP is not \fINULL\fP the -.BR bus_create(3) +.BR bus_create () function fails if the file already exists if \fIflags\fP contains \fIBUS_EXCL\fP. Otherwise if \fIfile\fP is not \fINULL\fP, the -.BR bus_create(3) +.BR bus_create () function does nothing if the file already exists. .PP If \fIflags\fP contains \fIBUS_INTR\fP, the function fails if it is @@ -36,14 +39,20 @@ function return -1 with \fIerrno\fP set to indicate the error. The process cannot allocate more memory. .PP The -.BR bus_create(3) +.BR bus_create (3) function may also fail and set \fIerrno\fP to any of the errors specified for the routines -.BR open(2) +.BR open (2) and -.BR write(2). +.BR write (2). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_unlink(3), bus_open(3), open(2), write(2) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_unlink (3), +.BR bus_open (3), +.BR open (2), +.BR write (2) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_open.3 b/doc/bus_open.3 index f40f444..f20ceba 100644 --- a/doc/bus_open.3 +++ b/doc/bus_open.3 @@ -2,16 +2,19 @@ .SH NAME bus_open - Open a bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_open(bus_t *bus, const char *file, int flags); +.P +int bus_open(bus_t *\fIbus\fP, const char *\fIfile\fP, int \fIflags\fP); +.fi .SH DESCRIPTION The -.BR bus_open(3) +.BR bus_open () function acquires resources required for the process to use the bus associated with the filename stored in \fIfile\fP. The function also stores the resource \fIbus\fP for use by other -.BR bus(5) +.BR bus () functions. .PP Values for \fIflags\fP are constructed by a bitwise inclusive OR of @@ -40,13 +43,20 @@ Operation permission is denied to the calling process. The described bus does not exist. .PP The -.BR bus_open(3) +.BR bus_open () function may also fail and set \fIerrno\fP to any of the errors specified for the routine -.BR open(2). +.BR open (2). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_close(3), bus_unlink(3), -bus_write(3), bus_read(3), bus_poll(3), open(2) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_close (3), +.BR bus_unlink (3), +.BR bus_write (3), +.BR bus_read (3), +.BR bus_poll (3), +.BR 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 index 7962082..9260f48 100644 --- a/doc/bus_poll.3 +++ b/doc/bus_poll.3 @@ -1,61 +1,88 @@ .TH BUS_POLL 3 BUS-%VERSION% .SH NAME -bus_poll - Wait a message to be broadcasted +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 *bus, int flags); -int bus_poll_stop(const bus_t *bus); -const char * bus_poll(bus_t *bus); +int bus_poll_start(bus_t *\fIbus\fP, int \fIflags\fP); +int bus_poll_stop(const bus_t *\fIbus\fP); +const char *bus_poll(bus_t *\fIbus\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(3) +.BR bus_poll () 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 +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) was used the last time -.BR bus_poll_start(3) -was called. Received messages shall be copied and parsed, and acted +.BR bus_poll_start () +was called. Received messages shall be copied and parsed, and acted upon, in a separate thread, and -.BR bus_poll(3) +.BR bus_poll () or -.BR bus_poll_stop(3) +.BR bus_poll_stop () called again as soon as possible. .PP The -.BR bus_poll_start(3) +.BR bus_poll_start () funcion must be called before -.BR bus_poll(3) -is called for the first time. When the process is done listening on the +.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(3) +.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. Additionally, the +.BR bus_poll_start () +function must not have been called with (\fIflags\fP &BUS_NOWAIT), +otherwise the behaviour is undefined. .SH RETURN VALUES Upon successful completion, the functions -.BR bus_poll_start(3) +.BR bus_poll_start () and -.BR bus_poll_stop(3) +.BR bus_poll_stop () 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) +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) +.BR bus_poll (3), +.BR bus_poll_start (3) and -.BR bus_poll_stop(3) +.BR bus_poll_stop (3) functions may fail and set \fIerrno\fP to any of the errors specified for -.BR semop(3). +.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 -bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3), -bus_read(3), semop(3) +.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) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. diff --git a/doc/bus_read.3 b/doc/bus_read.3 index b8b927e..0bea94a 100644 --- a/doc/bus_read.3 +++ b/doc/bus_read.3 @@ -1,16 +1,22 @@ .TH BUS_READ 3 BUS-%VERSION% .SH NAME -bus_read - Listen for new messages a bus +bus_read, bus_read_timed - Listen for new messages a bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data); +.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(3) +.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(3) +.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 @@ -20,22 +26,46 @@ 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 +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 \fIbus_read\fP should stop listening or 1 if -\fIbus_read\fP should continue listening. +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, the function returns 0. Otherwise the +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) +.BR bus_read (3) function may fail and set \fIerrno\fP to any of the errors specified for -.BR semop(3). +.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 -bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3), -bus_poll(3), semop(3) +.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. diff --git a/doc/bus_unlink.3 b/doc/bus_unlink.3 index 625b308..83ec760 100644 --- a/doc/bus_unlink.3 +++ b/doc/bus_unlink.3 @@ -2,12 +2,15 @@ .SH NAME bus_unlink - Remove a bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_unlink(const char *file); +.P +int bus_unlink(const char *\fIfile\fP); +.fi .SH DESCRIPTION The -.BR bus_unlink(3) +.BR bus_unlink () function removes the bus assoicated with the pathname stored in \fIfile\fP. The function also unlinks the file. .SH RETURN VALUES @@ -25,17 +28,24 @@ Operation permission is denied to the calling process. The user does not have permission to remove the bus. .PP The -.BR bus_unlink(3) +.BR bus_unlink (3) function may also fail and set \fIerrno\fP to any of the errors specified for the routines -.BR unlink(2), -.BR open(2), -.BR semget(3) +.BR unlink (2), +.BR open (2), +.BR semget (3) and -.BR shmget(3). +.BR shmget (3). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_create(3), bus_close(3), -unlink(2), open(2), semget(3) and shmget(3) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_create (3), +.BR bus_close (3), +.BR unlink (2), +.BR open (2), +.BR semget (3), +.BR shmget (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 55ca7df..4513c29 100644 --- a/doc/bus_write.3 +++ b/doc/bus_write.3 @@ -1,31 +1,59 @@ .TH BUS_WRITE 3 BUS-%VERSION% .SH NAME -bus_write - Broadcast a message a bus +bus_write, bus_write_timed - Broadcast a message a bus .SH SYNOPSIS +.LP +.nf #include <bus.h> - -int bus_write(const bus_t *bus, const char *message, int flags); +.P +int bus_write(const bus_t *\fIbus\fP, const char *\fImessage\fP, int \fIflags\fP); +int bus_write_timed(const bus_t *\fIbus\fP, const char *\fImessage\fP, + const struct timespec *\fItimeout\fP, clockid_t \fIclockid\fP); +.fi .SH DESCRIPTION -The \fIbus_write()\fP function broadcasts a message on the bus whose -information is stored in \fIbus\fP. The message read by the function is -stored in the parameter \fImessage\fP. It may not exceeed 2048 bytes, -including NUL termination. +The +.BR bus_write () +function broadcasts a message on the bus whose information is stored in +\fIbus\fP. The message read by the function is stored in the parameter +\fImessage\fP. It may not exceeed 2048 bytes, including NULL termination. +.PP +The +.BR bus_write () +function shall fail, and set \fIerrno\fP to \fIEAGAIN\fP, if the call +would suspend the process and (\fIflags\fP &BUS_NOWAIT). .PP -The \fIbus_write()\fP function shall fail, and set \fIerrno\fP to -\fIEAGAIN\fP, if the call would suspend the process and -(\fIflags\fP &BUS_NOWAIT). +The +.BR bus_write_timed () +function behaves like +.BR bus_write (), +except if it is not able to write the \fImessage\fP 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 function returns 0. Otherwise the +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_write(3) -function may fail and set \fIerrno\fP to any of the -errors specified for -.BR semop(3). +.BR bus_write (3) +function may fail and set \fIerrno\fP to any of the errors specified for +.BR semop (3). +The +.BR bus_write_timed (3) +function may also set \fIerrno\fP to any of the errors specified for +.BR clock_gettime (3). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_open(3), bus_read(3), -bus_poll(3), bus_chown(3), bus_chmod(3) +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_read (3), +.BR bus_poll (3), +.BR bus_chown (3), +.BR bus_chmod (3), +.BR clock_gettime (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 18c1d6e..804ee97 100644 --- a/doc/libbus.7 +++ b/doc/libbus.7 @@ -2,19 +2,33 @@ .SH NAME libbus - A simple daemonless system for broadcasting messages locally .SH DESCRIPTION -\fBbus\fP is a stupid-simple, thrilless, daemonless interprocess -communication system for broadcasting messages. +.BR bus +is a stupid-simple, thrilless, daemonless interprocess communication +system for broadcasting messages. .SH RATIONALE We need an interprocess communication system similar to message queues. But we need broadcasting rather than anycasting, so we have a fast, simple and daemonless system for announcing events to any processes that might be interested. .SH FUTURE DIRECTION -Timed out read and writes will be added. +None. .SH SEE ALSO -bus(1), bus(5), bus_create(3), bus_unlink(3), bus_open(3), bus_close(3), -bus_write(3), bus_read(3), bus_poll_start(3), bus_poll_stop(3), -bus_poll(3), bus_chown(3), bus_chmod(3) +.BR bus (1), +.BR bus (5), +.BR bus_create (3), +.BR bus_unlink (3), +.BR bus_open (3), +.BR bus_close (3), +.BR bus_write (3), +.BR bus_write_timed (3), +.BR bus_read (3), +.BR bus_read_timed (3), +.BR bus_poll_start (3), +.BR bus_poll_stop (3), +.BR bus_poll (3), +.BR bus_poll_timed (3), +.BR bus_chown (3), +.BR bus_chmod (3) .SH AUTHORS Principal author, Mattias Andrée. See the LICENSE file for the full list of authors. @@ -33,6 +33,7 @@ #include <sys/types.h> #include <sys/stat.h> #include <fcntl.h> +#include <time.h> #include <sys/ipc.h> #include <sys/sem.h> @@ -422,6 +423,36 @@ mkdirs(char *pathname, mode_t mode) } +/** + * Convert an absolute time to a relative time + * + * @param delta Output parameter for the relative time + * @param absolute The absolute time + * @param clockid The ID of the clock the time is measured in + * @return 0 on success, -1 on error + */ +static int +absolute_time_to_delta_time(struct timespec *delta, const struct timespec *absolute, clockid_t clockid) +{ + if (clock_gettime(clockid, delta) < 0) + return -1; + + delta->tv_sec = absolute->tv_sec - delta->tv_sec; + delta->tv_nsec = absolute->tv_nsec - delta->tv_nsec; + + if (delta->tv_nsec < 0L) { + delta->tv_nsec += 1000000000L; + delta->tv_sec -= 1; + } + if (delta->tv_nsec >= 1000000000L) { + delta->tv_nsec -= 1000000000L; + delta->tv_sec += 1; + } + + return 0; +} + + /** * Create a new bus @@ -632,7 +663,7 @@ fail: /** - * Broadcast a message a bus + * Broadcast a message on a bus * * @param bus Bus information * @param message The message to write, may not be longer than @@ -677,26 +708,49 @@ fail: /** + * Broadcast a message on a bus + * + * @param bus Bus information + * @param message The message to write, may not be longer than + * `BUS_MEMORY_SIZE` including the NUL-termination + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return 0 on success, -1 on error + */ +int bus_write_timed(const bus_t *bus, const char *message, + const struct timespec *timeout, clockid_t clockid) +{ + /* TODO bus_write_timed */ + if (!timeout) + return bus_write(bus, message, 0); + (void) bus, (void) message, (void) timeout, (void) clockid; +} + + +/** * Listen (in a loop, forever) for new message on a bus * - * @param bus Bus information - * @param callback Function to call when a message is received, the - * input parameters will be the read message and - * `user_data` from `bus_read`'s parameter with the - * same name. The message must have been parsed or - * copied when `callback` returns as it may be over - * overridden after that time. `callback` should - * return either of the the values: - * * 0: stop listening - * * 1: continue listening - * * -1: an error has occurred - * However, the function [`bus_read`] will invoke - * `callback` with `message` set to `NULL`one time - * directly after it has started listening on the - * bus. This is to the the program now it can safely - * continue with any action that requires that the - * programs is listening on the bus. - * @return 0 on success, -1 on error + * @param bus Bus information + * @param callback Function to call when a message is received, the + * input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @return 0 on success, -1 on error */ int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data) @@ -738,6 +792,44 @@ done: /** + * Listen (in a loop, forever) for new message on a bus + * + * @param bus Bus information + * @param callback Function to call when a message is received, the + * input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed, note that the callback + * function may or may not have been called + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return 0 on success, -1 on error + */ +int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void *user_data), + void *user_data, const struct timespec *timeout, clockid_t clockid) +{ + /* TODO bus_read_timed */ + if (!timeout) + return bus_read(bus, callback, user_data); + (void) bus, (void) callback, (void) user_data, (void) timeout, (void) clockid; +} + + +/** * Announce that the thread is listening on the bus. * This is required so the will does not miss any * messages due to race conditions. Additionally, @@ -835,6 +927,30 @@ fail: /** + * Wait for a message to be broadcasted on the bus. + * The caller should make a copy of the received message, + * without freeing the original copy, and parse it in a + * separate thread. When the new thread has started be + * started, the caller of this function should then + * either call `bus_poll_timed` again or `bus_poll_stop`. + * + * @param bus Bus information + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return The received message, `NULL` on error + */ +const char *bus_poll_timed(bus_t *bus, const struct timespec *timeout, clockid_t clockid) +{ + /* TODO bus_poll_timed */ + if (!timeout) + return bus_poll(bus); + (void) bus, (void) timeout, (void) clockid; +} + + +/** * Change the ownership of a bus * * `stat(2)` can be used of the bus's associated file to get the bus's ownership @@ -29,6 +29,7 @@ # define _DEFAULT_SOURCE #endif #include <sys/types.h> +#include <time.h> @@ -158,7 +159,7 @@ int bus_close(bus_t *bus); /** - * Broadcast a message a bus + * Broadcast a message on a bus * * @param bus Bus information * @param message The message to write, may not be longer than @@ -169,32 +170,78 @@ int bus_close(bus_t *bus); * @return 0 on success, -1 on error */ int bus_write(const bus_t *bus, const char *message, int flags); -/* TODO bus_write_timed */ + +/** + * Broadcast a message on a bus + * + * @param bus Bus information + * @param message The message to write, may not be longer than + * `BUS_MEMORY_SIZE` including the NUL-termination + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return 0 on success, -1 on error + */ +int bus_write_timed(const bus_t *bus, const char *message, + const struct timespec *timeout, clockid_t clockid); + /** * Listen (in a loop, forever) for new message on a bus * - * @param bus Bus information - * @param callback Function to call when a message is received, the - * input parameters will be the read message and - * `user_data` from `bus_read`'s parameter with the - * same name. The message must have been parsed or - * copied when `callback` returns as it may be over - * overridden after that time. `callback` should - * return either of the the values: - * * 0: stop listening - * * 1: continue listening - * * -1: an error has occurred - * However, the function [`bus_read`] will invoke - * `callback` with `message` set to `NULL`one time - * directly after it has started listening on the - * bus. This is to the the program now it can safely - * continue with any action that requires that the - * programs is listening on the bus. - * @return 0 on success, -1 on error + * @param bus Bus information + * @param callback Function to call when a message is received, the + * input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @return 0 on success, -1 on error */ int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data); -/* TODO bus_read_timed */ + +/** + * Listen (in a loop, forever) for new message on a bus + * + * @param bus Bus information + * @param callback Function to call when a message is received, the + * input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed, note that the callback + * function may or may not have been called + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return 0 on success, -1 on error + */ +int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void *user_data), + void *user_data, const struct timespec *timeout, clockid_t clockid); /** @@ -235,7 +282,23 @@ int bus_poll_stop(const bus_t *bus); * @return The received message, `NULL` on error */ const char *bus_poll(bus_t *bus); -/* TODO bus_poll_timed */ + +/** + * Wait for a message to be broadcasted on the bus. + * The caller should make a copy of the received message, + * without freeing the original copy, and parse it in a + * separate thread. When the new thread has started be + * started, the caller of this function should then + * either call `bus_poll_timed` again or `bus_poll_stop`. + * + * @param bus Bus information + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return The received message, `NULL` on error + */ +const char *bus_poll_timed(bus_t *bus, const struct timespec *timeout, clockid_t clockid); /** |