diff options
| -rw-r--r-- | Makefile | 3 | ||||
| -rw-r--r-- | doc/bus_close.3 | 20 | ||||
| -rw-r--r-- | doc/bus_create.3 | 26 | ||||
| -rw-r--r-- | doc/bus_open.3 | 31 | ||||
| -rw-r--r-- | doc/bus_read.3 | 22 | ||||
| -rw-r--r-- | doc/bus_unlink.3 | 20 | ||||
| -rw-r--r-- | doc/bus_write.3 | 20 |
7 files changed, 141 insertions, 1 deletions
@@ -11,10 +11,11 @@ VERSION = 1.0 all: bus doc doc: man -man: man1 man5 man7 +man: man1 man3 man5 man7 bus: bin/bus bin/libbus.so.$(LIB_VERSION) bin/libbus.so.$(LIB_MAJOR) bin/libbus.so bin/libbus.a man1: bin/bus.1 bin/bus-broadcast.1 bin/bus-create.1 bin/bus-listen.1 bin/bus-remove.1 bin/bus-wait.1 +man3: bin/bus_create.3 bin/bus_unlink.3 bin/bus_open.3 bin/bus_close.3 bin/bus_read.3 bin/bus_write.3 man5: bin/bus.5 man7: bin/libbus.7 diff --git a/doc/bus_close.3 b/doc/bus_close.3 new file mode 100644 index 0000000..f971b53 --- /dev/null +++ b/doc/bus_close.3 @@ -0,0 +1,20 @@ +.TH BUS_CLOSE 1 BUS-%VERSION% +.SH NAME +bus_close - Close a bus +.SH SYNOPSIS +#include <bus.h> + +int bus_close(bus_t *bus); +.SH DESCRIPTION +The \fIbus_close\fP function shall dispose of resource require for the process to use a bus whose information is stored in \fIbus\fP. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_open(3), bus_unlink(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + diff --git a/doc/bus_create.3 b/doc/bus_create.3 new file mode 100644 index 0000000..cfb7963 --- /dev/null +++ b/doc/bus_create.3 @@ -0,0 +1,26 @@ +.TH BUS_CREATE 1 BUS-%VERSION% +.SH NAME +bus_create - Create a new bus +.SH SYNOPSIS +#include <bus.h> + +int bus_create(const char *file, int flags, char **out_file); +.SH DESCRIPTION +The \fIbus_create\fP function shall create a bus with the asscoiated pathname specifed by the value of the parameter \fIfile\fP. If the \fIfile\iP is \fINULL\fP, a random pathname shall be selected. This random pathname must adhere to the convention set forth by bus(5). + +If \fIfile\fP is not \fINULL\fP, the \fIbus_create\fP function must fail if the file already exists if \fIflags\fP contains \fIBUS_EXCL\fP. Otherwise if \fIfile\fP is not \fINULL\fP, the \fIbus_create\fP function should do nothing if the file already exists. + +If and only if \fIflags\fP contains \fIBUS_INTR\fP, the function shall fail if it is interrupted. + +Unless \fIout_file\fP is \fINULL\P, the pathname of the bus should be stored in a new char array stored in \fI*out_file\fP. The caller must free the allocated stored in \fI*out_file\fP. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_unlink(3), bus_open(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + diff --git a/doc/bus_open.3 b/doc/bus_open.3 new file mode 100644 index 0000000..cdd51cf --- /dev/null +++ b/doc/bus_open.3 @@ -0,0 +1,31 @@ +.TH BUS_OPEN 1 BUS-%VERSION% +.SH NAME +bus_open - Open a bus +.SH SYNOPSIS +#include <bus.h> + +int bus_open(bus_t *bus, const char *file, int flags); +.SH DESCRIPTION +The \fIbus_open\fP function shall acquire the resources required for the process to use the bus associated with the filename stored in \fIfile\fP. The function shall also store these resource \fIbus\fP for use by other \fBbus\fP functions. + +Values for \fIflags\fP are constructed by a bitwise-inclusive OR of flags from the following list. +.TP +.IR BUS_RDONLY +The process will only be using the bus for receiving messages. +.TP +.IR BUS_WRONLY +The process will only be using the bus for sending messages. +.TP +.IR BUS_RDWR +The process will use the bus for both receiving adn sending messages. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_open(3), bus_unlink(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + diff --git a/doc/bus_read.3 b/doc/bus_read.3 new file mode 100644 index 0000000..1751cb8 --- /dev/null +++ b/doc/bus_read.3 @@ -0,0 +1,22 @@ +.TH BUS_CLOSE 1 BUS-%VERSION% +.SH NAME +bus_read - Listen for new messages a bus +.SH SYNOPSIS +#include <bus.h> + +int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data); +.SH DESCRIPTION +The \fIbus_read\fP function shall continuously wait for new message to be sent on the bus whose information is stored in \fIbus\fP. Once a message is received, the \fIcallback\fP function shall be invoked. \fImessage\fP should be the recieved message, and \fIuser_data\fP for \fIcallback\fP should be \fIuser_data\fP from \fIbus_read\fP. + +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 stop listening. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + diff --git a/doc/bus_unlink.3 b/doc/bus_unlink.3 new file mode 100644 index 0000000..f1bc947 --- /dev/null +++ b/doc/bus_unlink.3 @@ -0,0 +1,20 @@ +.TH BUS_UNLINK 1 BUS-%VERSION% +.SH NAME +bus_unlink - Remove a bus +.SH SYNOPSIS +#include <bus.h> + +int bus_unlink(const char *file); +.SH DESCRIPTION +The \fIbus_unlink\fP function shall remove the bus assoicated with the pathname stored in \fIfile\fP. The \fIbus_unlink\fP function shall also unlink the file. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_create(3), bus_close(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + diff --git a/doc/bus_write.3 b/doc/bus_write.3 new file mode 100644 index 0000000..cc5c8f2 --- /dev/null +++ b/doc/bus_write.3 @@ -0,0 +1,20 @@ +.TH BUS_CLOSE 1 BUS-%VERSION% +.SH NAME +bus_write - Broadcast a message a bus +.SH SYNOPSIS +#include <bus.h> + +int bus_write(const bus_t *bus, const char *message); +.SH DESCRIPTION +The \fIbus_write\fP function shall broadcast a message on the bus whose information is stored in \fIbus\fP. The message read by the function is stored in the parameter \fImessage\fIP. It may not exceeed 2048 bytes including NUL-termiantion. +.SH RETURN VALUES +Upon successful completion, the function shall return 0. Otherwise the function shall return -1 and set \fIerrno\fP to indicate the error. +.SH SEE ALSO +bus-create(1), bus(5), libbus(7), bus_open(3), bus_raed(3) +.SH AUTHORS +See the LICENSE file for the authors. +.SH LICENSE +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report them. + |