Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.12' '-r1.13' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2001/10/10 09:21:27	1.12
+++ sa.pod	2001/10/10 19:32:57	1.13
@@ -101,55 +101,76 @@
 
 =head1 DESCRIPTION
 
-B<OSSP sa> is an abstraction library for the Unix socket interface
-featuring stream and datagram oriented communication over Unix Domain
-and Internet Domain sockets.
+B<OSSP sa> is an abstraction library for the Unix I<Socket> networking
+interface featuring stream and datagram oriented communication over
+I<Unix Domain> and I<Internet Domain> (TCP and UDP) sockets.
 
 It provides the following key features:
 
 =over 4
 
+=item B<Stand-Alone, Self-Contained, Embeddable>
+
+Although there are various Open Source libraries available which provide
+a similar abstraction approach, they all either lack important features
+or unfortunately depend on other companion libraries. B<OSSP sa> fills
+this gap by providing all important features (see following points) as a
+stand-alone and fully self-contained library. This way B<OSSP sa> can be
+trivially embedded as a sub-library into other libraries. It especially
+provides additional support for namespace-safe embedding of its API in
+order to avoid symbol conflicts (see C<SA_PREFIX> in F<sa.h>).
+
 =item B<Address Abstraction>
 
-Most of the uglyness in the Unix socket API is the necessarity to have
-to deal with the various address structures (C<struct sockaddr_xx>)
+Most of the uglyness in the Unix I<Socket> API is the necessarity to
+have to deal with the various address structures (C<struct sockaddr_xx>)
 which exist because of both the different communication types and
 addressing schemes. B<OSSP sa> fully hides this by providing an abstract
-and opaque address type (C<sa_addr_t>) together with four utility
-functions which allow one to convert from the traditional C<struct
-sockaddr> or URI specification to the C<sa_addr_t> and vice versa.
+and opaque address type (C<sa_addr_t>) together with utility functions
+which allow one to convert from the traditional C<struct sockaddr> or
+URI specification to the C<sa_addr_t> and vice versa without having to
+deal with special cases related to the underlying particular C<struct
+sockaddr_xx>. B<OSSP sa> support I<Unix Domain> and both IPv4 and IPv6
+I<Internet Domain> addressing.
 
 =item B<Type Abstraction>
 
-Some other subtle details in the socket API make the life hard in
-practice: C<socklen_t> and C<ssize_t>. These two types originally were
-(and on some platforms still are) plain integers or unsigned integers
-while POSIX later introduced own types for them. This is nasty, because
-for full backward compatibility and type-correct API usage, every
+Some other subtle details in the Unix I<Socket> API make the life hard
+in practice: C<socklen_t> and C<ssize_t>. These two types originally
+were (and on some platforms still are) plain integers or unsigned
+integers while POSIX later introduced own types for them (and even
+revised these types after some time again). This is nasty, because
+for 100% type-correct API usage (especially important on 64-bit
+machines where pointers to different integer types make trouble), every
 application has to check whether the newer types exists and if not
 provide own definitions which map to the still actually used integer
-type on the underlying platform. B<OSSP sa> hides all this in its API.
+type on the underlying platform. B<OSSP sa> hides most of this in its
+API and for C<socklen_t> provides a backward-compatibility definition.
+Instead of C<ssize_t> it uses C<size_t> because B<OSSP sa> does not use
+traditional Unix return code semantics.
 
 =item B<I/O Timeouts>
 
-Each I/O function in B<OSSP sa> is aware of a central timeout (set
-by sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_SYS>
-and C<errno> set to C<ETIMEDOUT> if this timeout expired before the
-operation was able to succeed. This allows one to easily program
-less-blocking network services.
+Each I/O function in B<OSSP sa> is aware of timeouts (set by
+sa_timeout()), i.e., all I/O operations return C<SA_ERR_TMT> if the
+timeout expired before the I/O operation was able to succeed. This
+allows one to easily program less-blocking network services. B<OSSP
+sa> internally implements these timeouts either through the
+C<SO_{SND,RCV}TIMEO> feature on more modern I<Socket> implementations
+or through traditional select(2). This way high performance is achieved
+on modern platforms while the full functionality still is available on
+older platforms.
 
 =item B<I/O Stream Buffering>
 
 If B<OSSP sa> is used for stream communication, internally all I/O
 operations can be performed through input and/or output buffers (set
-by sa_buffers(3)) for achieving higher I/O performance by doing I/O
-operations on larger aggregated messages.
-
-=item B<Convinience I/O Functions>
-
-If B<OSSP sa> is used for stream communication, for convinience reasons
-line-oriented reading (sa_readln(3)) and formated writing (sa_writef(3))
-is provided, modelled after STDIO's fgets(3) and fprintf(3).
+by sa_buffer()) for achieving higher I/O performance by doing I/O
+operations on larger aggregated messages and with less system calls.
+Additionally if B<OSSP sa> is used for stream communication, for
+convinience reasons line-oriented reading (sa_readln()) and formatted
+writing (sa_writef()) is provided, modelled after STDIO's fgets(3) and
+fprintf(3). Both features fully leverage from the I/O buffering.
 
 =back
 
@@ -188,8 +209,12 @@
 
 =item sa_rc_t B<sa_addr_create>(sa_addr_t **I<saa>);
 
+Create a socket address abstraction object.
+
 =item sa_rc_t B<sa_addr_destroy>(sa_addr_t *I<saa>);
 
+Destroy a socket address abstraction object.
+
 =back
 
 =head2 Address Operations
@@ -198,14 +223,36 @@
 
 =item sa_rc_t B<sa_addr_u2a>(sa_addr_t *I<saa>, const char *I<uri>, ...);
 
+Import an address by converting from an URI specification
+to the corresponding address abstraction. The supported URI
+syntax is: "C<unix:>I<path>" for I<Unix Domain> addresses and
+"C<inet://>I<addr>C<:>I<port>" for I<Internet Domain> addresses.
+I<path> can be an absolute or relative file path to an existing or
+not-existing file. I<addr> can be an IPv4 address in dotted decimal
+notation (C<127.0.0.1>), an IPv6 address in colon-seperated (optionally
+shortended) hexadecimal notation (C<::1>) or a to-be-resolved hostname
+(C<localhost.example.com>). I<port> has to be a decimal port in the
+range C<1>...C<65535>.
+
 =item sa_rc_t B<sa_addr_s2a>(sa_addr_t *I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
 
+Import an address by converting from a tranditional C<struct sockaddr> object to the
+corresponding address abstraction.
+
 =item sa_rc_t B<sa_addr_a2u>(sa_addr_t *I<saa>, char **I<uri>);
 
+Export an address by converting from the
+address abstraction to the corresponding URI specification.
+
 =item sa_rc_t B<sa_addr_a2s>(sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
 
+Export an address by converting from the
+address abstraction to the corresponding traditional C<struct sockaddr> object.
+
 =item sa_rc_t B<sa_addr_match>(sa_addr_t *I<saa1>, sa_addr_t *I<saa2>, size_t I<prefixlen>);
 
+Match two address abstractions 
+
 =back
             
 =head2 Socket Object Operations