--- sa.pod 2001/10/31 20:27:27 1.16
+++ sa.pod 2001/10/31 20:51:01 1.17
@@ -232,33 +232,50 @@
Import an address by converting from an URI specification
to the corresponding address abstraction. The supported URI
-syntax is: "C<unix:>I<path>" for I<Unix Domain> addresses and
-"C<inet://>I<addr>C<:>I<port>" for I<Internet Domain> addresses.
+syntax is: C<unix:>I<path> for I<Unix Domain> addresses and
+C<inet://>I<addr>C<:>I<port>[C<#>I<protocol>] for I<Internet Domain>
+addresses.
+
I<path> can be an absolute or relative file path to an existing or
not-existing file. I<addr> can be an IPv4 address in dotted decimal
-notation (C<127.0.0.1>), an IPv6 address in colon-seperated (optionally
-shortended) hexadecimal notation (C<::1>) or a to-be-resolved hostname
-(C<localhost.example.com>). I<port> has to be a decimal port in the
-range C<1>...C<65535>.
+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. If I<port> is specified as a
+name, it is resolved as a TCP port by default. To force resolving via a
+particular protocol, I<protocol> can be specified as either C<tcp> or
+C<udp>.
=item sa_rc_t B<sa_addr_s2a>(sa_addr_t *I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
-Import an address by converting from a tranditional C<struct sockaddr> object to the
-corresponding address abstraction.
+Import an address by converting from a tranditional C<struct sockaddr> object
+to the corresponding address abstraction. The accepted addresses are: C<struct
+sockaddr_un> (C<AF_LOCAL>), C<struct sockaddr_in> (C<AF_INET>) and C<struct
+sockaddr_in6> (C<AF_INET6>).
=item sa_rc_t B<sa_addr_a2u>(sa_addr_t *I<saa>, char **I<uri>);
-Export an address by converting from the
-address abstraction to the corresponding URI specification.
+Export an address by converting from the address abstraction to the
+corresponding URI specification. The result is a string of the form
+C<unix:>I<path> for I<Unix Domain> addresses and (unresolved/numerical)
+C<inet://>I<addr>C<:>I<port> for I<Internet Domain> addresses. The
+caller has to free(3) the I<uri> later.
=item sa_rc_t B<sa_addr_a2s>(sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
-Export an address by converting from the
-address abstraction to the corresponding traditional C<struct sockaddr> object.
+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 caller has to free(3) the
+I<sabuf> later.
=item sa_rc_t B<sa_addr_match>(sa_addr_t *I<saa1>, sa_addr_t *I<saa2>, size_t I<prefixlen>);
-Match two address abstractions
+Match two address abstractions by only taking the prefix part of length
+I<prefixlen> into account. I<prefixlen> is number of path characters
+for I<Unix Domain> addresses and number of bits for I<Internet Domain>
+addresses.
=back
@@ -268,8 +285,12 @@
=item sa_rc_t B<sa_create>(sa_t **I<sa>);
+Create a socket abstraction object.
+
=item sa_rc_t B<sa_destroy>(sa_t *I<sa>);
+Destroy a socket abstraction object.
+
=back
=head2 Socket Parameter Operations
|
