commit 3f4d1c6275cbdebcc038a87f12020f0c6326ffb5
parent 13f86e09a7683bc31017d2119c012c16fb4f400e
Author: Kris Maglione <jg@suckless.org>
Date: Sun, 27 Jan 2008 13:48:38 -0500
Partial inline API documentation. Note that there is currently no way to munge this documentation format.
Diffstat:
5 files changed, 309 insertions(+), 17 deletions(-)
diff --git a/libixp/client.c b/libixp/client.c
@@ -86,6 +86,11 @@ fail:
return 0;
}
+/**
+ * Function: ixp_unmount
+ *
+ * Unmounts the client P<c> and frees its data structures.
+ */
void
ixp_unmount(IxpClient *c) {
IxpCFid *f;
@@ -113,6 +118,23 @@ allocmsg(IxpClient *c, int n) {
c->wmsg.data = erealloc(c->wmsg.data, n);
}
+/**
+ * Function: ixp_mountfd
+ * Function: ixp_mount
+ *
+ * Params:
+ * fd - A file descriptor which is already connected
+ * to a 9P server.
+ * address - An address (in Plan 9 resource fomat) on
+ * which to connect to a 9P server.
+ *
+ * Initiate a 9P connection with the server at
+ * P<address> or connected to on P<fd>.
+ *
+ * Returns:
+ * A pointer to a new 9P client.
+ */
+
IxpClient*
ixp_mountfd(int fd) {
IxpClient *c;
@@ -242,6 +264,18 @@ clunk(IxpCFid *f) {
return ret;
}
+/**
+ * Function: ixp_remove
+ *
+ * Params:
+ * path - The path of the file to remove.
+ *
+ * Removes a file or directory from the remote server.
+ *
+ * Returns:
+ * ixp_remove returns 0 on failure, 1 on success.
+ */
+
int
ixp_remove(IxpClient *c, const char *path) {
Fcall fcall;
@@ -270,21 +304,43 @@ initfid(IxpCFid *f, Fcall *fcall) {
f->qid = fcall->qid;
}
+/**
+ * Function: ixp_create
+ * Function: ixp_open
+ *
+ * Params:
+ * path - The path of the file to open or create.
+ * perm - The permissions with which to create the new
+ * file. These will be ANDed with those of the
+ * parent directory by the server.
+ * mode - The file's open mode.
+ *
+ * ixp_open and ixp_create each open a file at P<path>.
+ * P<mode> must include OREAD, OWRITE, or ORDWR, and may
+ * include any of the modes specified in 9pmodes(3).
+ * ixp_create, additionally, creates a file at P<path> if it
+ * doesn't already exist.
+ *
+ * Returns:
+ * A pointer on which to operate on the newly
+ * opened file.
+ */
+
IxpCFid*
-ixp_create(IxpClient *c, const char *name, uint perm, uchar mode) {
+ixp_create(IxpClient *c, const char *path, uint perm, uchar mode) {
Fcall fcall;
IxpCFid *f;
- char *path;;
+ char *tpath;;
- path = estrdup(name);
+ tpath = estrdup(path);
- f = walkdir(c, path, &name);
+ f = walkdir(c, tpath, &path);
if(f == nil)
goto done;
fcall.type = TCreate;
fcall.fid = f->fid;
- fcall.name = (char*)(uintptr_t)name;
+ fcall.name = (char*)(uintptr_t)path;
fcall.perm = perm;
fcall.mode = mode;
@@ -300,16 +356,16 @@ ixp_create(IxpClient *c, const char *name, uint perm, uchar mode) {
ixp_freefcall(&fcall);
done:
- free(path);
+ free(tpath);
return f;
}
IxpCFid*
-ixp_open(IxpClient *c, const char *name, uchar mode) {
+ixp_open(IxpClient *c, const char *path, uchar mode) {
Fcall fcall;
IxpCFid *f;
- f = walk(c, name);
+ f = walk(c, path);
if(f == nil)
return nil;
@@ -329,6 +385,16 @@ ixp_open(IxpClient *c, const char *name, uchar mode) {
return f;
}
+/**
+ * Function: ixp_close
+ *
+ * Closes the file pointed to by P<f> and frees its
+ * associated data structures;
+ *
+ * Returns:
+ * Returns 1 on success, and zero on failure.
+ */
+
int
ixp_close(IxpCFid *f) {
return clunk(f);
@@ -357,6 +423,23 @@ _stat(IxpClient *c, ulong fid) {
return stat;
}
+/**
+ * Function: ixp_stat
+ * Function: ixp_fstat
+ *
+ * Params:
+ * path - The path of the file to stat.
+ * f - A CFid of an open file to stat.
+ *
+ * Stats the file at P<path> or pointed to by P<f>.
+ *
+ * Returns:
+ * Returns a Stat structure, which must be freed by
+ * the caller with free(3).
+ *
+ * S<Stat>
+ */
+
Stat*
ixp_stat(IxpClient *c, const char *path) {
Stat *stat;
@@ -405,6 +488,26 @@ _pread(IxpCFid *f, char *buf, long count, vlong offset) {
return len;
}
+/**
+ * Function: ixp_read
+ * Function: ixp_pread
+ *
+ * Params:
+ * buf - A buffer in which to store the read data.
+ * count - The number of bytes to read.
+ * offset - The offset at which to begin reading.
+ *
+ * ixp_read and ixp_pread each read P<count> bytes of data
+ * from the file pointed to by P<f>, into P<buf>. ixp_read
+ * begins reading at its stored offset, and increments it by
+ * the number of bytes read. ixp_pread reads beginning at
+ * P<offset> and does not alter C<f>'s stored offset.
+ *
+ * Returns:
+ * These functions return the number of bytes read on
+ * success and -1 on failure.
+ */
+
long
ixp_read(IxpCFid *f, void *buf, long count) {
int n;
@@ -453,6 +556,27 @@ _pwrite(IxpCFid *f, const void *buf, long count, vlong offset) {
return len;
}
+/**
+ * Function: ixp_write
+ * Function: ixp_pwrite
+ *
+ * Params:
+ * buf - A buffer holding the contents to store.
+ * count - The number of bytes to store.
+ * offset - The offset at which to write the data.
+ *
+ * ixp_write and ixp_pwrite each write P<count> bytes of
+ * data stored in P<buf> to the file pointed to by C<f>.
+ * ixp_write writes its data at its stored offset, and
+ * increments it by P<count>. ixp_pwrite writes its data a
+ * P<offset> and does not alter C<f>'s stored offset.
+ *
+ * Returns:
+ * These functions return the number of bytes actually
+ * written. Any value less than P<count> must be considered
+ * a failure.
+ */
+
long
ixp_write(IxpCFid *f, const void *buf, long count) {
int n;
@@ -475,6 +599,30 @@ ixp_pwrite(IxpCFid *f, const void *buf, long count, vlong offset) {
return n;
}
+/**
+ * Function: ixp_vprint
+ * Function: ixp_print
+ * Variable: ixp_vsmprint
+ *
+ * Params:
+ * fmt - The string with which to format the data.
+ * ap - A va_list holding the arguments to the format
+ * string.
+ * ... - The arguments to the format string.
+ *
+ * These functions act like the standard formatted IO
+ * functions. They write the result of the formatting to the
+ * file pointed to by C<f>.
+ *
+ * V<ixp_vsmprint> may be set to a function which will
+ * format its arguments and return a null terminated string
+ * allocated with malloc(3).
+ *
+ * Returns:
+ * These functions return the number of bytes written.
+ * There is currently no way to detect failure.
+ */
+
int
ixp_vprint(IxpCFid *f, const char *fmt, va_list ap) {
char *buf;
diff --git a/libixp/error.c b/libixp/error.c
@@ -35,6 +35,33 @@ enum {
EPLAN9 = 0x19283745,
};
+/**
+ * Function: ixp_errbuf
+ * Function: ixp_errstr
+ * Function: ixp_rerrstr
+ * Function: ixp_werrstr
+ *
+ * Params:
+ * buf - The buffer to read and/or fill.
+ * n - The size of the buffer.
+ * fmt - A format string with which to write the * errstr.
+ * ... - Arguments to P<fmt>.
+ *
+ * These functions simulate Plan 9's errstr functionality.
+ * They replace errno in libixp. Note that these functions
+ * are not internationalized.
+ *
+ * F<ixp_errbuf> returns the errstr buffer for the current
+ * thread. F<ixp_rerrstr> fills P<buf> with the data from
+ * the current thread's error buffer, while F<ixp_errstr>
+ * exchanges P<buf>'s contents with those of the current
+ * thread's error buffer. F<ixp_werrstr> is takes a format
+ * string from which to construct an errstr.
+ *
+ * Returns:
+ * F<ixp_errbuf> returns the current thread's error
+ * string buffer.
+ */
char*
ixp_errbuf() {
char *errbuf;
diff --git a/libixp/server.c b/libixp/server.c
@@ -9,6 +9,28 @@
#include <unistd.h>
#include "ixp_local.h"
+/**
+ * Function: ixp_listen
+ *
+ * Params:
+ * fs - The file descriptor on which to listen.
+ * aux - A piece of data to store in the connection's
+ * T<IxpConn> data structure.
+ * read - The function to call when the connection has
+ * data available to read.
+ * close - A cleanup function to call when the
+ * connection is closed.
+ *
+ * Starts the server P<s> listening on P<fd>. The optional
+ * callbacks are called as described, with the connections
+ * T<IxpConn> data structure as their arguments.
+ *
+ * Returns:
+ * Returns the connection's new T<IxpConn> data
+ * structure.
+ *
+ * S<IxpConn>
+ */
IxpConn*
ixp_listen(IxpServer *s, int fd, void *aux,
void (*read)(IxpConn *c),
@@ -27,6 +49,17 @@ ixp_listen(IxpServer *s, int fd, void *aux,
return c;
}
+/**
+ * Function: ixp_hangup
+ * Function: ixp_server_close
+ *
+ * ixp_hangup closes a connection, and stops the server
+ * listening on it. It calls the connection's close
+ * function, if it exists. ixp_server_close calls ixp_hangup
+ * on all of the connections on which the server is
+ * listening.
+ */
+
void
ixp_hangup(IxpConn *c) {
IxpServer *s;
@@ -48,6 +81,16 @@ ixp_hangup(IxpConn *c) {
free(c);
}
+void
+ixp_server_close(IxpServer *s) {
+ IxpConn *c, *next;
+
+ for(c = s->conn; c; c = next) {
+ next = c->next;
+ ixp_hangup(c);
+ }
+}
+
static void
prepare_select(IxpServer *s) {
IxpConn *c;
@@ -71,6 +114,22 @@ handle_conns(IxpServer *s) {
}
}
+/**
+ * Function: ixp_serverloop
+ *
+ * Enters the main loop of the server. Exits when
+ * P<s>->running becomes false, or when select(2) returns an
+ * error other than EINTR.
+ *
+ * S<IxpServer>
+ *
+ * Returns:
+ * Returns 0 when the loop exits normally, and 1 when
+ * it exits on error. V<errno> or the return value of
+ * ixp_errbuf(3) may be inspected.
+ *
+ */
+
int
ixp_serverloop(IxpServer *s) {
timeval *tvp;
@@ -104,12 +163,3 @@ ixp_serverloop(IxpServer *s) {
return 0;
}
-void
-ixp_server_close(IxpServer *s) {
- IxpConn *c, *next;
- for(c = s->conn; c; c = next) {
- next = c->next;
- ixp_hangup(c);
- }
-}
-
diff --git a/libixp/socket.c b/libixp/socket.c
@@ -246,6 +246,26 @@ lookup(const char *address, addrtab *tab) {
return ret;
}
+/**
+ * Function: ixp_dial
+ * Function: ixp_announce
+ *
+ * Params:
+ * address - An address on which to connect or listen,
+ * specified in the Plan 9 resources
+ * specification format
+ * (<protocol>!address[!<port>])
+ *
+ * These functions hide some of the ugliness of Berkely
+ * Sockets. ixp_dial connects to the resource at P<address>,
+ * while ixp_announce begins listening on P<address>.
+ *
+ * Returns:
+ * These functions return file descriptors on success,
+ * and -1 on failure. ixp_errbuf(3) may be inspected on
+ * failure.
+ */
+
int
ixp_dial(const char *address) {
return lookup(address, dtab);
diff --git a/libixp/timer.c b/libixp/timer.c
@@ -12,6 +12,13 @@
static long lastid = 1;
+/**
+ * Function: ixp_msec
+ *
+ * Returns:
+ * Returns the time since the Epoch in milliseconds.
+ * Be aware that this may overflow.
+ */
long
ixp_msec(void) {
timeval tv;
@@ -21,6 +28,23 @@ ixp_msec(void) {
return tv.tv_sec*1000 + tv.tv_usec/1000;
}
+/**
+ * Function: ixp_settimer
+ *
+ * Params:
+ * msec - The timeout in milliseconds.
+ * fn - The function to call after P<msec> milliseconds
+ * have elapsed.
+ * aux - An arbitrary argument to pass to P<fn> when it
+ * is called.
+ *
+ * Initializes a callback-based timer to be triggerred after
+ * P<msec> milliseconds. The timer is passed its id number
+ * and the value of P<aux>.
+ *
+ * Returns:
+ * Returns the new timer's unique id number.
+ */
long
ixp_settimer(IxpServer *s, long msec, void (*fn)(long, void*), void *aux) {
Timer **tp;
@@ -48,6 +72,18 @@ ixp_settimer(IxpServer *s, long msec, void (*fn)(long, void*), void *aux) {
return t->id;
}
+/**
+ * Function: ixp_unsettimer
+ *
+ * Params:
+ * id - The id number of the timer to void.
+ *
+ * Voids the timer identified by P<id>.
+ *
+ * Returns:
+ * Returns true if a timer was stopped, false
+ * otherwise.
+ */
int
ixp_unsettimer(IxpServer *s, long id) {
Timer **tp;
@@ -65,6 +101,17 @@ ixp_unsettimer(IxpServer *s, long id) {
return t != nil;
}
+/**
+ * Function: ixp_nexttimer
+ *
+ * Triggers any timers whose timeouts have ellapsed. This is
+ * primarilly intended to be called from libixp's select
+ * loop.
+ *
+ * Returns:
+ * Returns the number of milliseconds until the next
+ * timer's timeout.
+ */
long
ixp_nexttimer(IxpServer *s) {
Timer *t;
