aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMattias Andrée <maandree@operamail.com>2015-04-29 22:30:47 +0200
committerMattias Andrée <maandree@operamail.com>2015-04-29 22:30:47 +0200
commit7754e3c18a7bfed1fea34d286c6f8f8e2f119a0d (patch)
tree9c3a8639d49871d7ce6160a25bb19e3ff373e87c
parent... (diff)
downloadbus-7754e3c18a7bfed1fea34d286c6f8f8e2f119a0d.tar.gz
bus-7754e3c18a7bfed1fea34d286c6f8f8e2f119a0d.tar.bz2
bus-7754e3c18a7bfed1fea34d286c6f8f8e2f119a0d.tar.xz
doc
Signed-off-by: Mattias Andrée <maandree@operamail.com>
Diffstat (limited to '')
-rw-r--r--doc/bus_write.36
-rw-r--r--doc/libbus.75
-rw-r--r--src/bus.c40
-rw-r--r--src/bus.h52
-rw-r--r--src/cmdline.c4
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;