doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

5 files changed, 100 insertions, 7 deletions

diff --git a/doc/bus_write.3 b/doc/bus_write.3
index e058013..fd758be 100644
--- a/doc/bus_write.3
+++ b/doc/bus_write.3
@@ -4,12 +4,16 @@ bus_write - Broadcast a message a bus
 .SH SYNOPSIS
 #include <bus.h>
 
-int bus_write(const bus_t *bus, const char *message);
+int bus_write(const bus_t *bus, const char *message, int flags);
 .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.
+.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).
 .SH RETURN VALUES
 Upon successful completion, the function returns 0.  Otherwise the
 function returns -1 and sets \fIerrno\fP to indicate the error.
diff --git a/doc/libbus.7 b/doc/libbus.7
index c3f14e6..4b0ead4 100644
--- a/doc/libbus.7
+++ b/doc/libbus.7
@@ -10,9 +10,8 @@ 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.
+Private and abstract buses might be interesting.  Timed out read and
+writes might be too.
 .SH SEE ALSO
 bus(1), bus(5), bus_create(3), bus_unlink(3), bus_open(3), bus_close(3),
 bus_read(3), bus_write(3)
diff --git a/src/bus.c b/src/bus.c
index 6c90500..369fa2f 100644
--- a/src/bus.c
+++ b/src/bus.c
@@ -732,6 +732,17 @@ done:
 }
 
 
+/**
+ * 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,
+ * not calling this function will cause the bus the
+ * misbehave, is `bus_poll` is written to expect
+ * this function to have been called.
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int
 bus_poll_start(bus_t *bus)
 {
@@ -740,6 +751,14 @@ bus_poll_start(bus_t *bus)
 }
 
 
+/**
+ * Announce that the thread has stopped listening on the bus.
+ * This is required so that the thread does not cause others
+ * to wait indefinitely.
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int
 bus_poll_stop(const bus_t *bus)
 {
@@ -780,6 +799,16 @@ fail:
 }
 
 
+/**
+ * Change the ownership of a bus
+ * 
+ * `stat(2)` can be used of the bus's associated file to get the bus's ownership
+ * 
+ * @param   file   The pathname of the bus
+ * @param   owner  The user ID of the bus's new owner
+ * @param   group  The group ID of the bus's new group
+ * @return         0 on success, -1 on error
+ */
 int
 bus_chown(const char *file, uid_t owner, gid_t group)
 {
@@ -794,6 +823,17 @@ fail:
 }
 
 
+/**
+ * Change the permissions for a bus
+ * 
+ * `stat(2)` can be used of the bus's associated file to get the bus's permissions
+ * 
+ * @param   file  The pathname of the bus
+ * @param   mode  The permissions of the bus, any permission for a user implies
+ *                full permissions for that user, except only the owner may
+ *                edit the bus's associated file
+ * @return        0 on success, -1 on error
+ */
 int
 bus_chmod(const char *file, mode_t mode)
 {
diff --git a/src/bus.h b/src/bus.h
index ac03106..d8112f2 100644
--- a/src/bus.h
+++ b/src/bus.h
@@ -45,17 +45,17 @@
 /**
  * Open the bus for both reading and writing only
  */
-#define BUS_RDWR    0
+#define BUS_RDWR  0
 
 /**
  * Fail to create bus if its file already exists
  */
-#define BUS_EXCL    2
+#define BUS_EXCL  2
 
 /**
  * Fail if interrupted
  */
-#define BUS_INTR    4
+#define BUS_INTR  4
 
 /**
  * Function shall fail with errno set to `EAGAIN`
@@ -189,11 +189,57 @@ int bus_write(const bus_t *bus, const char *message, int flags);
 int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data);
 
 
+/**
+ * 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,
+ * not calling this function will cause the bus the
+ * misbehave, is `bus_poll` is written to expect
+ * this function to have been called.
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int bus_poll_start(bus_t *bus);
+
+/**
+ * Announce that the thread has stopped listening on the bus.
+ * This is required so that the thread does not cause others
+ * to wait indefinitely.
+ * 
+ * @param   bus  Bus information
+ * @return       0 on success, -1 on error
+ */
 int bus_poll_stop(const bus_t *bus);
 const char *bus_poll(bus_t *bus, int flags);
 
 
+/**
+ * Change the ownership of a bus
+ * 
+ * `stat(2)` can be used of the bus's associated file to get the bus's ownership
+ * 
+ * @param   file   The pathname of the bus
+ * @param   owner  The user ID of the bus's new owner
+ * @param   group  The group ID of the bus's new group
+ * @return         0 on success, -1 on error
+ */
+int bus_chown(const char *file, uid_t owner, gid_t group);
+
+/**
+ * Change the permissions for a bus
+ * 
+ * `stat(2)` can be used of the bus's associated file to get the bus's permissions
+ * 
+ * @param   file  The pathname of the bus
+ * @param   mode  The permissions of the bus, any permission for a user implies
+ *                full permissions for that user, except only the owner may
+ *                edit the bus's associated file
+ * @return        0 on success, -1 on error
+ */
+int bus_chmod(const char *file, mode_t mode);
+
+
 
 #endif
 
diff --git a/src/cmdline.c b/src/cmdline.c
index 03efdf3..bc0d676 100644
--- a/src/cmdline.c
+++ b/src/cmdline.c
@@ -120,6 +120,7 @@ main(int argc, char *argv[])
 	/* Create a new bus with selected name. */
 	if ((argc == 3) && !strcmp(argv[1], "create")) {
 		t(bus_create(argv[2], 0, NULL));
+		/* TODO add -x */
 
 	/* Create a new bus with random name. */
 	} else if ((argc == 2) && !strcmp(argv[1], "create")) {
@@ -150,6 +151,9 @@ main(int argc, char *argv[])
 		t(bus_open(&bus, argv[2], BUS_WRONLY));
 		t(bus_write(&bus, argv[3], 0));
 		t(bus_close(&bus));
+		/* TODO add -n */
+
+	/* TODO add "chmod", "chown" and "chgrp" */
 
 	} else
 		return 2;