Index: ossp-pkg/sa/sa.pod
RCS File: /v/ossp/cvs/ossp-pkg/sa/sa.pod,v
rcsdiff -q -kk '-r1.28' '-r1.29' -u '/v/ossp/cvs/ossp-pkg/sa/sa.pod,v' 2>/dev/null
--- sa.pod	2002/10/25 17:36:08	1.28
+++ sa.pod	2002/10/25 18:10:43	1.29
@@ -158,24 +158,24 @@
 =item B<I/O Timeouts>
 
 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.
+sa_timeout(3)), 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_>{C<SND>,C<RCV>}C<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_buffer()) for achieving higher I/O performance by doing I/O
+by sa_buffer(3)) for achieving higher I/O performance by doing I/O
 operations on larger aggregated messages and with less required system
 calls. Additionally if B<OSSP sa> is used for stream communication, for
-convenience reasons line-oriented reading (sa_readln()) and formatted
-writing (see sa_writef()) is provided, modelled after STDIO's fgets(3)
+convenience reasons line-oriented reading (sa_readln(3)) and formatted
+writing (see sa_writef(3)) is provided, modelled after STDIO's fgets(3)
 and fprintf(3). Both features fully leverage from the I/O buffering.
 
 =back
@@ -217,26 +217,32 @@
 =head1 FUNCTIONS
 
 B<OSSP sa> provides a bunch of API functions, all modelled after the
-same prototype: "C<sa_rc_t> C<sa_>I<name>C<(sa_>[C<addr_>]C<_t *,>
-...C<)>". This means every function returns C<sa_rc_t> to indicate its
-success (C<SA_OK>) or failure (C<SA_ERR_XXX>) by returning a return code
-(the corresponding describing text can be determined by passing this
-return code to C<sa_error>). Each function name starts with the common
-prefix C<sa_> and receives a C<sa_t> (or C<sa_addr_t>) object on which
+same prototype:
+
+C<sa_rc_t> B<sa_>I<name>C<(sa_>[C<addr_>]C<_t *,> ...C<)>
+
+This means, every function returns C<sa_rc_t> to indicate its success
+(C<SA_OK>) or failure (C<SA_ERR_>I<XXX>) by returning a return code (the
+corresponding describing text can be determined by passing this return
+code to sa_error(3)). Each function name starts with the common prefix
+C<sa_> and receives a C<sa_t> (or C<sa_addr_t>) object handle on which
 it operates as its first argument.
 
 =head2 Address Object Operations
 
+This API part provides operations for the creation and destruction of
+address abstraction C<sa_addr_t>.
+
 =over 4
 
-=item sa_rc_t B<sa_addr_create>(sa_addr_t **I<saa>);
+=item C<sa_rc_t >B<sa_addr_create>C<(sa_addr_t **>I<saa>C<);>
 
 Create a socket address abstraction object. 
 The object is stored in I<saa> on success.
 
 Example: C<sa_addr_t *saa; sa_addr_create(&saa);>
 
-=item sa_rc_t B<sa_addr_destroy>(sa_addr_t *I<saa>);
+=item C<sa_rc_t >B<sa_addr_destroy>C<(sa_addr_t *>I<saa>C<);>
 
 Destroy a socket address abstraction object.
 The object I<saa> is invalid after this call succeeded.
@@ -247,9 +253,12 @@
 
 =head2 Address Operations
 
+This API part provides operations for working with the address
+abstraction C<sa_addr_t>.
+
 =over 4
 
-=item sa_rc_t B<sa_addr_u2a>(sa_addr_t *I<saa>, const char *I<uri>, ...);
+=item C<sa_rc_t >B<sa_addr_u2a>C<(sa_addr_t *>I<saa>C<, const char *>I<uri>C<, ...);>
 
 Import an address into by converting from an URI specification to the
 corresponding address abstraction. 
@@ -263,17 +272,16 @@
 in dotted decimal notation ("C<127.0.0.1>"), an IPv6 address in
 colon-separated (optionally abbreviated) hexadecimal notation ("C<::1>")
 or a to-be-resolved hostname ("C<localhost.example.com>"). I<port> has
-to be either a decimal port in the range C<1>...C<65535> or a port
-name ("C<smtp>"). If I<port> is specified as a name, it is resolved as
-a TCP port by default. To force resolving a I<port> name via a
-particular protocol, I<protocol> can be specified as either "C<tcp>" or
-"C<udp>".
+to be either a decimal port in the range C<1>...C<65535> or a port name
+("C<smtp>"). If I<port> is specified as a name, it is resolved as a TCP
+port by default. To force resolving a I<port> name via a particular
+protocol, I<protocol> can be specified as either "C<tcp>" or "C<udp>".
 
 The result is stored in I<saa> on success.
 
 Example: C<sa_addr_u2a(saa, "inet://192.168.0.1:smtp");>
 
-=item sa_rc_t B<sa_addr_s2a>(sa_addr_t *I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
+=item C<sa_rc_t >B<sa_addr_s2a>C<(sa_addr_t *>I<saa>C<, const struct sockaddr *>I<sabuf>C<, socklen_t >I<salen>C<);>
 
 Import an address by converting from a traditional C<struct sockaddr>
 object to the corresponding address abstraction.
@@ -281,13 +289,13 @@
 The accepted addresses for I<sabuf> are: C<struct sockaddr_un>
 (C<AF_LOCAL>), C<struct sockaddr_in> (C<AF_INET>) and C<struct
 sockaddr_in6> (C<AF_INET6>). The I<salen> is the corresponding
-C<sizeof()> of the underlying structure.
+C<sizeof(...)> of the particular underyling structure.
 
 The result is stored in I<saa> on success.
 
 Example: C<sockaddr_in in; sa_addr_s2a(saa, (struct sockaddr *)&in, (socklen_t)sizeof(in));>
 
-=item sa_rc_t B<sa_addr_a2u>(sa_addr_t *I<saa>, char **I<uri>);
+=item C<sa_rc_t >B<sa_addr_a2u>C<(sa_addr_t *>I<saa>C<, char **>I<uri>C<);>
 
 Export an address by converting from the address abstraction to the
 corresponding URI specification. 
@@ -296,7 +304,7 @@
 Domain> addresses and "C<inet://>I<addr>C<:>I<port>" for I<Internet
 Domain> addresses. Notice that I<addr> and I<port> are returned in
 numerical (unresolved) way. Additionally, because usually one cannot map
-bi-directionally between TCP or UDP port names and the numerical value,
+bidirectionally between TCP or UDP port names and the numerical value,
 there is no distinction between TCP and UDP here.
 
 The result is stored in I<uri> on success.
@@ -304,21 +312,21 @@
 
 Example: C<char *uri; sa_addr_a2u(saa, &uri);>
 
-=item sa_rc_t B<sa_addr_a2s>(sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
+=item C<sa_rc_t >B<sa_addr_a2s>C<(sa_addr_t *>I<saa>C<, struct sockaddr **>I<sabuf>C<, socklen_t *>I<salen>C<);>
 
 Export an address by converting from the address abstraction to the
 corresponding traditional C<struct sockaddr> object. 
 
-The result is one of the following underlying address structures: C<struct
-sockaddr_un> (C<AF_LOCAL>), C<struct sockaddr_in> (C<AF_INET>) and C<struct
-sockaddr_in6> (C<AF_INET6>). 
+The result is one of the following particular underlying address
+structures: C<struct sockaddr_un> (C<AF_LOCAL>), C<struct sockaddr_in>
+(C<AF_INET>) and C<struct sockaddr_in6> (C<AF_INET6>).
 
 The result is stored in I<sabuf> and I<salen> on success.
 The caller has to free(3) the I<sabuf> buffer later.
 
 Example: C<struct sockaddr sabuf, socklen_t salen; sa_addr_a2s(saa, &sa, &salen);>
 
-=item sa_rc_t B<sa_addr_match>(sa_addr_t *I<saa1>, sa_addr_t *I<saa2>, size_t I<prefixlen>);
+=item C<sa_rc_t >B<sa_addr_match>C<(sa_addr_t *>I<saa1>C<, sa_addr_t *>I<saa2>C<, size_t >I<prefixlen>C<);>
 
 Match two address abstractions up to a specified prefix.
 
@@ -337,7 +345,7 @@
 
 This especially can be used to implement Access Control Lists (ACL)
 without having to fiddle around with the underlying representation.
-For this make I<saa1> the to be checked address and I<saa2> plus
+For this, make I<saa1> the to be checked address and I<saa2> plus
 I<prefixlen> the ACL pattern as shown in the following example.
 
 Example:
@@ -367,16 +375,19 @@
 
 =head2 Socket Object Operations
 
+This API part provides operations for the creation and destruction of
+socket abstraction C<sa_t>.
+
 =over 4
 
-=item sa_rc_t B<sa_create>(sa_t **I<sa>);
+=item C<sa_rc_t >B<sa_create>C<(sa_t **>I<sa>C<);>
 
 Create a socket abstraction object.
 The object is stored in I<sa> on success.
 
 Example: C<sa_t *sa; sa_create(&sa);>
 
-=item sa_rc_t B<sa_destroy>(sa_t *I<sa>);
+=item C<sa_rc_t >B<sa_destroy>C<(sa_t *>I<sa>C<);>
 
 Destroy a socket abstraction object.
 The object I<sa> is invalid after this call succeeded.
@@ -384,12 +395,15 @@
 Example: C<sa_destroy(sa);>
 
 =back
-            
+
 =head2 Socket Parameter Operations
 
+This API part provides operations for parameterizing the socket
+abstraction C<sa_t>.
+
 =over 4
 
-=item sa_rc_t B<sa_type>(sa_t *I<sa>, sa_type_t I<type>);
+=item C<sa_rc_t >B<sa_type>C<(sa_t *>I<sa>C<, sa_type_t >I<type>C<);>
 
 Assign a particular communication protocol type to the socket
 abstraction object.
@@ -406,39 +420,40 @@
 
 Example: C<sa_type(sa, SA_TYPE_STREAM);>
 
-=item sa_rc_t B<sa_timeout>(sa_t *I<sa>, sa_timeout_t I<id>, long I<sec>, long I<usec>);
+=item C<sa_rc_t >B<sa_timeout>C<(sa_t *>I<sa>C<, sa_timeout_t >I<id>C<, long >I<sec>C<, long >I<usec>C<);>
 
-Assign one or more communication timeouts to the socket abstraction object.
+Assign one or more communication timeouts to the socket abstraction
+object.
 
 Possible values for I<id> are: C<SA_TIMEOUT_ACCEPT> (affecting
-sa_accept()), C<SA_TIMEOUT_CONNECT> (affecting sa_connect()),
-C<SA_TIMEOUT_READ> (affecting sa_read(), sa_readln() and sa_recv())
-and C<SA_TIMEOUT_WRITE> (affecting sa_write(), sa_writef() and
-sa_send()). Additionally you can set all four timeouts at once by using
+sa_accept(3)), C<SA_TIMEOUT_CONNECT> (affecting sa_connect(3)),
+C<SA_TIMEOUT_READ> (affecting sa_read(3), sa_readln(3) and sa_recv(3))
+and C<SA_TIMEOUT_WRITE> (affecting sa_write(3), sa_writef(3) and
+sa_send(3)). Additionally you can set all four timeouts at once by using
 C<SA_TIMEOUT_ALL>. The default is that no communication timeouts are
 used which is equal to I<sec>=C<0>/I<usec>=C<0>.
 
 Example: C<sa_timeout(sa, SA_TIMEOUT_ALL, 30, 0);>
 
-=item sa_rc_t B<sa_buffer>(sa_t *I<sa>, sa_buffer_t I<id>, size_t I<size>);
+=item C<sa_rc_t >B<sa_buffer>C<(sa_t *>I<sa>C<, sa_buffer_t >I<id>C<, size_t >I<size>C<);>
 
 Assign I/O communication buffers to the socket abstraction object.
 
-Possible values for I<id> are: C<SA_BUFFER_READ> (affecting sa_read()
-and sa_readln()) and C<SA_BUFFER_WRITE> (affecting sa_write() and
-sa_writef()). The default is that no communication buffers are
-used which is equal to I<size>=C<0>.
+Possible values for I<id> are: C<SA_BUFFER_READ> (affecting sa_read(3)
+and sa_readln(3)) and C<SA_BUFFER_WRITE> (affecting sa_write(3) and
+sa_writef(3)). The default is that no communication buffers are used
+which is equal to I<size>=C<0>.
 
 Example: C<sa_buffer(sa, SA_BUFFER_READ, 16384);>
 
-=item sa_rc_t B<sa_option>(sa_t *I<sa>, sa_option_t I<id>, ...);
+=item C<sa_rc_t >B<sa_option>C<(sa_t *>I<sa>C<, sa_option_t >I<id>C<, ...);>
 
 Adjust various options of the socket abstraction object.
 
-The adjusted option is controlled by I<id>. The number and type of
-the expected following argument(s) are dependent on the particular
-option. Currently the following options are implemented (option arguments
-in parenthesis): 
+The adjusted option is controlled by I<id>. The number and type of the
+expected following argument(s) are dependent on the particular option.
+Currently the following options are implemented (option arguments in
+parenthesis):
 
 C<SA_OPTION_NAGLE> (C<int> I<yesno>) for enabling (I<yesno>=C<1>) or
 disabling (I<yesno> == C<0>) Nagle's Algorithm (see RFC898).
@@ -451,11 +466,11 @@
 
 C<SA_OPTION_REUSEADDR> (C<int> I<yesno>) for enabling (I<yesno> ==
 C<1>) or disabling (I<yesno> == C<0>) the reusability of the address on
-binding (see C<SO_REUSEADDR> of setsockopt(2)).
+binding via sa_bind(3) (see C<SO_REUSEADDR> of setsockopt(2)).
 
 C<SA_OPTION_REUSEPORT> (C<int> I<yesno>) for enabling (I<yesno> == C<1>)
 or disabling (I<yesno> == C<0>) the reusability of the port on binding
-(see C<SO_REUSEPORT> of setsockopt(2)).
+via sa_bind(3) (see C<SO_REUSEPORT> of setsockopt(2)).
 
 C<SA_OPTION_NONBLOCK> (C<int> I<yesno>) for enabling (I<yesno> == C<1>)
 or disabling (I<yesno> == C<0>) non-blocking I/O mode (see C<O_NONBLOCK>
@@ -463,9 +478,10 @@
 
 Example: C<sa_option(sa, SA_OPTION_NONBLOCK, 1);>
 
-=item sa_rc_t B<sa_syscall>(sa_t *I<sa>, sa_syscall_t I<id>, void (*I<fptr>)(), void *I<fctx>);
+=item C<sa_rc_t >B<sa_syscall>C<(sa_t *>I<sa>C<, sa_syscall_t >I<id>C<, void (*>I<fptr>C<)(), void *>I<fctx>C<);>
 
-Divert I/O communication related system calls to user supplied callback functions.
+Divert I/O communication related system calls to user supplied callback
+functions.
 
 This allows you to override mostly all I/O related system calls B<OSSP
 sa> internally performs while communicating. This can be used to adapt
@@ -484,25 +500,33 @@
 Possible values for I<id> are (expected prototypes behind I<fptr> are
 given in parenthesis): 
 
-C<SA_SYSCALL_CONNECT>: "C<int (*)([void *,] int, const struct sockaddr *, socklen_t)>", see connect(2).
+C<SA_SYSCALL_CONNECT>: "C<int (*)([void *,] int, const struct sockaddr
+*, socklen_t)>", see connect(2).
 
-C<SA_SYSCALL_ACCEPT>: "C<int (*)([void *,] int, struct sockaddr *, socklen_t *)>", see accept(2).
+C<SA_SYSCALL_ACCEPT>: "C<int (*)([void *,] int, struct sockaddr *,
+socklen_t *)>", see accept(2).
 
-C<SA_SYSCALL_SELECT>: "C<int (*)([void *,] int, fd_set *, fd_set *, fd_set *, struct timeval *)>", see select(2).
+C<SA_SYSCALL_SELECT>: "C<int (*)([void *,] int, fd_set *, fd_set *,
+fd_set *, struct timeval *)>", see select(2).
 
-C<SA_SYSCALL_READ>: "C<ssize_t (*)([void *,] int, void *, size_t)>", see read(2). 
+C<SA_SYSCALL_READ>: "C<ssize_t (*)([void *,] int, void *, size_t)>", see
+read(2).
 
-C<SA_SYSCALL_WRITE>: "C<ssize_t (*)([void *,] int, const void *, size_t)>", see write(2). 
+C<SA_SYSCALL_WRITE>: "C<ssize_t (*)([void *,] int, const void *,
+size_t)>", see write(2).
 
-C<SA_SYSCALL_RECVFROM>: "C<ssize_t (*)([void *,] int, void *, size_t, int, struct sockaddr *, socklen_t *)>", see recvfrom(2). 
+C<SA_SYSCALL_RECVFROM>: "C<ssize_t (*)([void *,] int, void *, size_t,
+int, struct sockaddr *, socklen_t *)>", see recvfrom(2).
 
-C<SA_SYSCALL_SENDTO>: "C<ssize_t (*)([void *,] int, const void *, size_t, int, const struct sockaddr *, socklen_t)>", see sendto(2).
+C<SA_SYSCALL_SENDTO>: "C<ssize_t (*)([void *,] int, const void *,
+size_t, int, const struct sockaddr *, socklen_t)>", see sendto(2).
 
 Example: 
 
  FILE *trace_fp = ...;
 
- ssize_t trace_read(void *ctx, int fd, void *buf, size_t len)
+ ssize_t 
+ trace_read(void *ctx, int fd, void *buf, size_t len)
  {
      FILE *fp = (FILE *)ctx; 
      ssize_t rv;
@@ -510,7 +534,8 @@
 
      rv = read(fd, buf, len);
      errno_saved = errno;
-     fprintf(fp, "read(%d, %lx, %d) = %d\n", fd, (long)buf, len, rv);
+     fprintf(fp, "read(%d, %lx, %d) = %d\n", 
+             fd, (long)buf, len, rv);
      errno = errno_saved;
      return rv;
  }
@@ -521,23 +546,26 @@
 
 =head2 Socket Connection Operations
 
+This API part provides operations for stream-oriented data communication
+through the socket abstraction C<sa_t>.
+
 =over 4
 
-=item sa_rc_t B<sa_bind>(sa_t *I<sa>, sa_addr_t *I<laddr>);
+=item C<sa_rc_t >B<sa_bind>C<(sa_t *>I<sa>C<, sa_addr_t *>I<laddr>C<);>
 
 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
+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
+sa_listen(3)) for incoming connections, for clients this is the address
+used for outgoing connections (see sa_connect(3)). 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>);
+=item C<sa_rc_t >B<sa_connect>C<(sa_t *>I<sa>C<, sa_addr_t *>I<raddr>C<);>
 
 Initiate an outgoing connection on a socket abstraction object.
 
@@ -551,7 +579,7 @@
 
 Example: C<sa_connect(sa, raddr);>
 
-=item sa_rc_t B<sa_listen>(sa_t *I<sa>, int I<backlog>);
+=item C<sa_rc_t >B<sa_listen>C<(sa_t *>I<sa>C<, int >I<backlog>C<);>
 
 Listen for incoming connections on a socket abstraction object.
 
@@ -562,7 +590,7 @@
 
 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>);
+=item C<sa_rc_t >B<sa_accept>C<(sa_t *>I<sa>C<, sa_addr_t **>I<caddr>C<, sa_t **>I<csa>C<);>
 
 Accept incoming connection on a socket abstraction object.
 
@@ -583,7 +611,9 @@
      ...
  }
 
-=item sa_rc_t B<sa_getremote>(sa_t *I<sa>, sa_addr_t **I<raddr>);
+=item C<sa_rc_t >B<sa_getremote>C<(sa_t *>I<sa>C<, sa_addr_t **>I<raddr>C<);>
+
+FIXME
 
 =item sa_rc_t B<sa_getlocal>(sa_t *I<sa>, sa_addr_t **I<laddr>);