From d26658642e018e36e848caa7d7587a213808913b Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 28 Nov 2015 23:44:00 +0100 Subject: move manpages from doc/ to doc/man/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- doc/man/bus-broadcast.1 | 34 +++++++++++++++++++ doc/man/bus-chgrp.1 | 38 +++++++++++++++++++++ doc/man/bus-chmod.1 | 49 ++++++++++++++++++++++++++++ doc/man/bus-chown.1 | 41 +++++++++++++++++++++++ doc/man/bus-create.1 | 37 +++++++++++++++++++++ doc/man/bus-listen.1 | 32 ++++++++++++++++++ doc/man/bus-remove.1 | 28 ++++++++++++++++ doc/man/bus-wait.1 | 33 +++++++++++++++++++ doc/man/bus.1 | 77 +++++++++++++++++++++++++++++++++++++++++++ doc/man/bus.5 | 50 ++++++++++++++++++++++++++++ doc/man/bus_chmod.3 | 64 ++++++++++++++++++++++++++++++++++++ doc/man/bus_chown.3 | 51 +++++++++++++++++++++++++++++ doc/man/bus_close.3 | 36 ++++++++++++++++++++ doc/man/bus_create.3 | 63 +++++++++++++++++++++++++++++++++++ doc/man/bus_open.3 | 67 +++++++++++++++++++++++++++++++++++++ doc/man/bus_poll.3 | 87 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/man/bus_read.3 | 76 ++++++++++++++++++++++++++++++++++++++++++ doc/man/bus_unlink.3 | 56 +++++++++++++++++++++++++++++++ doc/man/bus_write.3 | 64 ++++++++++++++++++++++++++++++++++++ doc/man/libbus.7 | 39 ++++++++++++++++++++++ 20 files changed, 1022 insertions(+) create mode 100644 doc/man/bus-broadcast.1 create mode 100644 doc/man/bus-chgrp.1 create mode 100644 doc/man/bus-chmod.1 create mode 100644 doc/man/bus-chown.1 create mode 100644 doc/man/bus-create.1 create mode 100644 doc/man/bus-listen.1 create mode 100644 doc/man/bus-remove.1 create mode 100644 doc/man/bus-wait.1 create mode 100644 doc/man/bus.1 create mode 100644 doc/man/bus.5 create mode 100644 doc/man/bus_chmod.3 create mode 100644 doc/man/bus_chown.3 create mode 100644 doc/man/bus_close.3 create mode 100644 doc/man/bus_create.3 create mode 100644 doc/man/bus_open.3 create mode 100644 doc/man/bus_poll.3 create mode 100644 doc/man/bus_read.3 create mode 100644 doc/man/bus_unlink.3 create mode 100644 doc/man/bus_write.3 create mode 100644 doc/man/libbus.7 (limited to 'doc/man') diff --git a/doc/man/bus-broadcast.1 b/doc/man/bus-broadcast.1 new file mode 100644 index 0000000..e6094be --- /dev/null +++ b/doc/man/bus-broadcast.1 @@ -0,0 +1,34 @@ +.TH BUS-BROADCAST 1 BUS-%VERSION% +.SH NAME +bus broadcast - Broadcast a message on a bus +.SH SYNOPSIS +.B bus broadcast +.IR [options] +[--] +.IR pathname +.IR message +.SH DESCRIPTION +Broadcast \fImessage\fP on the bus associated with \fIpathname\fP. +.SH OPTIONS +.TP +.B \-n +Fail if another process is attempting to broadcast on the bus. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +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 +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org diff --git a/doc/man/bus-chgrp.1 b/doc/man/bus-chgrp.1 new file mode 100644 index 0000000..d825e32 --- /dev/null +++ b/doc/man/bus-chgrp.1 @@ -0,0 +1,38 @@ +.TH BUS-CHGRP 1 BUS-%VERSION% +.SH NAME +bus chgrp - Change group ownership of a bus +.SH SYNOPSIS +.B bus chgrp +[--] +.IR group +.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 +with a GID or with a group name. +.PP +The current ownership of a bus can be retrieved by running +.BR stat (1) +over the \fIpathname\fP of the bus. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus-chown (1), +.BR bus-chmod (1), +.BR stat (1) +.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/man/bus-chmod.1 b/doc/man/bus-chmod.1 new file mode 100644 index 0000000..24f97e6 --- /dev/null +++ b/doc/man/bus-chmod.1 @@ -0,0 +1,49 @@ +.TH BUS-CHMOD 1 BUS-%VERSION% +.SH NAME +bus chmod - Change permissions on a bus +.SH SYNOPSIS +.B bus chmod +[--] +.IR permissions +.IR pathname +.SH DESCRIPTION +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 +that all user classes list after it, and only those classes, as +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. +.PP +The current permissions of a bus can be retrieved by running +.BR stat (1) +over the \fIpathname\fP of the bus. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus-chown (1), +.BR bus-chgrp (1), +.BR stat (1) +.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/man/bus-chown.1 b/doc/man/bus-chown.1 new file mode 100644 index 0000000..24487a1 --- /dev/null +++ b/doc/man/bus-chown.1 @@ -0,0 +1,41 @@ +.TH BUS-CHOWN 1 BUS-%VERSION% +.SH NAME +bus chown - Change ownership of a bus +.SH SYNOPSIS +.B bus chown +[--] +.IR owner[:group] +.IR pathname +.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. +.PP +The current ownership of a bus can be retrieved by running +.BR stat (1) +over the \fIpathname\fP of the bus. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus-chgrp (1), +.BR bus-chmod (1), +.BR stat (1) +.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/man/bus-create.1 b/doc/man/bus-create.1 new file mode 100644 index 0000000..d0cc27d --- /dev/null +++ b/doc/man/bus-create.1 @@ -0,0 +1,37 @@ +.TH BUS-CREATE 1 BUS-%VERSION% +.SH NAME +bus create - Create a bus +.SH SYNOPSIS +.B bus create +.IR [options] +[--] +.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. +.SH OPTIONS +.TP +.B \-x +Fail if the \fIpathname\fP already exists. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus (5), +.BR bus-remove (1) +.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/man/bus-listen.1 b/doc/man/bus-listen.1 new file mode 100644 index 0000000..4977ce5 --- /dev/null +++ b/doc/man/bus-listen.1 @@ -0,0 +1,32 @@ +.TH BUS-LISTEN 1 BUS-%VERSION% +.SH NAME +bus listen - Listen for new messages on a bus +.SH SYNOPSIS +.B bus listen +[--] +.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 \fI$msg\fP set +to the received message. POSIX shell syntax applies to \fIcommand\fP. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus (5) +.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/man/bus-remove.1 b/doc/man/bus-remove.1 new file mode 100644 index 0000000..8bebce6 --- /dev/null +++ b/doc/man/bus-remove.1 @@ -0,0 +1,28 @@ +.TH BUS-REMOVE 1 BUS-%VERSION% +.SH NAME +bus remove - Remove a bus +.SH SYNOPSIS +.B bus remove +[--] +.IR pathname +.SH DESCRIPTION +Remove the bus associated with \fIpathname\fP. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +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 +See the LICENSE file for the terms of redistribution. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org diff --git a/doc/man/bus-wait.1 b/doc/man/bus-wait.1 new file mode 100644 index 0000000..4231cd0 --- /dev/null +++ b/doc/man/bus-wait.1 @@ -0,0 +1,33 @@ +.TH BUS-WAIT 1 BUS-%VERSION% +.SH NAME +bus wait - Listen for a new message on a bus +.SH SYNOPSIS +.B bus wait +[--] +.IR pathname +.IR command +.SH DESCRIPTION +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$msg\fP set to the received +message. POSIX shell syntax applies to \fIcommand\fP. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.BR bus (5) +.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/man/bus.1 b/doc/man/bus.1 new file mode 100644 index 0000000..afb3925 --- /dev/null +++ b/doc/man/bus.1 @@ -0,0 +1,77 @@ +.TH BUS 1 BUS-%VERSION% +.SH NAME +bus - A simple daemonless system for broadcasting messages locally +.SH SYNOPSIS +.B bus +.IR command +.IR argument\ ... +.SH COMMANDS +.TP +.B create +Create a bus, see +.BR bus-create (1) +for further details. +.TP +.B remove +Remove a bus, see +.BR bus-remove (1) +for further details. +.TP +.B listen +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, see +.BR bus-wait (1) +for further details. +.TP +.B broadcast +Broadcast a message on a bus, see +.BR bus-broadcast (1) +for further details. +.TP +.B chmod +Change permissions on a bus, see +.BR bus-chmod (1) +for further details. +.TP +.B chown +Change ownership of a bus, see +.BR bus-chown (1) +for further details. +.TP +.B chgrp +Change group ownership of a bus, see +.BR bus-chgrp (1) +for further details. +.SH EXIT STATUS +.TP +0 +The command was successful. +.TP +1 +The command failed. +.TP +2 +The command is not recognised. +.SH SEE ALSO +.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. +.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/man/bus.5 b/doc/man/bus.5 new file mode 100644 index 0000000..0a5de7e --- /dev/null +++ b/doc/man/bus.5 @@ -0,0 +1,50 @@ +.TH BUS 5 BUS-%VERSION% +.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. +.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 +.B GENERIC +For the bus used in generic cases. That is all but the cases of the +buses listed below. +.TP +.B AUDIO +For the bus used in with the audio subsystem is involved. +.TP +.B VIDEO +For the bus used in with the video subsystem is involved. +.TP +.B INPUT +For the bus used in with the input subsystem is involved. +.TP +.B FILES +For the bus used in with the storage subsystem is involved. +.PP +Messages broadcasted on a bus cannot be longer than 2047 bytes, +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, or 0 if ephemeral, +whence the message originated, followed by a single regular space. +.SH SEE ALSO +.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. +.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/man/bus_chmod.3 b/doc/man/bus_chmod.3 new file mode 100644 index 0000000..c2ac3f9 --- /dev/null +++ b/doc/man/bus_chmod.3 @@ -0,0 +1,64 @@ +.TH BUS_CHMOD 3 BUS-%VERSION% +.SH NAME +bus_chmod - Change bus mode bits +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_chmod(const char *\fIfile\fP, mode_t \fImode\fP); +.fi +.SH DESCRIPTION +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. +.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. +.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 +access. +.PP +The current permissions of a bus can be retrieved by running +.BR stat (3) +over the \fIpathname\fP of the bus. +.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) +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) +and +.BR shmctl (3) +as well as any errors specified for the \fIIPC_STAT\fP and +\fIIPC_SET\fP commands for +.BR semctl (3). +.SH SEE ALSO +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_read (3), +.BR stat (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/man/bus_chown.3 b/doc/man/bus_chown.3 new file mode 100644 index 0000000..fcde96b --- /dev/null +++ b/doc/man/bus_chown.3 @@ -0,0 +1,51 @@ +.TH BUS_CHOWN 3 BUS-%VERSION% +.SH NAME +bus_chown - Change bus owner and group +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_chown(const char *\fIfile\fP, uid_t \fIowner\fP, gid_t \fIgroup\fP); +.fi +.SH DESCRIPTION +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. +.PP +The current ownership of a bus can be retrieved by running +.BR stat (3) +over the \fIpathname\fP of the bus. +.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) +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) +and +.BR shmctl (3) +as well as any errors specified for the \fIIPC_STAT\fP and +\fIIPC_SET\fP commands for +.BR semctl (3). +.SH SEE ALSO +.BR bus-create (1), +.BR bus (5), +.BR libbus (7), +.BR bus_open (3), +.BR bus_read (3), +.BR stat (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/man/bus_close.3 b/doc/man/bus_close.3 new file mode 100644 index 0000000..734f18d --- /dev/null +++ b/doc/man/bus_close.3 @@ -0,0 +1,36 @@ +.TH BUS_CLOSE 3 BUS-%VERSION% +.SH NAME +bus_close - Close a bus +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_close(bus_t *\fIbus\fP); +.fi +.SH DESCRIPTION +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 returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The bus does not exist. +.SH SEE ALSO +.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. +.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/man/bus_create.3 b/doc/man/bus_create.3 new file mode 100644 index 0000000..158c755 --- /dev/null +++ b/doc/man/bus_create.3 @@ -0,0 +1,63 @@ +.TH BUS_CREATE 3 BUS-%VERSION% +.SH NAME +bus_create - Create a new bus +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_create(const char *\fIfile\fP, int \fIflags\fP, char **\fIout_file\fP); +.fi +.SH DESCRIPTION +The +.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 +by +.BR bus(5). +.PP +If \fIfile\fP is not \fINULL\fP the +.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 () +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 returns 0. Otherwise the +function return -1 with \fIerrno\fP set to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +The process cannot allocate more memory. +.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 +.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. +.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/man/bus_open.3 b/doc/man/bus_open.3 new file mode 100644 index 0000000..f20ceba --- /dev/null +++ b/doc/man/bus_open.3 @@ -0,0 +1,67 @@ +.TH BUS_OPEN 3 BUS-%VERSION% +.SH NAME +bus_open - Open a bus +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_open(bus_t *\fIbus\fP, const char *\fIfile\fP, int \fIflags\fP); +.fi +.SH DESCRIPTION +The +.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 () +functions. +.PP +Values for \fIflags\fP are constructed by a bitwise inclusive OR of +flags from the following list. +.TP +.B BUS_RDONLY +The process will only be using the bus for receiving messages. +.TP +.B BUS_WRONLY +The process will only be using the bus for sending messages. +.TP +.B BUS_RDWR +The process will use the bus for both receiving and sending messages. +.SH RETURN VALUES +Upon successful completion the function returns 0. Otherwise the +function returns -1 and set \fIerrno\fP to indicate the error. +.SH ERRORS +.TP +.B ENOMEM +The process cannot allocate more memory. +.TP +.B EACCES +Operation permission is denied to the calling process. +.TP +.B EINVAL +The described bus does not exist. +.PP +The +.BR bus_open () +function may also fail and set \fIerrno\fP to any of the errors +specified for the routine +.BR open (2). +.SH SEE ALSO +.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. +.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/man/bus_poll.3 b/doc/man/bus_poll.3 new file mode 100644 index 0000000..b22115c --- /dev/null +++ b/doc/man/bus_poll.3 @@ -0,0 +1,87 @@ +.TH BUS_POLL 3 BUS-%VERSION% +.SH NAME +bus_poll_start, bus_poll_stop, bus_poll, bus_poll_timed - Wait a message to be broadcasted +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_poll_start(bus_t *\fIbus\fP); +int bus_poll_stop(const bus_t *\fIbus\fP); +const char *bus_poll(bus_t *\fIbus\fP, int \fIflags\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 () +function waits for a message to broadcasted on the \fIbus\fP, and return +the message it receives. The function fails if (\fIflags\fP &BUS_NOWAIT) +and there is not already a message waiting on the bus. Received messages +shall be copied and parsed, and acted upon, in a separate thread, and +.BR bus_poll () +or +.BR bus_poll_stop () +called again as soon as possible. +.PP +The +.BR bus_poll_start () +funcion must be called before +.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 () +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. +.SH RETURN VALUES +Upon successful completion, the functions +.BR bus_poll_start () +and +.BR bus_poll_stop () +returns 0. Otherwise the functions returns -1 and sets \fIerrno\fP to +indicate the error. +.PP +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) +and +.BR bus_poll_stop (3) +functions may fail and set \fIerrno\fP to any of the errors specified for +.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 +.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. +.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/man/bus_read.3 b/doc/man/bus_read.3 new file mode 100644 index 0000000..0bea94a --- /dev/null +++ b/doc/man/bus_read.3 @@ -0,0 +1,76 @@ +.TH BUS_READ 3 BUS-%VERSION% +.SH NAME +bus_read, bus_read_timed - Listen for new messages a bus +.SH SYNOPSIS +.LP +.nf +#include +.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 () +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 () +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 +.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, these functions returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. +.SH ERRORS +The +.BR bus_read (3) +function may fail and set \fIerrno\fP to any of the errors specified for +.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 +.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. +.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/man/bus_unlink.3 b/doc/man/bus_unlink.3 new file mode 100644 index 0000000..83ec760 --- /dev/null +++ b/doc/man/bus_unlink.3 @@ -0,0 +1,56 @@ +.TH BUS_UNLINK 3 BUS-%VERSION% +.SH NAME +bus_unlink - Remove a bus +.SH SYNOPSIS +.LP +.nf +#include +.P +int bus_unlink(const char *\fIfile\fP); +.fi +.SH DESCRIPTION +The +.BR bus_unlink () +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 returns 0. Otherwise the +function returns -1 and sets \fIerrno\fP to indicate the error. +.SH ERRORS +.TP +.B EINVAL +The bus does not exist. +.TP +.B EACCES +Operation permission is denied to the calling process. +.TP +.B EPERM +The user does not have permission to remove the bus. +.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 +.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. +.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/man/bus_write.3 b/doc/man/bus_write.3 new file mode 100644 index 0000000..4513c29 --- /dev/null +++ b/doc/man/bus_write.3 @@ -0,0 +1,64 @@ +.TH BUS_WRITE 3 BUS-%VERSION% +.SH NAME +bus_write, bus_write_timed - Broadcast a message a bus +.SH SYNOPSIS +.LP +.nf +#include +.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 +.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 +.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, 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). +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 +.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. +.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/man/libbus.7 b/doc/man/libbus.7 new file mode 100644 index 0000000..804ee97 --- /dev/null +++ b/doc/man/libbus.7 @@ -0,0 +1,39 @@ +.TH LIBBUS 7 BUS-%VERSION% +.SH NAME +libbus - A simple daemonless system for broadcasting messages locally +.SH DESCRIPTION +.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 +None. +.SH SEE ALSO +.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. +.SH LICENSE +MIT/X Consortium License. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org -- cgit v1.2.3-70-g09d2