[hackers] [libixp] Partial inline API documentation. Note that there is currently no way to munge this documentation format.

From: Kris Maglione <jg_AT_suckless.org>
Date: Sun Jan 27 19:52:16 2008

changeset: 88:3e1f5e86e99b
tag: tip
user: Kris Maglione <jg_AT_suckless.org>
date: Sun Jan 27 13:48:38 2008 -0500
summary: Partial inline API documentation. Note that there is currently no way to munge this documentation format.

diff -r 721312ae775c -r 3e1f5e86e99b libixp/client.c
--- a/libixp/client.c Sat Jan 26 22:27:42 2008 -0500
+++ b/libixp/client.c Sun Jan 27 13:48:38 2008 -0500
@@ -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;
@@ -112,6 +117,23 @@ allocmsg(IxpClient *c, int n) {
         c->rmsg.data = erealloc(c->rmsg.data, 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) {
@@ -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) {
- Fcall fcall;
- IxpCFid *f;
- char *path;;
-
- path = estrdup(name);
-
- f = walkdir(c, path, &name);
+ixp_create(IxpClient *c, const char *path, uint perm, uchar mode) {
+ Fcall fcall;
+ IxpCFid *f;
+ char *tpath;;
+
+ tpath = estrdup(path);
+
+ 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 *nam
         ixp_freefcall(&fcall);
 
 done:
- free(path);
+ free(tpath);
         return f;
 }
 
 IxpCFid*
-ixp_open(IxpClient *c, const char *name, uchar mode) {
- Fcall fcall;
- IxpCFid *f;
-
- f = walk(c, name);
+ixp_open(IxpClient *c, const char *path, uchar mode) {
+ Fcall fcall;
+ IxpCFid *f;
+
+ f = walk(c, path);
         if(f == nil)
                 return nil;
 
@@ -329,6 +385,16 @@ ixp_open(IxpClient *c, const char *name,
         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);
@@ -356,6 +422,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) {
@@ -404,6 +487,26 @@ _pread(IxpCFid *f, char *buf, long count
         }
         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) {
@@ -453,6 +556,27 @@ _pwrite(IxpCFid *f, const void *buf, lon
         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,
         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 -r 721312ae775c -r 3e1f5e86e99b libixp/error.c
--- a/libixp/error.c Sat Jan 26 22:27:42 2008 -0500
+++ b/libixp/error.c Sun Jan 27 13:48:38 2008 -0500
@@ -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 -r 721312ae775c -r 3e1f5e86e99b libixp/server.c
--- a/libixp/server.c Sat Jan 26 22:27:42 2008 -0500
+++ b/libixp/server.c Sun Jan 27 13:48:38 2008 -0500
@@ -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),
@@ -26,6 +48,17 @@ ixp_listen(IxpServer *s, int fd, void *a
         s->conn = c;
         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) {
@@ -46,6 +79,16 @@ ixp_hangup(IxpConn *c) {
 
         close(c->fd);
         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
@@ -70,6 +113,22 @@ handle_conns(IxpServer *s) {
                         c->read(c);
         }
 }
+
+/**
+ * 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) {
@@ -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 -r 721312ae775c -r 3e1f5e86e99b libixp/socket.c
--- a/libixp/socket.c Sat Jan 26 22:27:42 2008 -0500
+++ b/libixp/socket.c Sun Jan 27 13:48:38 2008 -0500
@@ -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 -r 721312ae775c -r 3e1f5e86e99b libixp/timer.c
--- a/libixp/timer.c Sat Jan 26 22:27:42 2008 -0500
+++ b/libixp/timer.c Sun Jan 27 13:48:38 2008 -0500
@@ -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, vo
         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;
Received on Sun Jan 27 2008 - 19:52:16 UTC

This archive was generated by hypermail 2.2.0 : Sun Jul 13 2008 - 15:59:12 UTC