commit c33be74e6f6da8c6398c1a05821a9601f882a118 parent dae2d922891c00b656296105761335707563d692 Author: Kris Maglione <kris@suckless.org> Date: Fri, 18 Jun 2010 12:15:18 -0400 Add some additional documentation. Diffstat:
48 files changed, 359 insertions(+), 118 deletions(-)
diff --git a/include/ixp.h b/include/ixp.h @@ -680,6 +680,9 @@ struct Ixp9Srv { * only one accessor at a time. Rendezvous points are similar to * pthread condition types. P<errbuf> should return a * thread-local buffer or the size IXP_ERRMAX. + * + * See also: + * F<ixp_pthread_init>, F<ixp_taskinit>, F<ixp_rubyinit> */ struct IxpThread { /* Read/write lock */ diff --git a/lib/libixp/client.c b/lib/libixp/client.c @@ -142,7 +142,7 @@ allocmsg(IxpClient *c, int n) { * Returns: * A pointer to a new 9P client. * See also: - * F<ixp_unmount> + * F<ixp_open>, F<ixp_create>, F<ixp_remove>, F<ixp_unmount> */ IxpClient* @@ -361,7 +361,8 @@ initfid(IxpCFid *f, IxpFcall *fcall) { * opened file. * * See also: - * F<ixp_mount>, F<ixp_read>, F<ixp_write>, F<ixp_close> + * F<ixp_mount>, F<ixp_read>, F<ixp_write>, F<ixp_print>, + * F<ixp_fstat>, F<ixp_close> */ IxpCFid* diff --git a/lib/libixp/server.c b/lib/libixp/server.c @@ -29,6 +29,9 @@ * * Returns: * Returns the connection's new IxpConn data structure. + * + * See also: + * F<ixp_serverloop>, F<ixp_serve9conn>, F<ixp_hangup> */ IxpConn* ixp_listen(IxpServer *srv, int fd, void *aux, @@ -129,7 +132,7 @@ handle_conns(IxpServer *s) { * it exits on error. V<errno> or the return value of * F<ixp_errbuf> may be inspected. * See also: - * F<ixp_listen> + * F<ixp_listen>, F<ixp_settimer> */ int diff --git a/lib/libixp_pthread/thread_pthread.c b/lib/libixp_pthread/thread_pthread.c @@ -10,10 +10,21 @@ static IxpThread ixp_pthread; static pthread_key_t errstr_k; +/** + * Function: ixp_pthread_init + * + * This function initializes libixp for use in multithreaded + * programs using the POSIX thread system. When using libixp in such + * programs, this function must be called before any other libixp + * functions. This function is part of libixp_pthread, which you + * must explicitly link against. + */ int ixp_pthread_init() { int ret; + IXP_ASSERT_VERSION; + ret = pthread_key_create(&errstr_k, free); if(ret) { werrstr("can't create TLS value: %s", ixp_errbuf()); diff --git a/lib/libixp_rubythread/thread_ruby.c b/lib/libixp_rubythread/thread_ruby.c @@ -10,6 +10,19 @@ static IxpThread ixp_rthread; static char RWLock[]; +/** + * Function: ixp_rubyinit + * + * This function initializes libixp for use in multithreaded + * programs embedded in the ruby interpreter. When using a pthread + * edition of ruby, ixp_pthread_init should be used instead. When + * using libixp in such programs, this function must be called + * before any other libixp functions. + * + * This function is part of libixp_rubythread, which is part of the + * libixp distribution, but is not built by default unless enabled + * in config.mk. + */ int ixp_rubyinit(void) { rb_require("thread.rb"); diff --git a/lib/libixp_task/thread_task.c b/lib/libixp_task/thread_task.c @@ -8,6 +8,18 @@ static IxpThread ixp_task; +/** + * Function: ixp_taskinit + * + * This function initializes libixp for use in multithreaded + * programs using the libtask threading system. When using libixp in + * such programs, this function must be called before any other + * libixp functions. + * + * This function is part of libixp_task, which is part of the libixp + * distribution, but is not built by default unless enabled in + * config.mk. + */ int ixp_taskinit() { ixp_thread = &ixp_task; diff --git a/man/Ixp9Srv.3 b/man/Ixp9Srv.3 @@ -45,8 +45,8 @@ Ixp9Srv, Ixp9Req, ixp_serve9conn .SH DESCRIPTION .P The ixp_serve9conn handles incoming 9P connections. It is -ordinarily passed as the \fIread\fR member to \fBixp_listen(3)\fR with an -Ixp9Srv structure passed as the \fIaux\fR member. The handlers +ordinarily passed as the Iread R member to \fBixp_listen(3)\fR with an +Ixp9Srv structure passed as the Iaux R member. The handlers defined in the Ixp9Srv structure are called whenever a matching Fcall type is received. The handlers are expected to call \fBixp_respond(3)\fR at some point, whether before they return or at @@ -58,7 +58,7 @@ structures. .P Whenever a file is closed and an \fBIxpFid(3)\fR is about to be freed, -the \fIfreefid\fR member is called to perform any necessary cleanup +the Ifreefid R member is called to perform any necessary cleanup and to free any associated resources. .SH SEE ALSO diff --git a/man/IxpFcall.3 b/man/IxpFcall.3 @@ -162,7 +162,7 @@ IxpFcall, IxpFType, IxpFAttach, IxpFError, IxpFHdr, IxpFIO, IxpFRAuth, IxpFROpen .SH DESCRIPTION .P The IxpFcall structure represents a 9P protocol message. The -\fIhdr\fR element is common to all Fcall types, and may be used to + Ihdr R element is common to all Fcall types, and may be used to determine the type and tag of the message. The IxpFcall type is used heavily in server applications, where it both presents a request to handler functions and returns a response to the @@ -170,11 +170,11 @@ client. .P Each member of the IxpFcall structure represents a certain -message type, which can be discerned from the \fIhdr.type\fR field. +message type, which can be discerned from the Ihdr.type R field. This value corresponds to one of the IxpFType constants. Types with significant overlap use the same structures, thus TRead and RWrite are both represented by IxpFIO and can be accessed via the -\fIio\fR member as well as \fItread\fR and \fIrwrite\fR respectively. + Iio R member as well as Itread R and Irwrite R respectively. .SH SEE ALSO .P diff --git a/man/IxpFid.3 b/man/IxpFid.3 @@ -27,7 +27,7 @@ IxpFid Represents an open file for a 9P connection. The same structure persists as long as the file remains open, and is installed in the \fBIxp9Req(3)\fR structure for any request Fcall -which references it. Handlers may use the \fIaux\fR member to +which references it. Handlers may use the Iaux R member to store any data which must persist for the life of the open file. diff --git a/man/IxpMsg.3 b/man/IxpMsg.3 @@ -30,19 +30,19 @@ IxpMsg, IxpMsgMode, ixp_message The IxpMsg struct represents a binary message, and is used extensively by libixp for converting messages to and from wire format. The location and size of a buffer are stored in -\fIdata\fR and \fIsize\fR, respectively. \fIpos\fR points to the + Idata R and Isize R, respectively. Ipos R points to the location in the message currently being packed or unpacked, -while \fIend\fR points to the end of the message. The packing -functions advance \fIpos\fR as they go, always ensuring that -they don't read or write past \fIend\fR. When a message is -entirely packed or unpacked, \fIpos\fR whould be less than or -equal to \fIend\fR. Any other state indicates error. +while Iend R points to the end of the message. The packing +functions advance Ipos R as they go, always ensuring that +they don't read or write past Iend R. When a message is +entirely packed or unpacked, Ipos R whould be less than or +equal to Iend R. Any other state indicates error. .P ixp_message is a convenience function to pack a construct an -IxpMsg from a buffer of a given \fIlength\fR and a given -\fImode\fR. \fIpos\fR and \fIdata\fR are set to \fIdata\fR and \fIend\fR is -set to \fIdata\fR + \fIlength\fR. +IxpMsg from a buffer of a given Ilength R and a given + Imode R. Ipos R and Idata R are set to Idata R and Iend R is +set to Idata R + Ilength R. .SH SEE ALSO .P diff --git a/man/IxpThread.3 b/man/IxpThread.3 @@ -72,9 +72,13 @@ Read/write locks should allow multiple readers and a single writer of a shared resource, but should not allow new readers while a writer is waitng for a lock. Mutexes should allow only one accessor at a time. Rendezvous points are similar to -pthread condition types. \fIerrbuf\fR should return a +pthread condition types. Ierrbuf R should return a thread\-local buffer or the size IXP_ERRMAX. +.SH SEE ALSO +.P +ixp_pthread_init(3), ixp_taskinit(3), ixp_rubyinit(3) + .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) .\" cmdline: txt2tags -o- IxpThread.man3 diff --git a/man/Makefile b/man/Makefile @@ -3,7 +3,7 @@ include $(ROOT)/mk/hdr.mk include $(ROOT)/mk/ixp.mk include targets.mk -MANPAGES += ixpc.1 +MANPAGES += ixpc.1 libixp.3 ixp_srvutils.3 include $(ROOT)/mk/man.mk diff --git a/man/header.t2t b/man/header.t2t @@ -1,9 +1,12 @@ %!target: man %!encoding: UTF-8 +%# There's apparently no other way to do this. +%!postproc(man): "^(.TH.*?) 1 " "\1 3 " + %!preproc: \bPROVISIONAL\b **PROVISIONAL** -%!preproc: [FSTV]<(.*?)> **\1(3)** -%!preproc: [P]<(.*?)> //\1// +%!preproc: [FMSTV]<(.*?)> **\1(3)** +%!postproc(man): [P]<(.*?)> \fI\1\fR %!postproc(man): (\[.*?\]) \\fI\1\\fR %!postproc(man): \+$ \n.P diff --git a/man/ixp_close.3 b/man/ixp_close.3 @@ -13,7 +13,7 @@ ixp_close .SH DESCRIPTION .P -Closes the file pointed to by \fIf\fR and frees its +Closes the file pointed to by If R and frees its associated data structures; .SH RETURN VALUE diff --git a/man/ixp_dial.3 b/man/ixp_dial.3 @@ -24,8 +24,8 @@ specification format .SH DESCRIPTION .P These functions hide some of the ugliness of Berkely -Sockets. ixp_dial connects to the resource at \fIaddress\fR, -while ixp_announce begins listening on \fIaddress\fR. +Sockets. ixp_dial connects to the resource at Iaddress R, +while ixp_announce begins listening on Iaddress R. .SH RETURN VALUE .P diff --git a/man/ixp_errbuf.3 b/man/ixp_errbuf.3 @@ -31,7 +31,7 @@ fmt A format string with which to write the errstr. .TP .RB ... -Arguments to \fIfmt\fR. +Arguments to Ifmt R. .SH DESCRIPTION .P @@ -41,16 +41,16 @@ are not internationalized. .P \fBixp_errbuf(3)\fR returns the errstr buffer for the current -thread. \fBixp_rerrstr(3)\fR fills \fIbuf\fR with the data from +thread. \fBixp_rerrstr(3)\fR fills Ibuf R with the data from the current thread's error buffer, while \fBixp_errstr(3)\fR -exchanges \fIbuf\fR's contents with those of the current +exchanges Ibuf R's contents with those of the current thread's error buffer. \fBixp_werrstr(3)\fR formats the given -format string, \fIfmt\fR, via \fBixp_vsnprint(3)\fR and writes it to +format string, Ifmt R, via \fBixp_vsnprint(3)\fR and writes it to the error buffer. .P \fBixp_vsnprint(3)\fR may be set to a function which will format -its arguments write the result to the \fInbuf\fR length buffer +its arguments write the result to the Inbuf R length buffer \fBbuf(3)\fR. The default value is \fBvsnprintf(3)\fR. The function must format '%s' as a nul\-terminated string and may not consume any arguments not indicated by a %\-prefixed format specifier, diff --git a/man/ixp_listen.3 b/man/ixp_listen.3 @@ -17,7 +17,7 @@ ixp_listen, IxpConn int fd; /* The file descriptor of the connection. */ void (*read)(IxpConn *); void (*close)(IxpConn *); - char closed; /* Non-zero when //fd// has been closed. */ + char closed; /* Non-zero when Ifd R has been closed. */ /* Private members */ ... @@ -31,7 +31,7 @@ The file descriptor on which to listen. .TP aux A piece of data to store in the connection's -\fIaux\fR member of the IxpConn data structure. + Iaux R member of the IxpConn data structure. .TP read The function called when the connection has @@ -43,14 +43,18 @@ connection is closed. .SH DESCRIPTION .P -Starts the server \fIsrv\fR listening on \fIfd\fR. The optional -\fIread\fR and \fIclose\fR callbacks are called with the IxpConn +Starts the server Isrv R listening on Ifd R. The optional + Iread R and Iclose R callbacks are called with the IxpConn structure for the connection as their sole argument. .SH RETURN VALUE .P Returns the connection's new IxpConn data structure. +.SH SEE ALSO +.P +ixp_serverloop(3), ixp_serve9conn(3), ixp_hangup(3) + .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) .\" cmdline: txt2tags -o- ixp_listen.man3 diff --git a/man/ixp_mount.3 b/man/ixp_mount.3 @@ -41,9 +41,9 @@ namespace directory. .SH DESCRIPTION .P -Initiate a 9P connection with the server at \fIaddress\fR, -connected to on \fIfd\fR, or under the process's namespace -directory as \fIname\fR. +Initiate a 9P connection with the server at Iaddress R, +connected to on Ifd R, or under the process's namespace +directory as Iname R. .SH RETURN VALUE .P @@ -51,7 +51,7 @@ A pointer to a new 9P client. .SH SEE ALSO .P -ixp_unmount(3) +ixp_open(3), ixp_create(3), ixp_remove(3), ixp_unmount(3) .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) diff --git a/man/ixp_open.3 b/man/ixp_open.3 @@ -57,10 +57,10 @@ The file's open mode. .SH DESCRIPTION .P -ixp_open and ixp_create each open a file at \fIpath\fR. -\fImode\fR must include OREAD, OWRITE, or ORDWR, and may +ixp_open and ixp_create each open a file at Ipath R. + Imode R must include OREAD, OWRITE, or ORDWR, and may include any of the modes specified in \fBIxpOMode(3)\fR. -ixp_create, additionally, creates a file at \fIpath\fR if it +ixp_create, additionally, creates a file at Ipath R if it doesn't already exist. .SH RETURN VALUE @@ -70,7 +70,8 @@ opened file. .SH SEE ALSO .P -ixp_mount(3), ixp_read(3), ixp_write(3), ixp_close(3) +ixp_mount(3), ixp_read(3), ixp_write(3), ixp_print(3), +ixp_fstat(3), ixp_close(3) .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) diff --git a/man/ixp_pdata.3 b/man/ixp_pdata.3 @@ -13,16 +13,16 @@ ixp_pdata .SH DESCRIPTION .P -Packs or unpacks a raw character buffer of size \fIlen\fR. +Packs or unpacks a raw character buffer of size Ilen R. .P -If \fImsg\fR\->mode is MsgPack, buffer pointed to by \fIdata\fR is -packed into the buffer at \fImsg\fR\->pos. If \fImsg\fR\->mode is -MsgUnpack, the address pointed to by \fIs\fR is loaded with a +If Imsg R\->mode is MsgPack, buffer pointed to by Idata R is +packed into the buffer at Imsg R\->pos. If Imsg R\->mode is +MsgUnpack, the address pointed to by Is R is loaded with a malloc(3) allocated buffer with the contents of the buffer at -\fImsg\fR\->pos. In either case, \fImsg\fR\->pos is advanced by the + Imsg R\->pos. In either case, Imsg R\->pos is advanced by the number of bytes read or written. If the action would advance -\fImsg\fR\->pos beyond \fImsg\fR\->end, \fImsg\fR\->pos is still advanced + Imsg R\->pos beyond Imsg R\->end, Imsg R\->pos is still advanced but no other action is taken. .SH SEE ALSO diff --git a/man/ixp_pending_write.3 b/man/ixp_pending_write.3 @@ -31,15 +31,15 @@ These functions aid in writing virtual files used for broadcasting events or writing data when it becomes available. When a file to be used with these functions is opened, ixp_pending_pushfid should be called with its -\fBIxpFid(3)\fR as an argument. This sets the IxpFid's \fIpending\fR +\fBIxpFid(3)\fR as an argument. This sets the IxpFid's Ipending R member to true. Thereafter, for each file with its -\fIpending\fR member set, ixp_pending_respond should be called + Ipending R member set, ixp_pending_respond should be called for each TRead request, ixp_pending_clunk for each TClunk request, and ixp_pending_flush for each TFlush request. .P -ixp_pending_write queues the data in \fIdat\fR of length \fIndat\fR -to be written to each currently pending fid in \fIpending\fR. If +ixp_pending_write queues the data in Idat R of length Indat R +to be written to each currently pending fid in Ipending R. If there is a read request pending for a given fid, the data is written immediately. Otherwise, it is written the next time ixp_pending_respond is called. Likewise, if there is data @@ -53,7 +53,7 @@ time. .SH RETURN VALUE .P -ixp_pending_clunk returns true if \fIpending\fR has any +ixp_pending_clunk returns true if Ipending R has any more pending IxpFids. diff --git a/man/ixp_pfcall.3 b/man/ixp_pfcall.3 @@ -30,7 +30,7 @@ ixp_pstring. .P ixp_sizeof_stat returns the size of the packed represention -of \fIstat\fR. +of Istat R. .SH SEE ALSO .P diff --git a/man/ixp_pstring.3 b/man/ixp_pstring.3 @@ -19,14 +19,14 @@ integer followed by the contents of the string. The unpacked representation is a nul\-terminated character array. .P -If \fImsg\fR\->mode is MsgPack, the string pointed to by \fIs\fR is -packed into the buffer at \fImsg\fR\->pos. If \fImsg\fR\->mode is -MsgUnpack, the address pointed to by \fIs\fR is loaded with a +If Imsg R\->mode is MsgPack, the string pointed to by Is R is +packed into the buffer at Imsg R\->pos. If Imsg R\->mode is +MsgUnpack, the address pointed to by Is R is loaded with a malloc(3) allocated, nul\-terminated representation of the -string packed at \fImsg\fR\->pos. In either case, \fImsg\fR\->pos is +string packed at Imsg R\->pos. In either case, Imsg R\->pos is advanced by the number of bytes read or written. If the -action would advance \fImsg\fR\->pos beyond \fImsg\fR\->end, -\fImsg\fR\->pos is still advanced but no other action is taken. +action would advance Imsg R\->pos beyond Imsg R\->end, + Imsg R\->pos is still advanced but no other action is taken. .SH SEE ALSO .P diff --git a/man/ixp_pstrings.3 b/man/ixp_pstrings.3 @@ -19,22 +19,22 @@ an array of strings as packed by \fBixp_pstring(3)\fR. The unpacked representation is an array of nul\-terminated character arrays. .P -If \fImsg\fR\->mode is MsgPack, \fI*num\fR strings in the array -pointed to by \fIstrings\fR are packed into the buffer at -\fImsg\fR\->pos. If \fImsg\fR\->mode is MsgUnpack, \fI*num\fR is loaded +If Imsg R\->mode is MsgPack, I*num R strings in the array +pointed to by Istrings R are packed into the buffer at + Imsg R\->pos. If Imsg R\->mode is MsgUnpack, I*num R is loaded with the number of strings unpacked, the array at -\fI*strings\fR is loaded with pointers to the unpacked strings, -and \fI(*strings)\fI[0]\fR\fR must be freed by the user. In either -case, \fImsg\fR\->pos is advanced by the number of bytes read or -written. If the action would advance \fImsg\fR\->pos beyond -\fImsg\fR\->end, \fImsg\fR\->pos is still advanced, but no other -action is taken. If \fI*num\fR is greater than \fImax\fR, -\fImsg\fR\->pos is set beyond \fImsg\fR\->end and no other action is + I*strings R is loaded with pointers to the unpacked strings, +and I(*strings)\fI[0]\fR R must be freed by the user. In either +case, Imsg R\->pos is advanced by the number of bytes read or +written. If the action would advance Imsg R\->pos beyond + Imsg R\->end, Imsg R\->pos is still advanced, but no other +action is taken. If I*num R is greater than Imax R, + Imsg R\->pos is set beyond Imsg R\->end and no other action is taken. .SH SEE ALSO .P -\fIIxpMsg\fR, \fIixp_pstring\fR, \fIixp_pdata\fR + IIxpMsg R, Iixp_pstring R, Iixp_pdata R .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) diff --git a/man/ixp_pthread_init.3 b/man/ixp_pthread_init.3 @@ -0,0 +1,25 @@ +.TH "IXP_PTHREAD_INIT" 3 "2010 Jun" "libixp Manual" + +.SH NAME +.P +ixp_pthread_init + +.SH SYNOPSIS +.nf + #include <ixp.h> + + int ixp_pthread_init(void); +.fi + +.SH DESCRIPTION +.P +This function initializes libixp for use in multithreaded +programs using the POSIX thread system. When using libixp in such +programs, this function must be called before any other libixp +functions. This function is part of libixp_pthread, which you +must explicitly link against. + + +.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) +.\" cmdline: txt2tags -o- ixp_pthread_init.man3 + diff --git a/man/ixp_pu8.3 b/man/ixp_pu8.3 @@ -23,12 +23,12 @@ These functions pack or unpack an unsigned integer of the specified size. .P -If \fImsg\fR\->mode is MsgPack, the value pointed to by \fIval\fR is -packed into the buffer at \fImsg\fR\->pos. If \fImsg\fR\->mode is -MsgUnpack, the packed value at \fImsg\fR\->pos is loaded into the -location pointed to by \fIval\fR. In both cases, \fImsg\fR\->pos is +If Imsg R\->mode is MsgPack, the value pointed to by Ival R is +packed into the buffer at Imsg R\->pos. If Imsg R\->mode is +MsgUnpack, the packed value at Imsg R\->pos is loaded into the +location pointed to by Ival R. In both cases, Imsg R\->pos is advanced by the number of bytes read or written. If the call -would advance \fImsg\fR\->pos beyond \fImsg\fR\->end, \fImsg\fR\->pos is +would advance Imsg R\->pos beyond Imsg R\->end, Imsg R\->pos is advanced, but nothing is modified. .SH SEE ALSO diff --git a/man/ixp_read.3 b/man/ixp_read.3 @@ -26,11 +26,11 @@ The offset at which to begin reading. .SH DESCRIPTION .P -ixp_read and ixp_pread each read \fIcount\fR bytes of data -from the file pointed to by \fIfid\fR, into \fIbuf\fR. ixp_read +ixp_read and ixp_pread each read Icount R bytes of data +from the file pointed to by Ifid R, into Ibuf R. ixp_read begins reading at its stored offset, and increments it by the number of bytes read. ixp_pread reads beginning at -\fIoffset\fR and does not alter \fIfid\fR's stored offset. + Ioffset R and does not alter Ifid R's stored offset. .SH RETURN VALUE .P diff --git a/man/ixp_respond.3 b/man/ixp_respond.3 @@ -14,11 +14,11 @@ ixp_respond .SH DESCRIPTION .P Sends a response to the given request. The response is -constructed from the \fIofcall\fR member of the \fIreq\fR parameter, or -from the \fIerror\fR parameter if it is non\-null. In the latter +constructed from the Iofcall R member of the Ireq R parameter, or +from the Ierror R parameter if it is non\-null. In the latter case, the response is of type RError, while in any other case it -is of the same type as \fIreq\fR\->\fIofcall\fR, which must match the -request type in \fIreq\fR\->\fIifcall\fR. +is of the same type as Ireq R\-> Iofcall R, which must match the +request type in Ireq R\-> Iifcall R. .SH SEE ALSO .P diff --git a/man/ixp_rubyinit.3 b/man/ixp_rubyinit.3 @@ -0,0 +1,30 @@ +.TH "IXP_RUBYINIT" 3 "2010 Jun" "libixp Manual" + +.SH NAME +.P +ixp_rubyinit + +.SH SYNOPSIS +.nf + #include <ixp.h> + + ixp_rubyinit +.fi + +.SH DESCRIPTION +.P +This function initializes libixp for use in multithreaded +programs embedded in the ruby interpreter. When using a pthread +edition of ruby, ixp_pthread_init should be used instead. When +using libixp in such programs, this function must be called +before any other libixp functions. + +.P +This function is part of libixp_rubythread, which is part of the +libixp distribution, but is not built by default unless enabled +in config.mk. + + +.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) +.\" cmdline: txt2tags -o- ixp_rubyinit.man3 + diff --git a/man/ixp_sendmsg.3 b/man/ixp_sendmsg.3 @@ -19,15 +19,15 @@ These functions read and write messages to and from the given file descriptors. .P -ixp_sendmsg writes the data at \fImsg\fR\->pos upto \fImsg\fR\->end. +ixp_sendmsg writes the data at Imsg R\->pos upto Imsg R\->end. If the call returns non\-zero, all data is assured to have been written. .P ixp_recvmsg first reads a 32 bit, little\-endian length from -\fIfd\fR and then reads a message of that length (including the -4 byte size specifier) into the buffer at \fImsg\fR\->data, so -long as the size is less than \fImsg\fR\->size. + Ifd R and then reads a message of that length (including the +4 byte size specifier) into the buffer at Imsg R\->data, so +long as the size is less than Imsg R\->size. .SH RETURN VALUE .P diff --git a/man/ixp_serverloop.3 b/man/ixp_serverloop.3 @@ -26,7 +26,7 @@ ixp_serverloop, IxpServer .SH DESCRIPTION .P Enters the main loop of the server. Exits when -\fIsrv\fR\->running becomes false, or when select(2) returns an + Isrv R\->running becomes false, or when select(2) returns an error other than EINTR. .SH RETURN VALUE @@ -37,7 +37,7 @@ it exits on error. \fBerrno(3)\fR or the return value of .SH SEE ALSO .P -ixp_listen(3) +ixp_listen(3), ixp_settimer(3) .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) diff --git a/man/ixp_settimer.3 b/man/ixp_settimer.3 @@ -17,18 +17,18 @@ msec The timeout in milliseconds. .TP fn -The function to call after \fImsec\fR milliseconds +The function to call after Imsec R milliseconds have elapsed. .TP aux -An arbitrary argument to pass to \fIfn\fR when it +An arbitrary argument to pass to Ifn R when it is called. .SH DESCRIPTION .P Initializes a callback\-based timer to be triggerred after -\fImsec\fR milliseconds. The timer is passed its id number -and the value of \fIaux\fR. + Imsec R milliseconds. The timer is passed its id number +and the value of Iaux R. .SH RETURN VALUE .P diff --git a/man/ixp_srv_clonefiles.3 b/man/ixp_srv_clonefiles.3 @@ -14,7 +14,7 @@ ixp_srv_clonefiles .SH DESCRIPTION .P Increase the reference count of every IxpFileId linked -to \fIfileid\fR. +to Ifileid R. .SH SEE ALSO .P diff --git a/man/ixp_srv_data2cstring.3 b/man/ixp_srv_data2cstring.3 @@ -13,7 +13,7 @@ ixp_srv_data2cstring .SH DESCRIPTION .P -Ensure that the data member of \fIreq\fR is null terminated, +Ensure that the data member of Ireq R is null terminated, removing any new line from its end. .SH SEE ALSO diff --git a/man/ixp_srv_readbuf.3 b/man/ixp_srv_readbuf.3 @@ -16,16 +16,16 @@ ixp_srv_readbuf, ixp_srv_writebuf .SH DESCRIPTION .P Utility functions for handling TRead and TWrite requests for -files backed by in\-memory buffers. For both functions, \fIbuf\fR -points to a buffer and \fIlen\fR specifies the length of the +files backed by in\-memory buffers. For both functions, Ibuf R +points to a buffer and Ilen R specifies the length of the buffer. In the case of ixp_srv_writebuf, these values add a level of pointer indirection, and updates the values if they change. .P -If \fImax\fR has a value other than 0, ixp_srv_writebuf will +If Imax R has a value other than 0, ixp_srv_writebuf will truncate any writes to that point in the buffer. Otherwise, -\fI*buf\fR is assumed to be malloc(3) allocated, and is + I*buf R is assumed to be malloc(3) allocated, and is reallocated to fit the new data as necessary. The buffer is is always left nul\-terminated. diff --git a/man/ixp_srv_walkandclone.3 b/man/ixp_srv_walkandclone.3 @@ -25,7 +25,7 @@ to simplify the process of walking, cloning, and returning directory listings. Given the \fBIxpFileId(3)\fR of a directory and a filename name should return a new IxpFileId (allocated via \fBixp_srv_getfile(3)\fR) for the matching directory entry, or null -if there is no match. If the passed name is null, \fIlookup\fR +if there is no match. If the passed name is null, Ilookup R should return a linked list of IxpFileIds, one for each child directory entry. @@ -39,7 +39,7 @@ request. ixp_srv_readdir should be called to handle read requests on directories. It prepares a stat for each child of the directory, taking into account the requested offset, and -calls \fBixp_respond(3)\fR. The \fIdostat\fR parameter must be a +calls \fBixp_respond(3)\fR. The Idostat R parameter must be a function which fills the passed \fBIxpStat(3)\fR pointer based on the contents of the passed IxpFileId. diff --git a/man/ixp_srv_writectl.3 b/man/ixp_srv_writectl.3 @@ -15,12 +15,12 @@ ixp_srv_writectl .P This utility function is meant to simplify the writing of pseudo files to which single\-lined commands are written. -In order to use this function, the \fIaux\fR member of -\fIreq\fR\->fid must be nul or an \fBIxpFileId(3)\fR. Each line of the +In order to use this function, the Iaux R member of + Ireq R\->fid must be nul or an \fBIxpFileId(3)\fR. Each line of the written data is stripped of its trailing newline, nul\-terminated, and stored in an \fBIxpMsg(3)\fR. For each line -thus prepared, \fIfn\fR is called with the IxpMsg pointer and -the the \fIp\fR member of the IxpFileId. +thus prepared, Ifn R is called with the IxpMsg pointer and +the the Ip R member of the IxpFileId. .\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) diff --git a/man/ixp_srvutils.3 b/man/ixp_srvutils.3 @@ -0,0 +1,25 @@ +.TH "IXP_API" 3 "2010 Jun" "libixp Manual" + +.SH SYNPOSIS +.nf + #include <ixp_srvutil.h> +.fi + +.SH DESCRIPTION +.P +Since a large part of libixp's purpose revolves around creating +virtual filesystems, a small library of utility functions are +provided towards furthering that end. They are mainly intended +for applications providing simple, largely static virtual +filesystems containing control files and event feeds, though +they are easily adaptable to other ends. + +.SH SEE ALSO +.P +\fBixp_srv_clonefiles(3)\fR, \fBixp_srv_data2cstring(3)\fR, +\fBixp_srv_readbuf(3)\fR, \fBixp_srv_walkandclone(3)\fR, \fBixp_srv_writectl(3)\fR + + +.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) +.\" cmdline: txt2tags -o- ixp_srvutils.man3 + diff --git a/man/ixp_srvutils.man3 b/man/ixp_srvutils.man3 @@ -0,0 +1,23 @@ +IXP_API +libixp Manual +2010 Jun + +%!includeconf: header.t2t + += SYNPOSIS = +``` +#include <ixp_srvutil.h> +``` += DESCRIPTION = + +Since a large part of libixp's purpose revolves around creating +virtual filesystems, a small library of utility functions are +provided towards furthering that end. They are mainly intended +for applications providing simple, largely static virtual +filesystems containing control files and event feeds, though +they are easily adaptable to other ends. + += SEE ALSO = +F<ixp_srv_clonefiles>, F<ixp_srv_data2cstring>, +F<ixp_srv_readbuf>, F<ixp_srv_walkandclone>, F<ixp_srv_writectl> + diff --git a/man/ixp_stat.3 b/man/ixp_stat.3 @@ -77,7 +77,7 @@ An open file descriptor to stat. .SH DESCRIPTION .P -Stats the file at \fIpath\fR or pointed to by \fIfid\fR. +Stats the file at Ipath R or pointed to by Ifid R. .SH RETURN VALUE .P diff --git a/man/ixp_taskinit.3 b/man/ixp_taskinit.3 @@ -0,0 +1,29 @@ +.TH "IXP_TASKINIT" 3 "2010 Jun" "libixp Manual" + +.SH NAME +.P +ixp_taskinit + +.SH SYNOPSIS +.nf + #include <ixp.h> + + ixp_taskinit +.fi + +.SH DESCRIPTION +.P +This function initializes libixp for use in multithreaded +programs using the libtask threading system. When using libixp in +such programs, this function must be called before any other +libixp functions. + +.P +This function is part of libixp_task, which is part of the libixp +distribution, but is not built by default unless enabled in +config.mk. + + +.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) +.\" cmdline: txt2tags -o- ixp_taskinit.man3 + diff --git a/man/ixp_unmount.3 b/man/ixp_unmount.3 @@ -13,7 +13,7 @@ ixp_unmount .SH DESCRIPTION .P -Unmounts the client \fIclient\fR and frees its data structures. +Unmounts the client Iclient R and frees its data structures. .SH SEE ALSO .P diff --git a/man/ixp_unsettimer.3 b/man/ixp_unsettimer.3 @@ -18,7 +18,7 @@ The id number of the timer to void. .SH DESCRIPTION .P -Voids the timer identified by \fIid\fR. +Voids the timer identified by Iid R. .SH RETURN VALUE .P diff --git a/man/ixp_write.3 b/man/ixp_write.3 @@ -26,16 +26,16 @@ The offset at which to write the data. .SH DESCRIPTION .P -ixp_write and ixp_pwrite each write \fIcount\fR bytes of -data stored in \fIbuf\fR to the file pointed to by C<fid>. +ixp_write and ixp_pwrite each write Icount R bytes of +data stored in Ibuf R to the file pointed to by C<fid>. ixp_write writes its data at its stored offset, and -increments it by \fIcount\fR. ixp_pwrite writes its data a -\fIoffset\fR and does not alter C<fid>'s stored offset. +increments it by Icount R. ixp_pwrite writes its data a + Ioffset R and does not alter C<fid>'s stored offset. .SH RETURN VALUE .P These functions return the number of bytes actually -written. Any value less than \fIcount\fR must be considered +written. Any value less than Icount R must be considered a failure. .SH SEE ALSO diff --git a/man/libixp.3 b/man/libixp.3 @@ -0,0 +1,28 @@ +.TH "IXP_API" 3 "2010 Jun" "libixp Manual" + +.SH SYNPOSIS +.nf + #include <ixp.h> +.fi + +.SH DESCRIPTION +.P +libixp is a client and server library for interacting with the +9P filesystem protocol. It includes a straightforward 9P +filesystem client, a callback\-based server library, portable +utilities for opening and multiplexing sockets, a library of +data marshalling functions, and utilities to ease the +construction of simple virtual filesystem servers. Further, +libixp is completely threadsafe and can be adapted to virtual +any threading system. + +.SH SEE ALSO +.P +\fBIXP_API(3)\fR, \fBIxpThread(3)\fR, \fBIxpMsg(3)\fR, \fBixp_mount(3)\fR, \fBixp_dial(3)\fR, +\fBixp_serverloop(3)\fR, \fBixp_listen(3)\fR, \fBixp_settimer(3)\fR, +\fBixp_serve9conn(3)\fR, ixp_srvutils(3) + + +.\" man code generated by txt2tags 2.5 (http://txt2tags.sf.net) +.\" cmdline: txt2tags -o- libixp.man3 + diff --git a/man/libixp.man3 b/man/libixp.man3 @@ -0,0 +1,25 @@ +IXP_API +libixp Manual +2010 Jun + +%!includeconf: header.t2t + += SYNPOSIS = +``` +#include <ixp.h> +``` += DESCRIPTION = + +libixp is a client and server library for interacting with the +9P filesystem protocol. It includes a straightforward 9P +filesystem client, a callback-based server library, portable +utilities for opening and multiplexing sockets, a library of +data marshalling functions, and utilities to ease the +construction of simple virtual filesystem servers. Further, +libixp is completely threadsafe and can be adapted to virtual +any threading system. + += SEE ALSO = +M<IXP_API>, S<IxpThread>, S<IxpMsg>, F<ixp_mount>, F<ixp_dial>, +F<ixp_serverloop>, F<ixp_listen>, F<ixp_settimer>, +F<ixp_serve9conn>, ixp_srvutils(3) diff --git a/man/targets.mk b/man/targets.mk @@ -43,4 +43,7 @@ MANPAGES = \ 'ixp_smprint.3' \ 'ixp_namespace.3' \ 'ixp_eprint.3' \ - 'ixp_emalloc.3 ixp_emallocz.3 ixp_erealloc.3 ixp_estrdup.3' + 'ixp_emalloc.3 ixp_emallocz.3 ixp_erealloc.3 ixp_estrdup.3' \ + 'ixp_pthread_init.3' \ + 'ixp_rubyinit.3' \ + 'ixp_taskinit.3' diff --git a/util/grepdoc b/util/grepdoc @@ -131,8 +131,6 @@ libixp Manual @{[strftime "%Y %b", localtime]} \%!includeconf: header.t2t -\%# There's apparently no other way to do this. -\%!postproc(man): "^(\.TH.*?) 1 " "\\1 3 " EOF @@ -146,7 +144,7 @@ EOF section 'DESCRIPTION', $_; section 'RETURN VALUE', $section{Returns} if exists $section{Returns}; section 'BUGS', $section{Bugs} if exists $section{Bugs}; - section 'SEE ALSO', subst {"$1(3)"} qr/\b[FSTV]<(.*?)>/, $section{'See also'} + section 'SEE ALSO', subst {"$1(3)"} qr/\b[FMSTV]<(.*?)>/, $section{'See also'} if exists $section{'See also'}; open STDOUT, ">&", $stdout }