diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/bus-create.1 | 15 | ||||
| -rw-r--r-- | doc/bus-listen.1 | 16 | ||||
| -rw-r--r-- | doc/bus-wait.1 | 20 | ||||
| -rw-r--r-- | doc/bus.1 | 33 | ||||
| -rw-r--r-- | doc/bus.5 | 36 | ||||
| -rw-r--r-- | doc/bus_close.3 | 16 | ||||
| -rw-r--r-- | doc/bus_create.3 | 55 | ||||
| -rw-r--r-- | doc/bus_open.3 | 38 | ||||
| -rw-r--r-- | doc/bus_read.3 | 40 | ||||
| -rw-r--r-- | doc/bus_unlink.3 | 33 | ||||
| -rw-r--r-- | doc/bus_write.3 | 24 | ||||
| -rw-r--r-- | doc/libbus.7 | 24 |
12 files changed, 225 insertions, 125 deletions
diff --git a/doc/bus-create.1 b/doc/bus-create.1 index 0e445ba..fa016e3 100644 --- a/doc/bus-create.1 +++ b/doc/bus-create.1 @@ -5,10 +5,9 @@ bus create - Create a bus .B bus create .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 printed to stdout. +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 EXIT STATUS .TP 0 @@ -22,9 +21,9 @@ The command is not recognised. .SH SEE ALSO bus(5) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus-listen.1 b/doc/bus-listen.1 index 89ae7d9..4b71462 100644 --- a/doc/bus-listen.1 +++ b/doc/bus-listen.1 @@ -6,11 +6,9 @@ bus listen - Listen for new messages on a bus .IR pathname .IR command .SH DESCRIPTION -Listen for new messages on the bus associated -with \fIpathname\fP. Once a message is received -\fIcommand\fP will be spawned with the \fI$arg\fP -set to the received message. -POSIX shell syntax applies to \fIcommand\fP. +Listen for new messages on the bus associated with \fIpathname\fP. Once +a message is received, \fIcommand\fP will be spawned with \fI$arg\fP set +to the received message. POSIX shell syntax applies to \fIcommand\fP. .SH EXIT STATUS .TP 0 @@ -24,9 +22,9 @@ The command is not recognised. .SH SEE ALSO bus(5) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus-wait.1 b/doc/bus-wait.1 index 42d176e..a2f3b2d 100644 --- a/doc/bus-wait.1 +++ b/doc/bus-wait.1 @@ -1,17 +1,15 @@ .TH BUS-WAIT 1 BUS-%VERSION% .SH NAME -bus wait - Listen for one new message only on a bus +bus wait - Listen for a new message on a bus .SH SYNOPSIS .B bus wait .IR pathname .IR command .SH DESCRIPTION -Listen for one new message on the bus associated -with \fIpathname\fP, and stop listening once a -message has been received. Once a message is -received \fIcommand\fP will be spawned with -\fI$arg\fP set to the received message. -POSIX shell syntax applies to \fIcommand\fP. +Listen for a new message on the bus associated with \fIpathname\fP, stop +listening once a message has been received. Once a message is received, +\fIcommand\fP will be spawned with \fI$arg\fP set to the received +message. POSIX shell syntax applies to \fIcommand\fP. .SH EXIT STATUS .TP 0 @@ -25,9 +23,9 @@ The command is not recognised. .SH SEE ALSO bus(5) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues @@ -4,23 +4,33 @@ bus - A simple daemonless system for broadcasting messages locally .SH SYNOPSIS .B bus .IR command -.IR argument... +.IR argument\ ... .SH COMMANDS .TP .B create -Create a bus. +Create a bus, see +.BR bus-create (1) +for further details. .TP .B remove -Remove a bus. +Remove a bus, see +.BR bus-remove (1) +for further details. .TP .B listen -Listen for new message on a bus. +Listen for new message on a bus, see +.BR bus-listen (1) +for further details. .TP .B wait -Listen for one new message only on a bus. +Listen for one new message only on a bus, see +.BR bus-wait (1) +for further details. .TP .B broadcast -Broadcast a message on a bus. +Broadcast a message on a bus, see +.BR bus-broadcast (1) +for further details. .SH EXIT STATUS .TP 0 @@ -32,11 +42,12 @@ The command failed. 2 The command is not recognised. .SH SEE ALSO -bus(5), libbus(7) +bus-create(1), bus-remove(1), bus-listen(1), bus-wait(1), +bus-broadcast(1), bus(5), libbus(7) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues @@ -2,12 +2,20 @@ .SH NAME bus - A simple daemonless system for broadcasting messages locally .SH DESCRIPTION -\fBbus\fP is a simple interprocess communication system for broadcasting 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. - -The command \fBbus create\fP can be used to new buses. By convention, buses should be stored in \fIXDG_RUNTIME_DIR/bus\fP, this is 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: +\fBbus\fP is a simple interprocess communication system for broadcasting +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 +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 +bus should be tracked using \fIBUS_X\fP, where \fIX\fP is replaced with +either: .TP .IR GENERIC -For the bus used in generic cases. That is all but the cases of the buses listed below. +For the bus used in generic cases. That is all but the cases of the +buses listed below. .TP .IR AUDIO For the bus used in with the audio subsystem is involved. @@ -21,14 +29,18 @@ For the bus used in with the input subsystem is involved. .IR FILES For the bus used in with the storage subsystem is involved. .SH - -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. - -Broadcasted message should start with the process ID whence the message originated, followed by a single regular space. +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. +.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) +bus(1), libbus(7), semop(2), shmop(2) .SH AUTHORS -See the LICENSE file for the 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 them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_close.3 b/doc/bus_close.3 index 94e23a8..025544f 100644 --- a/doc/bus_close.3 +++ b/doc/bus_close.3 @@ -6,9 +6,13 @@ bus_close - Close a bus 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. +The +.BR bus_close(3) +function disposes of resources allocated to the process, as referenced +in the \fIbus\fP argument. .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. +Upon successful completion, the function returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS .TP .IR EINVAL @@ -16,9 +20,9 @@ The bus does not exist. .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. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_create.3 b/doc/bus_create.3 index b30400e..b9cb66d 100644 --- a/doc/bus_create.3 +++ b/doc/bus_create.3 @@ -4,31 +4,50 @@ bus_create - Create a new bus .SH SYNOPSIS #include <bus.h> -int bus_create(const char *file, int flags, char **out_file); +int bus_create(const char * \fIfile\fP, int \fIflags\fP, char ** \fIout_file\fP); .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\fP 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\fP, 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. +The +.BR bus_create(3) +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 +by +.BR bus(5). +.PP +If \fIfile\fP is not \fINULL\fP the +.BR bus_create(3) +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) +function does nothing if the file already exists. +.PP +If \fIflags\fP contains \fIBUS_INTR\fP, the function fails if it is +interrupted. +.PP +Unless \fIout_file\fP is \fINULL\fP, 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. +Upon successful completion, the function returns 0. Otherwise the +function return -1 with \fIerrno\fP set to indicate the error. .SH ERRORS .TP .IR ENOMEM The process cannot allocate more memory. -.SH -.BR -The \fIbus_create\fP() function may also fail and set \fIerrno\fP to any of the errors specified for the rutines open(2) and write(2). -.BR +.PP +The +.BR bus_create(3) +function may also fail and set \fIerrno\fP to any +of the errors specified for the routines +.BR open(2) +and +.BR write(2). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_unlink(3), bus_open(3) +bus-create(1), bus(5), libbus(7), bus_unlink(3), bus_open(3), open(2), write(2) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_open.3 b/doc/bus_open.3 index 72847d7..0bedf00 100644 --- a/doc/bus_open.3 +++ b/doc/bus_open.3 @@ -6,9 +6,16 @@ bus_open - Open a bus 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. +The +.BR bus_open(3) +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) +functions. +.PP +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. @@ -17,9 +24,10 @@ The process will only be using the bus for receiving messages. 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. +The process will use the bus for both receiving and 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. +Upon successful completion the function returns 0. Otherwise the +function returns -1 and set \fIerrno\fP to indicate the error. .SH ERRORS .TP .IR ENOMEM @@ -30,16 +38,18 @@ Operation permission is denied to the calling process. .TP .IR EINVAL The described bus does not exist. -.SH -.BR -The \fIbus_open\fP() function may also fail and set \fIerrno\fP to any of the errors specified for the rutine open(2). -.BR +.PP +The +.BR bus_open(3) +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) +bus-create(1), bus(5), libbus(7), bus_open(3), bus_unlink(3), open(2) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_read.3 b/doc/bus_read.3 index 8f6ce88..9f57527 100644 --- a/doc/bus_read.3 +++ b/doc/bus_read.3 @@ -6,19 +6,39 @@ bus_read - Listen for new messages a bus 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 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. - -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. +The +.BR bus_read(3) +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) +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 \fIbus_read\fP should stop listening or 1 if +\fIbus_read\fP should continue 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. +Upon successful completion, the function returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS -The \fIbus_read\fP() function may fail and set \fIerrno\fP to any of the errors specified for the rutine semop(3). +The +.BR bus_read(3) +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) +bus-create(1), bus(5), libbus(7), bus_open(3), bus_write(3), semop(3) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_unlink.3 b/doc/bus_unlink.3 index 7044922..47b62d8 100644 --- a/doc/bus_unlink.3 +++ b/doc/bus_unlink.3 @@ -6,9 +6,13 @@ bus_unlink - Remove a bus 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. +The +.BR bus_unlink(3) +function removes the bus assoicated with the pathname stored in +\fIfile\fP. The function also unlinks 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. +Upon successful completion, the function returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS .TP .IR EINVAL @@ -19,16 +23,23 @@ Operation permission is denied to the calling process. .TP .IR EPERM The user does not have permission to remove the bus. -.SH -.BR -The \fIbus_unlink\fP() function may also fail and set \fIerrno\fP to any of the errors specified for the rutines unlink(2), open(2), semget(3) and shmget(3). -.BR +.PP +The +.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) +and +.BR shmget(3). .SH SEE ALSO -bus-create(1), bus(5), libbus(7), bus_create(3), bus_close(3) +bus-create(1), bus(5), libbus(7), bus_create(3), bus_close(3), +unlink(2), open(2), semget(3) and shmget(3) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/bus_write.3 b/doc/bus_write.3 index 643b3fe..d4329cc 100644 --- a/doc/bus_write.3 +++ b/doc/bus_write.3 @@ -6,17 +6,25 @@ bus_write - Broadcast a message a bus 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. +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. .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. +Upon successful completion, the function returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. .SH ERRORS -The \fIbus_read\fP() function may fail and set \fIerrno\fP to any of the errors specified for the rutine semop(3). +The +.BR bus_read(3) +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_raed(3) +bus-create(1), bus(5), libbus(7), bus_open(3), bus_read(3) .SH AUTHORS -See the LICENSE file for the authors. +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. .SH LICENSE -See the LICENSE file for the terms of redistribution. +MIT/X Consortium License. .SH BUGS -Please report them. - +Please report bugs to https://github.com/maandree/bus/issues diff --git a/doc/libbus.7 b/doc/libbus.7 index dbed392..cb1e460 100644 --- a/doc/libbus.7 +++ b/doc/libbus.7 @@ -2,15 +2,25 @@ .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 message. +\fBbus\fP 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 it we need broadcasting rather than anycasting, so we have a fast, simple and daemonless system for announcing events to all processes whom might be interested. +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 -Perhaps the ability to have groups and other permissions on bus, so they can be shared among users and be system-wide. Private and abstract buses might be interesting too, as well as timed out read and writes, and non-blocking writes. +Perhaps the ability to have groups and other permissions on bus, so they +can be shared among users and be system-wide. Private and abstract +buses might be interesting too, as well as timed out read and writes, +and non-blocking writes. .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(1), bus(5), bus_create(3), bus_unlink(3), bus_open(3), bus_close(3), +bus_read(3), bus_write(3) .SH AUTHORS -See the LICENSE file for the 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 them. - +Please report bugs to https://github.com/maandree/bus/issues |