##
##  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,
sa_rc_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_getfd,
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_getfd>(sa_t *I<sa>, int *I<fd>);

=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 HISTORY

B<OSSP sa> was invented in August 2001 by Ralf S. Engelschall for use
inside the OSSP project. Its creation was prompted by the requirement
to implement an SMTP logging channel for B<OSSP l2> (logging library).
Its initial code was derived from a predecessor sub-library originally
written for socket address abstraction inside B<OSSP lmtp2nntp>.

=head1 AUTHORS

 Ralf S. Engelschall
 rse@engelschall.com
 www.engelschall.com

=cut