--- 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
|
