Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.29' '-r1.30' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2002/10/25 18:10:43	1.29
+++ sa.pod	2002/10/25 20:45:43	1.30
@@ -82,11 +82,11 @@
 sa_accept,  
 sa_getremote,
 sa_getlocal,
-sa_getfd,
 sa_shutdown.
 
 =item B<Socket Input/Output Operations (Stream Communication)>:
 
+sa_getfd,
 sa_read,
 sa_readln,
 sa_write,
@@ -546,8 +546,8 @@
 
 =head2 Socket Connection Operations
 
-This API part provides operations for stream-oriented data communication
-through the socket abstraction C<sa_t>.
+This API part provides connection operations for stream-oriented data
+communication through the socket abstraction C<sa_t>.
 
 =over 4
 
@@ -613,20 +613,65 @@
 
 =item C<sa_rc_t >B<sa_getremote>C<(sa_t *>I<sa>C<, sa_addr_t **>I<raddr>C<);>
 
-FIXME
+Get address abstraction of remote side of communication.
+
+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).
+
+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 sa_rc_t B<sa_getfd>(sa_t *I<sa>, int *I<fd>);
+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).
+
+Example: C<sa_addr_t *laddr; sa_getlocal(sa, &laddr);>
 
 =item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
 
+Shut down part of the full-duplex connection.
+
+This performs a shut down of the connection descriped 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
+read and write channels of the communication are shut down). Internally
+this directly maps to shutdown(2).
+
+Example: C<sa_shutdown(sa, "w");>
+
 =back
 
 =head2 Socket Input/Output Operations (Stream Communication)
 
+This API part provides I/O operations for stream-oriented data
+communication through the socket abstraction C<sa_t>.
+
 =over 4
 
+=item sa_rc_t B<sa_getfd>(sa_t *I<sa>, int *I<fd>);
+
+Get underlying socket filedescriptor.
+
+This peeks into the underlying socket filedescriptor B<OSSP sa>
+allocated internally for the communication. This can be used for
+adjusting the socket communication (via fcntl(2), setsockopt(2), etc)
+directly.
+
+Think twice before using this, then think once more. After all that,
+think again. With enough thought, the need for directly manipulating the
+underlying socket can often be eliminated. At least remember that all
+your direct socket operations fully by-pass B<OSSP sa> and this way can
+leads to nasty side-effects.
+
+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 sa_rc_t B<sa_readln>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
@@ -639,7 +684,10 @@
 
 =back
 
-=head2 Socket Input/Output Operations (Stream Communication)
+=head2 Socket Input/Output Operations (Datagram Communication)
+
+This API part provides operations for datagram-oriented data
+communication through the socket abstraction C<sa_t>.
 
 =over 4