From 7754e3c18a7bfed1fea34d286c6f8f8e2f119a0d Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@operamail.com>
Date: Wed, 29 Apr 2015 22:30:47 +0200
Subject: doc
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@operamail.com>
---
 src/bus.c     | 40 ++++++++++++++++++++++++++++++++++++++++
 src/bus.h     | 52 +++++++++++++++++++++++++++++++++++++++++++++++++---
 src/cmdline.c |  4 ++++
 3 files changed, 93 insertions(+), 3 deletions(-)

(limited to 'src')

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;
-- 
cgit v1.2.3-70-g09d2