--- sa.pod 2002/10/26 17:59:30 1.32
+++ sa.pod 2002/10/26 18:28:16 1.33
@@ -618,26 +618,26 @@
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).
+sa_addr_destroy(3). Internally this maps to getpeername(2).
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 C<sa_rc_t >B<sa_getlocal>C<(sa_t *>I<sa>C<, sa_addr_t **>I<laddr>C<);>
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).
+later with sa_addr_destroy(3). Internally this maps to getsockname(2).
Example: C<sa_addr_t *laddr; sa_getlocal(sa, &laddr);>
-=item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
+=item C<sa_rc_t >B<sa_shutdown>C<(sa_t *>I<sa>C<, char *>I<flags>C<);>
Shut down part of the full-duplex connection.
-This performs a shut down of the connection descriped in I<sa>. The
+This performs a shut down of the connection described 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
@@ -655,7 +655,7 @@
=over 4
-=item sa_rc_t B<sa_getfd>(sa_t *I<sa>, int *I<fd>);
+=item C<sa_rc_t >B<sa_getfd>C<(sa_t *>I<sa>C<, int *>I<fd>C<);>
Get underlying socket filedescriptor.
@@ -672,37 +672,123 @@
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 C<sa_rc_t >B<sa_read>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
-=item sa_rc_t B<sa_readln>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+Read a chunk of data from socket into own buffer.
-=item sa_rc_t B<sa_write>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+This reads from the socket (optionally through the internal read buffer)
+up to a maximum of I<buflen> bytes into buffer I<buf>. The actual number
+of read bytes is stored in I<bufdone>. This internally maps to read(2).
-=item sa_rc_t B<sa_writef>(sa_t *I<sa>, const char *I<fmt>, ...);
+Example: C<char buf[1024]; size_t n; sa_read(sa, buf, sizeof(buf), &n);>
-=item sa_rc_t B<sa_flush>(sa_t *I<sa>);
+=item C<sa_rc_t >B<sa_readln>C<(sa_t *>I<sa>C<, char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
+
+Read a line of data from socket into own buffer.
+
+This reads from the socket (optionally through the internal read buffer)
+up to a maximum of I<buflen> bytes into buffer I<buf>, but only as long
+as no line terminating newline character (0x0a) was found. The line
+terminating newline character is stored in the buffer, too. The actual
+number of read bytes is stored in I<bufdone>. This internally maps to
+sa_read(3).
+
+Keep in mind that for efficiency reasons, line-oriented I/O usually
+always should be performed with read buffer (see sa_option(3) and
+C<SA_BUFFER_READ>). Without such a read buffer, the performance is
+cruel, because single character read(2) operations would be performed on
+the underlying socket.
+
+Example: C<char buf[1024]; size_t n; sa_readln(sa, buf, sizeof(buf), &n);>
+
+=item C<sa_rc_t >B<sa_write>C<(sa_t *>I<sa>C<, const char *>I<buf>C<, size_t >I<buflen>C<, size_t *>I<bufdone>C<);>
+
+Write a chunk of data to socket from own buffer.
+
+This writes to the socket (optionally through the internal write buffer)
+I<buflen> bytes from buffer I<buf>. In case of a partial write, the
+actual number of written bytes is stored in I<bufdone>. This internally
+maps to write(2).
+
+Example: C<sa_write(sa, cp, strlen(cp), NULL);>
+
+=item C<sa_rc_t >B<sa_writef>C<(sa_t *>I<sa>C<, const char *>I<fmt>C<, ...);>
+
+Write formatted data data to socket.
+
+This formats a string according to the printf(3)-style format
+specification I<fmt> and sends the result to the socket (optionally
+through the internal write buffer). In case of a partial socket
+write, the not written data of the formatted string is internally
+discarded. Hence using a write buffer is strongly recommended here
+(see sa_option(3) and C<SA_BUFFER_WRITE>). This internally maps to
+sa_write(3).
+
+The underlying string formatting engine is just a minimal one and for
+security and independence reasons intentionally not directly based on
+s[n]printf(3). It understands only the following format specifications:
+"C<%%>", "C<%c>" (C<char>), "C<%s>" (C<char *>) and "C<%d>" (C<int>)
+without any precision and padding possibilities. It is intended for
+minimal formatting only. If you need more sophisticated formatting, you
+have to format first into an own buffer via s[n]printf(3) and then write
+this to the socket via sa_write(3) instead.
+
+Example: C<sa_writef(sa, "%s=%d\n", cp, i);>
+
+=item C<sa_rc_t >B<sa_flush>C<(sa_t *>I<sa>C<);>
+
+Flush still pending outgoing data to socket.
+
+This writes all still pending outgoing data for the internal write
+buffer (see sa_option(3) and C<SA_BUFFER_WRITE>) to the socket. This
+internally maps to write(2).
+
+Example: C<sa_flush(sa);>
=back
=head2 Socket Input/Output Operations (Datagram Communication)
-This API part provides operations for datagram-oriented data
+This API part provides I/O operations for datagram-oriented data
communication through the socket abstraction C<sa_t>.
=over 4
=item sa_rc_t B<sa_recv>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t **I<raddr>);
+Receive a chunk of data from remote address via socket into own buffer.
+
+This receives from the remote address specified in I<raddr> via the
+socket up to a maximum of I<buflen> bytes into buffer I<buf>. The actual
+number of received bytes is stored in I<bufdone>. This internally maps
+to recvfrom(2).
+
+Example: C<char buf[1024]; size_t n; sa_recv(sa, buf, sizeof(buf), &n, saa);>
+
=item sa_rc_t B<sa_send>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t *I<raddr>);
+Send a chunk of data to remote address via socket from own buffer.
+
+This sends to the remote address specified in I<raddr> via the socket
+I<buflen> bytes from buffer I<buf>. The actual number of sent bytes is
+stored in I<bufdone>. This internally maps to sendto(2).
+
+Example: C<sa_send(sa, buf, strlen(buf), NULL, saa);>
+
=back
=head2 Socket Error Handling
+This API part provides error handling operations only.
+
=over 4
=item char *B<sa_error>(sa_rc_t I<rv>);
+Return the string representation corresponding to the return code
+value I<rv>. The returned string has to be treated read-only by the
+application and is not required to be deallocated.
+
=back
=head1 SEE ALSO
@@ -710,43 +796,43 @@
=head2 Standards
R. Gilligan, S. Thomson, J. Bound, W. Stevens:
-"Basic Socket Interface Extensions for IPv6",
-RFC 2553, March 1999.
+I<"Basic Socket Interface Extensions for IPv6">,
+B<RFC 2553>, March 1999.
W. Stevens:
-"Advanced Sockets API for IPv6",
+I<"Advanced Sockets API for IPv6">,
B<RFC 2292>, February 1998.
R. Fielding, L. Masinter, T. Berners-Lee:
-"Uniform Resource Identifiers: Generic Syntax",
+I<"Uniform Resource Identifiers: Generic Syntax">,
B<RFC 2396>, August 1998.
R. Hinden, S. Deering:
-"IP Version 6 Addressing Architecture",
+I<"IP Version 6 Addressing Architecture">,
B<RFC 2373>, July 1998.
R. Hinden, B. Carpenter, L. Masinter:
-"Format for Literal IPv6 Addresses in URL's",
+I<"Format for Literal IPv6 Addresses in URL's">,
B<RFC 2732>, December 1999.
=head2 Papers
Stuart Sechrest:
-"An Introductory 4.4BSD Interprocess Communication Tutorial",
+I<"An Introductory 4.4BSD Interprocess Communication Tutorial">,
FreeBSD 4.4 (/usr/share/doc/psd/20.ipctut/).
Samuel J. Leffler, Robert S. Fabry, William N. Joy, Phil Lapsley:
-"An Advanced 4.4BSD Interprocess Communication Tutorial",
+I<"An Advanced 4.4BSD Interprocess Communication Tutorial">,
FreeBSD 4.4 (/usr/share/doc/psd/21.ipc/).
Craig Metz:
-"Protocol Independence Using the Sockets API"
+I<"Protocol Independence Using the Sockets API">,
http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html,
USENIX Annual Technical Conference, June 2000.
=head2 Manual Pages
-socket(2)
+socket(2),
accept(2),
bind(2),
connect(2),
@@ -763,7 +849,7 @@
socketpair(2),
write(2),
getprotoent(3),
-protocols(4)
+protocols(4).
=head1 HISTORY
@@ -775,7 +861,7 @@
derived from a predecessor sub-library originally written for socket
address abstraction inside B<OSSP lmtp2nntp>.
-=head1 AUTHORS
+=head1 AUTHOR
Ralf S. Engelschall
rse@engelschall.com
|
