##
##  SA - OSSP Socket Abstraction Library
##  Copyright (c) 2001 Ralf S. Engelschall <rse@engelschall.com>
##  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_rc_t,
sa_addr_t,
sa_t.

=item B<Address Object Operations>:

sa_addr_create,
sa_addr_destroy.

=item B<Address Operations>:

sa_addr_u2a,
sa_addr_s2a,
sa_addr_a2u,
sa_addr_a2s.
            
=item B<Socket Object Operations>:

sa_create,
sa_destroy. 
            
=item B<Socket Parameter Operations>:

sa_timeout,
sa_buffers. 
            
=item B<Socket Connection Operations>:

sa_bind,
sa_connect,
sa_listen,
sa_accept,  
sa_getremote,
sa_getlocal,
sa_getfd,
sa_shutdown.

=item B<Socket Input/Output Operations (Stream Communication)>:
            
sa_read,
sa_readln,
sa_write,
sa_writef,
sa_flush.   

=item B<Socket Input/Output Operations (Datagram Communication)>:

sa_recv,
sa_send.

=back

=head1 DESCRIPTION

B<OSSP sa> is an abstraction library for the Unix socket interface
featuring stream and datagram oriented communication over Unix Domain
and Internet Domain sockets.

It provides the following key features:

=over 4

=item B<Address Abstraction>

Most of the uglyness in the Unix 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 communication types 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 traditional C<struct
sockaddr> or URI specification to the C<sa_addr_t> and vice versa.

=item B<Type Abstraction>

Some other subtle details in the socket API make the life hard in
practice: C<socklen_t> and C<ssize_t>. These two types originally were
(and on some platforms still are) plain integers or unsigned integers
while POSIX later introduced own types for them. This is nasty, because
for full backward compatibility and type-correct API usage, every
application has to check whether the newer types exists and if not
provide own definitions which map to the still actually used integer
type on the underlying platform. B<OSSP sa> hides all this in its API.

=item B<I/O Timeouts>

Each I/O function in 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<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_buffers(3)) for achieving higher I/O performance by doing I/O
operations on larger aggregated messages.

=item B<Convinience I/O Functions>

If B<OSSP sa> is used for stream communication, for convinience reasons
line-oriented reading (sa_readln(3)) and formated writing (sa_writef(3))
is provided, modelled after STDIO's fgets(3) and fprintf(3).

=back

=head1 DATA TYPES

B<OSSP sa> uses three data types in its API:

=over 4

=item B<sa_rc_t> (Return Code Type)

This is an exported enumerated integer type with the following possible
values: C<SA_OK> (everything ok, operation succeeded); C<SA_ERR_ARG>
(invalid argument(s) passed to function); C<SA_ERR_USE> (function used
in wrong context); C<SA_ERR_MEM> (out of memory); C<SA_ERR_EOF> (end of
file/socket in communication); C<SA_ERR_SYS> (operating system error;
errno contains details); C<SA_ERR_INT> (any other internal error).

=item B<sa_addr_t> (Socket Address Abstraction Type)

This is an opaque type representing a socket address. 
Only pointers to this abstract type are used in the API.

=item B<sa_t> (Socket Abstraction Type)

This is an opaque type representing a socket.
Only pointers to this abstract type are used in the API.

=back

=head1 FUNCTIONS

=head2 Address Object Operations

=over 4

=item sa_rc_t B<sa_addr_create>(sa_addr_t **I<saa>);

=item sa_rc_t B<sa_addr_destroy>(sa_addr_t *I<saa>);

=back

=head2 Address Operations

=over 4

=item sa_rc_t B<sa_addr_u2a>(sa_addr_t *I<saa>, const char *I<uri>, ...);

=item sa_rc_t B<sa_addr_s2a>(sa_addr_t *I<saa>, const struct sockaddr *I<sabuf>, socklen_t I<salen>);

=item sa_rc_t B<sa_addr_a2u>(sa_addr_t *I<saa>, char **I<uri>);

=item sa_rc_t B<sa_addr_a2s>(sa_addr_t *I<saa>, struct sockaddr **I<sabuf>, socklen_t *I<salen>);

=back
            
=head2 Socket 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 Socket Parameter Operations

=over 4

=item sa_rc_t B<sa_type>(sa_t *I<sa>, sa_type_t I<type>);

=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>);

=item sa_rc_t B<sa_getoption>(sa_t *I<sa>, int I<optname>, void *I<optval>, socklen_t *I<optlen>);

=item sa_rc_t B<sa_setoption>(sa_t *I<sa>, int I<optname>, const void *I<optval>, socklen_t I<optlen>);

=back

=head2 Socket 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 Socket Input/Output Operations (Stream Communication)

=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_readln>(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_writef>(sa_t *I<sa>, const char *I<fmt>, ...);

=item sa_rc_t B<sa_flush>(sa_t *I<sa>);

=back

=head2 Socket Input/Output Operations (Stream Communication)

=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>);

=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>);

=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