*** /dev/null Sat Nov 23 01:26:37 2024
--- - Sat Nov 23 01:26:43 2024
***************
*** 0 ****
--- 1,219 ----
+ ##
+ ## SA - OSSP Socket Abstraction Library
+ ## Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
+ ## Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
+ ##
+ ## This file is part of OSSP SA, a socket abstraction library which
+ ## can be found at http://www.ossp.org/pkg/sa/.
+ ##
+ ## Permission to use, copy, modify, and distribute this software for
+ ## any purpose with or without fee is hereby granted, provided that
+ ## the above copyright notice and this permission notice appear in all
+ ## copies.
+ ##
+ ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+ ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ ## SUCH DAMAGE.
+ ##
+ ## sa.pod: socket abstraction library manual page
+ ##
+
+ =pod
+
+ =head1 NAME
+
+ B<OSSP sa> - Socket Abstraction Library
+
+ =head1 SYNOPSIS
+
+ =over 4
+
+ =item B<Abstract Data Types>:
+
+ sa_addr_t,
+ sa_t.
+
+ =item B<Address Operations>:
+
+ sa_u2a,
+ sa_s2a,
+ sa_a2u,
+ sa_a2s.
+
+ =item B<Object Operations>:
+
+ sa_create,
+ sa_destroy.
+
+ =item B<Parameter Operations>:
+
+ sa_timeout,
+ sa_buffers.
+
+ =item B<Connection Operations>:
+
+ sa_bind,
+ sa_connect,
+ sa_listen,
+ sa_accept,
+ sa_getremote,
+ sa_getlocal,
+ sa_shutdown.
+
+ =item B<Input/Output Operations>:
+
+ sa_read,
+ sa_readfrom,
+ sa_readline,
+ sa_write,
+ sa_writeto,
+ sa_printf,
+ sa_flush.
+
+ =back
+
+ =head1 DESCRIPTION
+
+ B<OSSP sa> is a thin abstraction library for the BSD socket interface
+ for use in conjunction with TCP and UDP protocols. It provides the
+ following key features:
+
+ =over 4
+
+ =item B<Address Abstraction>
+
+ Most of the uglyness in the BSD socket API is the necessarity to have to
+ deal with the various address structures (C<struct sockaddr_xx>) which
+ exist because of both the different network protocols and addressing
+ schemes. B<OSSP sa> fully hides this by providing an abstract and
+ opaque address type (C<sa_addr_t>) together with four utility functions
+ which allow one to convert from the old C<struct sockaddr> and an URL
+ specification (C<{tcp,udp}://<host>[:<port>]>) to the C<sa_addr_t> and
+ vice versa.
+
+ =item B<I/O Timeouts>
+
+ Each function of B<OSSP sa> is aware of a central timeout (set by
+ sa_timeout(3)), i.e., all I/O operations return C<SA_ERR_SYS> and
+ C<errno> set to C<ETIMEDOUT> if this timeout expired before the
+ operation was able to succeed. This allows one to easily program
+ less-blocking network services.
+
+ =item B<Buffered I/O>
+
+ If B<OSSP sa> is used for TCP-based stream I/O, internally all I/O
+ operations can be performed through input and output buffers (set
+ by sa_buffers(3)) for achieving higher I/O performance by doing I/O
+ operations on larger messages.
+
+ =item B<Convinience I/O Functions>
+
+ If B<OSSP sa> is used for TCP-based stream I/O, for convinience reasons
+ line reading (sa_readline(3)) and output formatting (sa_printf(3))
+ functions are provided, modelled after STDIO's fgets(3) and fprintf(3).
+
+ =back
+
+ =head1 DATA TYPES
+
+ =over 4
+
+ =item B<sa_addr_t>
+
+ =item B<sa_t>
+
+ =back
+
+ =head1 FUNCTIONS
+
+ =head2 Address Operations
+
+ =over 4
+
+ =item sa_rc_t B<sa_u2a>(sa_addr_t **I<saa>, const char *I<uri>, ...);
+
+ =item sa_rc_t B<sa_s2a>(sa_addr_t **I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);
+
+ =item sa_rc_t B<sa_a2u>(const sa_addr_t *I<saa>, char **I<uri>);
+
+ =item sa_rc_t B<sa_a2s>(const sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);
+
+ =back
+
+ =head2 Object Operations
+
+ =over 4
+
+ =item sa_rc_t B<sa_create>(sa_t **I<sa>);
+
+ =item sa_rc_t B<sa_destroy>(sa_t *I<sa>);
+
+ =back
+
+ =head2 Parameter Operations
+
+ =over 4
+
+ =item sa_rc_t B<sa_timeout>(sa_t *I<sa>, long I<sec>, long I<usec>);
+
+ =item sa_rc_t B<sa_buffers>(sa_t *I<sa>, size_t I<rsize>, size_t I<wsize>);
+
+ =back
+
+ =head2 Connection Operations
+
+ =over 4
+
+ =item sa_rc_t B<sa_bind>(sa_t *I<sa>, sa_addr_t *I<laddr>);
+
+ =item sa_rc_t B<sa_connect>(sa_t *I<sa>, sa_addr_t *I<raddr>);
+
+ =item sa_rc_t B<sa_listen>(sa_t *I<sa>, int I<backlog>);
+
+ =item sa_rc_t B<sa_accept>(sa_t *I<sa>, sa_addr_t **I<caddr>, sa_t **I<csa>);
+
+ =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>);
+
+ =item sa_rc_t B<sa_shutdown>(sa_t *I<sa>, char *I<flags>);
+
+ =back
+
+ =head2 Input/Output Operations
+
+ =over 4
+
+ =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_readfrom>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t **I<raddr>);
+
+ =item sa_rc_t B<sa_readline>(sa_t *I<sa>, char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+
+ =item sa_rc_t B<sa_write>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>);
+
+ =item sa_rc_t B<sa_writeto>(sa_t *I<sa>, const char *I<buf>, size_t I<buflen>, size_t *I<bufdone>, sa_addr_t *I<raddr>);
+
+ =item sa_rc_t B<sa_printf>(sa_t *I<sa>, const char *I<fmt>, ...);
+
+ =item sa_rc_t B<sa_flush>(sa_t *I<sa>);
+
+ =back
+
+ =head1 AUTHORS
+
+ Ralf S. Engelschall
+ rse@engelschall.com
+ www.engelschall.com
+
+ =cut
+
|
