Index: ossp-pkg/sa/TODO
RCS File: /v/ossp/cvs/ossp-pkg/sa/TODO,v
rcsdiff -q -kk '-r1.40' '-r1.41' -u '/v/ossp/cvs/ossp-pkg/sa/TODO,v' 2>/dev/null
--- TODO	2002/10/26 18:01:24	1.40
+++ TODO	2002/10/26 18:28:15	1.41
@@ -13,8 +13,6 @@
 
   o more test cases to cover full API and especially the client/server usage
 
-  o more documentation to fully describe API
-
   CANDO
   -----
 
Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.32' '-r1.33' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2002/10/26 17:59:30	1.32
+++ sa.pod	2002/10/26 18:28:16	1.33
@@ -618,26 +618,26 @@
 This determines the address of the communication peer and creates a new
 socket address abstraction object (returned in I<raddr>) describing
 the peer address. The application has to destroy I<raddr> later with
-sa_addr_destroy(3).
+sa_addr_destroy(3). Internally this maps to getpeername(2).
 
 Example: C<sa_addr_t *raddr; sa_getremote(sa, &raddr);>
 
-=item sa_rc_t B<sa_getlocal>(sa_t *I<sa>, sa_addr_t **I<laddr>);
+=item C<sa_rc_t >B<sa_getlocal>C<(sa_t *>I<sa>C<, sa_addr_t **>I<laddr>C<);>
 
 Get address abstraction of local side of communication.
 
 This determines the address of the local communication side and
 creates a new socket address abstraction object (returned in I<laddr>)
 describing the local address. The application has to destroy I<laddr>
-later with sa_addr_destroy(3).
+later with sa_addr_destroy(3). Internally this maps to getsockname(2).
 
 Example: C<sa_addr_t *laddr; sa_getlocal(sa, &laddr);>
 
-=item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
+=item C<sa_rc_t >B<sa_shutdown>C<(sa_t *>I<sa>C<, char *>I<flags>C<);>
 
 Shut down part of the full-duplex connection.
 
-This performs a shut down of the connection descriped in I<sa>. The
+This performs a shut down of the connection described in I<sa>. The
 flags string can be either "C<r>" (indicating the read channel of the
 communication is shut down only), "C<w>" (indicating the write channel
 of the communication is shut down only), or "C<rw>" (indicating both the
@@ -655,7 +655,7 @@
 
 =over 4
 
-=item sa_rc_t B<sa_getfd>(sa_t *I<sa>, int *I<fd>);
+=item C<sa_rc_t >B<sa_getfd>C<(sa_t *>I<sa>C<, int *>I<fd>C<);>
 
 Get underlying socket filedescriptor.
 
@@ -672,37 +672,123 @@
 
 Example: C<int fd; sa_getfd(sa, &fd);>
 
-=item sa_rc_t B<sa_read>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+=item C<sa_rc_t >B<sa_read>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
 
-=item sa_rc_t B<sa_readln>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+Read a chunk of data from socket into own buffer.
 
-=item sa_rc_t B<sa_write>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+This reads from the socket (optionally through the internal read buffer)
+up to a maximum of I<buflen> bytes into buffer I<buf>. The actual number
+of read bytes is stored in I<bufdone>. This internally maps to read(2).
 
-=item sa_rc_t B<sa_writef>(sa_t *I<sa>, const char *I<fmt>, ...);
+Example: C<char buf[1024]; size_t n; sa_read(sa, buf, sizeof(buf), &n);>
 
-=item sa_rc_t B<sa_flush>(sa_t *I<sa>);
+=item C<sa_rc_t >B<sa_readln>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
+
+Read a line of data from socket into own buffer.
+
+This reads from the socket (optionally through the internal read buffer)
+up to a maximum of I<buflen> bytes into buffer I<buf>, but only as long
+as no line terminating newline character (0x0a) was found. The line
+terminating newline character is stored in the buffer, too. The actual
+number of read bytes is stored in I<bufdone>. This internally maps to
+sa_read(3).
+
+Keep in mind that for efficiency reasons, line-oriented I/O usually
+always should be performed with read buffer (see sa_option(3) and
+C<SA_BUFFER_READ>). Without such a read buffer, the performance is
+cruel, because single character read(2) operations would be performed on
+the underlying socket.
+
+Example: C<char buf[1024]; size_t n; sa_readln(sa, buf, sizeof(buf), &n);>
+
+=item C<sa_rc_t >B<sa_write>C<(sa_t *>I<sa>C<, const char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
+
+Write a chunk of data to socket from own buffer.
+
+This writes to the socket (optionally through the internal write buffer)
+I<buflen> bytes from buffer I<buf>. In case of a partial write, the
+actual number of written bytes is stored in I<bufdone>. This internally
+maps to write(2).
+
+Example: C<sa_write(sa, cp, strlen(cp), NULL);>
+
+=item C<sa_rc_t >B<sa_writef>C<(sa_t *>I<sa>C<, const char *>I<fmt>C<, ...);>
+
+Write formatted data data to socket.
+
+This formats a string according to the printf(3)-style format
+specification I<fmt> and sends the result to the socket (optionally
+through the internal write buffer). In case of a partial socket
+write, the not written data of the formatted string is internally
+discarded. Hence using a write buffer is strongly recommended here
+(see sa_option(3) and C<SA_BUFFER_WRITE>). This internally maps to
+sa_write(3).
+
+The underlying string formatting engine is just a minimal one and for
+security and independence reasons intentionally not directly based on
+s[n]printf(3). It understands only the following format specifications:
+"C<%%>", "C<%c>" (C<char>), "C<%s>" (C<char *>) and "C<%d>" (C<int>)
+without any precision and padding possibilities. It is intended for
+minimal formatting only. If you need more sophisticated formatting, you
+have to format first into an own buffer via s[n]printf(3) and then write
+this to the socket via sa_write(3) instead.
+
+Example: C<sa_writef(sa, "%s=%d\n", cp, i);>
+
+=item C<sa_rc_t >B<sa_flush>C<(sa_t *>I<sa>C<);>
+
+Flush still pending outgoing data to socket.
+
+This writes all still pending outgoing data for the internal write
+buffer (see sa_option(3) and C<SA_BUFFER_WRITE>) to the socket. This
+internally maps to write(2).
+
+Example: C<sa_flush(sa);>
 
 =back
 
 =head2 Socket Input/Output Operations (Datagram Communication)
 
-This API part provides operations for datagram-oriented data
+This API part provides I/O operations for datagram-oriented data
 communication through the socket abstraction C<sa_t>.
 
 =over 4
 
 =item sa_rc_t B<sa_recv>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t **I<raddr>);
 
+Receive a chunk of data from remote address via socket into own buffer.
+
+This receives from the remote address specified in I<raddr> via the
+socket up to a maximum of I<buflen> bytes into buffer I<buf>. The actual
+number of received bytes is stored in I<bufdone>. This internally maps
+to recvfrom(2).
+
+Example: C<char buf[1024]; size_t n; sa_recv(sa, buf, sizeof(buf), &n, saa);>
+
 =item sa_rc_t B<sa_send>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t *I<raddr>);
 
+Send a chunk of data to remote address via socket from own buffer.
+
+This sends to the remote address specified in I<raddr> via the socket
+I<buflen> bytes from buffer I<buf>. The actual number of sent bytes is
+stored in I<bufdone>. This internally maps to sendto(2).
+
+Example: C<sa_send(sa, buf, strlen(buf), NULL, saa);>
+
 =back
 
 =head2 Socket Error Handling
 
+This API part provides error handling operations only.
+
 =over 4
 
 =item char *B<sa_error>(sa_rc_t I<rv>);
 
+Return the string representation corresponding to the return code
+value I<rv>. The returned string has to be treated read-only by the
+application and is not required to be deallocated.
+
 =back
 
 =head1 SEE ALSO
@@ -710,43 +796,43 @@
 =head2 Standards
 
 R. Gilligan, S. Thomson, J. Bound, W. Stevens:
-"Basic Socket Interface Extensions for IPv6",
-RFC 2553, March 1999.
+I<"Basic Socket Interface Extensions for IPv6">,
+B<RFC 2553>, March 1999.
 
 W. Stevens:
-"Advanced Sockets API for IPv6",
+I<"Advanced Sockets API for IPv6">,
 B<RFC 2292>, February 1998.
 
 R. Fielding, L. Masinter, T. Berners-Lee:
-"Uniform Resource Identifiers: Generic Syntax",
+I<"Uniform Resource Identifiers: Generic Syntax">,
 B<RFC 2396>, August 1998.
 
 R. Hinden, S. Deering:
-"IP Version 6 Addressing Architecture",
+I<"IP Version 6 Addressing Architecture">,
 B<RFC 2373>, July 1998.
 
 R. Hinden, B. Carpenter, L. Masinter:
-"Format for Literal IPv6 Addresses in URL's",
+I<"Format for Literal IPv6 Addresses in URL's">,
 B<RFC 2732>, December 1999.
 
 =head2 Papers
 
 Stuart Sechrest:
-"An Introductory 4.4BSD Interprocess Communication Tutorial",
+I<"An Introductory 4.4BSD Interprocess Communication Tutorial">,
 FreeBSD 4.4 (/usr/share/doc/psd/20.ipctut/).
 
 Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley:
-"An Advanced 4.4BSD Interprocess Communication Tutorial",
+I<"An Advanced 4.4BSD Interprocess Communication Tutorial">,
 FreeBSD 4.4 (/usr/share/doc/psd/21.ipc/).
 
 Craig Metz:
-"Protocol Independence Using the Sockets API"
+I<"Protocol Independence Using the Sockets API">,
 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html,
 USENIX Annual Technical Conference, June 2000.
 
 =head2 Manual Pages
 
-socket(2)
+socket(2),
 accept(2),
 bind(2),
 connect(2),
@@ -763,7 +849,7 @@
 socketpair(2),
 write(2),
 getprotoent(3),
-protocols(4)
+protocols(4).
 
 =head1 HISTORY
 
@@ -775,7 +861,7 @@
 derived from a predecessor sub-library originally written for socket
 address abstraction inside B<OSSP lmtp2nntp>.
 
-=head1 AUTHORS
+=head1 AUTHOR
 
  Ralf S. Engelschall
  rse@engelschall.com