Index: ossp-pkg/xds/xds.pod
RCS File: /v/ossp/cvs/ossp-pkg/xds/xds.pod,v
rcsdiff -q -kk '-r1.1' '-r1.2' -u '/v/ossp/cvs/ossp-pkg/xds/xds.pod,v' 2>/dev/null
--- xds.pod	2001/07/03 08:25:24	1.1
+++ xds.pod	2001/07/03 11:36:22	1.2
@@ -41,6 +41,9 @@
 function every time it is called; it is not touched in any way by the
 xds library.
 
+A valid name I<name> for a callback function consists of an arbitrary
+number of characters from the class [a-zA-Z0-9_-].
+
 =item int B<xds_unregister>(xds_t* I<xds>, const char* I<name>);
 
 Remove encoding/decoding engine I<name> from context I<xds>. The
@@ -56,10 +59,10 @@
 B<free> the buffer nor will it try to B<realloc> it if it's too small.
 A buffer given to xds as a "gift" is henceforth owned by xds and may
 be B<free>d or B<realloc>ed as the library sees fit. If I<flag> is
-B<XDS_GIFT>, I<buffer> must be a pointer obtained from calling
-B<malloc> or a comparable system routine. Calling B<xds_setbuffer>
-with a I<buffer> of B<NULL> will cause the xds library to allocate a
-buffer of its own. I<buffer_size> is ignored in this case.
+B<XDS_GIFT>, I<buffer> must be a pointer obtained from calling the
+B<malloc(3)> API. Calling B<xds_setbuffer> with a I<buffer> of B<NULL>
+will cause the xds library to allocate a buffer of its own.
+I<buffer_size> is ignored in this case.
 
 Decoding mode: I<buffer> contains the encoded representation of the
 data to be used for following B<xds_decode> calls. The encoded data is
@@ -68,6 +71,11 @@
 is set to B<XDS_GIFT>, the library will B<free> I<buffer> when
 the context is destroyed.
 
+B<xds_setbuffer> returns one of the following codes signifying success
+or failure: B<XDS_OK> (everything alright), B<XDS_ERR_NO_MEM> (failed
+to allocate new internal buffers), and B<XDS_ERR_INVALID_ARG>
+(arguments don't make sense).
+
 =item int B<xds_getbuffer>(xds_t* I<xds>, xds_scope_t flag, void** buffer, size_t* buffer_size);
 
 This routine will write the address and size of the internal buffer in
@@ -84,15 +92,41 @@
 by the application programmer from now on, it is no longer modified or
 used in any way by the library.
 
-
 =item int B<xds_encode>(xds_t* I<xds>, const char* I<fmt>, ...);
 
+The B<encode> function call will encode an arbitrary number of values
+into the chosen representation. The syntax is very similar to
+B<sprintf>: As parameters, it requires the I<xds> handle obtained from
+B<xds_init>, a format string I<fmt> describing the following value
+parameters, and an arbitrary number of actual values.
+
+The format string lists the names of the callback functions to be used
+in order to format the values; it has the format "name name ...". The
+names are delimited by any number of characters any of which is not
+part of the character set allowed for function names here. Hence, you
+can delimit the names by blanks, tabs, dollar signs or pretty much
+anyting your want.
+
+B<xds_encode> will return either B<XDS_OK> (everything OK),
+B<XDS_ERR_NO_MEM> (failed allocating memory for intenal buffering),
+B<XDS_ERR_OVERFLOW> (can't expand internal buffer because it's owned
+by the application), B<XDS_ERR_INVALID_ARG> (parameters don't make
+sense), B<XDS_ERR_TYPE_MISMATCH> (specified callback can't handle this
+data type), and B<XDS_ERR_UNKNOW_ENGINE> (unknown call back name used
+in I<fmt>).
+
 =item int B<xds_decode>(xds_t* I<xds>, const char* I<fmt>, ...);
 
+Like B<xds_encode>, only the other way round.
+
 =item int B<xds_vencode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);
 
+See B<xds_encode>.
+
 =item int B<xds_vdecode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);
 
+See B<xds_decode>.
+
 =back
 
 =cut