Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.22' '-r1.23' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2002/01/02 13:44:48	1.22
+++ sa.pod	2002/01/02 14:41:07	1.23
@@ -506,12 +506,64 @@
 
 =item sa_rc_t B<sa_bind>(sa_t *I<sa>, sa_addr_t *I<laddr>);
 
+Bind socket abstraction object to a local protocol address.
+
+This assigns the local protocol address I<laddr>. When a socket is
+created ) it exists in an address family space but has no protocol
+address assigned. This call requests that I<laddr> be used as the local
+address. For servers this is the address they later listen on (see
+sa_listen()) for incoming connections, for clients this is the address
+used for outgoing connections (see sa_connect()). Internally this
+directly maps to bind(2).
+
+Example: C<sa_bind(sa, laddr);>
+
 =item sa_rc_t B<sa_connect>(sa_t *I<sa>, sa_addr_t *I<raddr>);
 
+Initiate an outgoing connection on a socket abstraction object.
+
+This performs a connect to the remote address I<raddr>. If the socket
+is of type C<SA_TYPE_DATAGRAM>, this call specifies the peer with which
+the socket is to be associated; this address is that to which datagrams
+are to be sent, and the only address from which datagrams are to be
+received. If the socket is of type C<SA_TYPE_STREAM>, this call attempts
+to make a connection to the remote socket. Internally this directly maps
+to connect(2).
+
+Example: C<sa_connect(sa, raddr);>
+
 =item sa_rc_t B<sa_listen>(sa_t *I<sa>, int I<backlog>);
 
+Listen for incoming connections on a socket abstraction object.
+
+A willingness to accept incoming connections and a queue limit for
+incoming connections are specified by this call. The I<backlog> argument
+defines the maximum length the queue of pending connections may grow to.
+Internally this directly maps to listen(2).
+
+Example: C<sa_listen(sa, 128);>
+
 =item sa_rc_t B<sa_accept>(sa_t *I<sa>, sa_addr_t **I<caddr>, sa_t **I<csa>);
 
+Accept incoming connection on a socket abstraction object.
+
+This accepts an incoming connection by extracting the first connection
+request on the queue of pending connections. It creates a new socket
+abstraction object (returned in I<csa>) and a new socket address
+abstraction object (returned in I<caddr>) describing the connection. The
+caller has to destroy these objects laters. If no pending connections
+are present on the queue, it blocks the caller until a connection is
+present.
+
+Example: 
+
+ sa_addr_t *clt_saa;
+ sa_t      *clt_sa;
+ ...
+ while (sa_accept(srv_sa, &clt_saa, &clt_sa) == SA_OK) {
+     ...
+ }
+
 =item sa_rc_t B<sa_getremote>(sa_t *I<sa>, sa_addr_t **I<raddr>);
 
 =item sa_rc_t B<sa_getlocal>(sa_t *I<sa>, sa_addr_t **I<laddr>);