--- sa.pod 2001/10/05 20:52:15 1.6
+++ sa.pod 2001/10/05 21:11:22 1.7
@@ -39,9 +39,9 @@
=item B<Abstract Data Types>:
+sa_rc_t,
sa_addr_t,
-sa_t,
-sa_rc_t.
+sa_t.
=item B<Address Object Operations>:
@@ -93,22 +93,23 @@
=head1 DESCRIPTION
-B<OSSP sa> is a thin abstraction library for the BSD socket interface
-for use in conjunction with TCP and UDP protocols. It provides the
-following key features:
+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.
+
+It provides the following key features:
=over 4
=item B<Address Abstraction>
-Most of the uglyness in the BSD 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 network protocols 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 old C<struct sockaddr> and an URL
-specification (C<{tcp,udp}://<host>[:<port>]>) to the C<sa_addr_t> and
-vice versa.
+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>)
+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.
=item B<Type Abstraction>
@@ -123,36 +124,51 @@
=item B<I/O Timeouts>
-Each function of 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
+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.
=item B<Buffered I/O>
-If B<OSSP sa> is used for TCP-based stream I/O, internally all I/O
-operations can be performed through input and output buffers (set
+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 messages.
+operations on larger aggregated messages.
=item B<Convinience I/O Functions>
-If B<OSSP sa> is used for TCP-based stream I/O, for convinience reasons
-line reading (sa_readline(3)) and output formatting (sa_writef(3))
-functions are provided, modelled after STDIO's fgets(3) and fprintf(3).
+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).
=back
=head1 DATA TYPES
+B<OSSP sa> uses three data types in its API:
+
=over 4
-=item B<sa_addr_t>
+=item B<sa_rc_t> (Return Code Type)
+
+This is an exported enumerated integer type with the following possible
+values: C<SA_OK> (everything ok, operation succeeded); C<SA_ERR_ARG>
+(invalid argument(s) passed to function); C<SA_ERR_USE> (function used
+in wrong context); C<SA_ERR_MEM> (out of memory); C<SA_ERR_EOF> (end of
+file/socket in communication); C<SA_ERR_SYS> (operating system error;
+errno contains details); C<SA_ERR_INT> (any other internal error).
+
+=item B<sa_addr_t> (Socket Address Abstraction Type)
+
+This is an opaque type representing a socket address.
+Only pointers to this abstract type are used in the API.
-=item B<sa_t>
+=item B<sa_t> (Socket Abstraction Type)
-=item B<sa_rc_tt>
+This is an opaque type representing a socket.
+Only pointers to this abstract type are used in the API.
=back
|
